本地代码知识库同步 MCP 工具

这是一个基于 模型上下文协议（Model Context Protocol, MCP）开发的服务端工具，旨在将你的本地项目代码目录无缝连接到支持 MCP 的 AI 应用（如 Claude 桌面版），从而将你的本地代码库变成一个可供 AI 实时查询和分析的动态知识库。

你不再需要手动上传文件或依赖云端仓库同步，AI 可以直接与你本地最新的代码进行交互。

主要功能

本项目通过实现多个 MCP 工具，为 AI 提供了与本地文件系统交互的超能力：

基础工具

list_project_files：递归地列出所有已配置目录中的文件，提供项目全貌
read_file_content：读取单个指定文件的完整内容，用于深度代码分析
analyze_project_structure：生成项目结构的概览和统计信息，帮助快速了解项目

智能搜索工具

search_code_content：在整个代码库中进行智能搜索，支持：
- 普通文本搜索和正则表达式搜索
- 深层目录结构精确定位
- 可配置的上下文行数，避免返回过多内容
- 文件类型过滤和结果数量控制

高效读取工具

read_multiple_files：使用 glob 模式批量读取多个文件的内容，方便提供模块级上下文
extract_function_definition：精确提取指定函数/方法的完整定义，包括注释和装饰器
read_file_section：读取文件的指定行范围，获取精确的代码片段

Related MCP server: AgentMode

快速开始

安装与配置

克隆仓库
git clone https://github.com/cytrogen/mcp-local-sync.git cd mcp-local-sync
安装依赖
npm install yarn install
配置同步路径
1. 打开 src/index.ts 文件
2. 找到 SYNC_PATHS 这个常量数组
3. 将其中的示例路径替换为你自己电脑上希望同步的项目的绝对路径。你可以配置一个或多个路径：
  const SYNC_PATHS = [ "D:\\your\\project\\directory\\src", "D:\\another\\project\\directory\\src" ];
构建项目
运行构建命令，将 TypeScript 代码编译为 JavaScript：
npm run build yarn run build
成功后，会在项目根目录下生成一个 build 文件夹。

连接到 Claude 桌面版

找到并编辑 Claude 配置文件：
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
如果文件或目录不存在，请手动创建它。
添加 MCP 服务器配置
将以下 JSON 内容添加到配置文件中（注意：必须将 args 中的路径替换为你自己项目 build/index.js 文件的绝对路径）：
{ "mcpServers": { "localProjectSync": { "command": "node", "args": [ "D:\\path\\to\\your\\mcp-local-sync\\build\\index.js" ] } } }
重启 Claude
完全退出并重新启动 Claude 桌面应用。成功后，你可以在聊天输入框下的 Search and Tools 菜单项内看到 localProjectSync 这个工具。

使用示例

基础项目探索

// 1. 了解项目结构 list_project_files() // 2. 分析项目架构 analyze_project_structure({ scope: "backend", depth: 3 })

智能代码搜索

// 普通文本搜索 search_code_content({ query: "EmailTemplateService", fileTypes: [".ts"], maxResults: 10 }) // 正则表达式搜索多个方法 search_code_content({ query: "markFieldProblems|requestClientRevision|submitRevision", fileTypes: [".ts", ".js"], maxResults: 10, useRegex: true }) // 搜索并返回上下文 search_code_content({ query: "async function", contextLines: 5, // 前后各5行上下文 maxResults: 8 })

精确代码提取

// 提取完整函数定义（推荐用法） extract_function_definition({ filePath: "[backend/src]/modules/email/services/email-template.service.ts", functionName: "renderTemplate", includeComments: true, includeDecorators: true }) // 读取指定行范围 read_file_section({ filePath: "[backend/src]/main.ts", startLine: 1, endLine: 50, showLineNumbers: true })

批量文件分析

// 读取模块内的所有服务 read_multiple_files({ patterns: ["modules/*/services/*.service.ts"], maxFiles: 10 }) // 读取配置相关文件 read_multiple_files({ patterns: ["config/*.ts", "*.config.ts"], maxFiles: 5 })

组合使用示例

// 完整的代码探索流程 1. analyze_project_structure() // 了解架构 2. search_code_content({query: "UserService", useRegex: false}) // 找到位置 3. extract_function_definition({functionName: "createUser"}) // 提取具体方法 4. read_multiple_files({patterns: ["**/user*.ts"]}) // 查看相关文件

高级搜索技巧

// 查找所有 service 类 search_code_content({ query: "export class.*Service", useRegex: true, fileTypes: [".ts"] }) // 查找特定装饰器的使用 search_code_content({ query: "@Injectable|@Controller|@Service", useRegex: true, contextLines: 3 })

注意事项

安全: 本工具具有读取指定目录内所有文件的权限。请确保你配置的 SYNC_PATHS 指向的是安全的项目目录，切勿将其指向包含敏感信息（如私钥、密码文件等）的系统目录
性能: 对于包含数十万个文件的超大型项目，list_project_files 和 search_code_content 的首次执行可能会比较慢
路径格式: 在与 AI 交互时，请尽量使用工具返回的、带前缀的完整文件路径（例如 [backend/src]/main.ts），以确保 AI 能准确调用工具

更新日志

v3.0.0

新增 extract_function_definition 工具
新增 read_file_section 工具
search_code_content 支持正则表达式和上下文行
修复深层目录搜索问题
优化conversation length使用

v2.0.0

新增 search_code_content 和 read_multiple_files
新增 analyze_project_structure

Deploy Server

A

security – no known vulnerabilities

F

license - not found

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Local Project Sync