本地代码知识库同步 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：读取文件的指定行范围，获取精确的代码片段
快速开始
安装与配置
-
克隆仓库
git clone https://github.com/cytrogen/mcp-local-sync.git cd mcp-local-sync -
安装依赖
npm install yarn install -
配置同步路径
-
打开
src/index.ts文件 -
找到
SYNC_PATHS这个常量数组 -
将其中的示例路径替换为你自己电脑上希望同步的项目的绝对路径。你可以配置一个或多个路径：
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
如果文件或目录不存在，请手动创建它。
- Windows：
-
添加 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