README.md•6.28 kB
# 本地代码知识库同步 MCP 工具
这是一个基于 **模型上下文协议**（Model Context Protocol, MCP）开发的服务端工具，旨在将你的本地项目代码目录无缝连接到支持 MCP 的 AI 应用（如 Claude 桌面版），从而将你的本地代码库变成一个可供 AI 实时查询和分析的动态知识库。
你不再需要手动上传文件或依赖云端仓库同步，AI 可以直接与你本地最新的代码进行交互。
## 主要功能
本项目通过实现多个 MCP 工具，为 AI 提供了与本地文件系统交互的超能力：
### 基础工具
1. `list_project_files`：递归地列出所有已配置目录中的文件，提供项目全貌
2. `read_file_content`：读取单个指定文件的完整内容，用于深度代码分析
3. `analyze_project_structure`：生成项目结构的概览和统计信息，帮助快速了解项目
### 智能搜索工具
1. `search_code_content`：在整个代码库中进行智能搜索，支持：
- 普通文本搜索和正则表达式搜索
- 深层目录结构精确定位
- 可配置的上下文行数，避免返回过多内容
- 文件类型过滤和结果数量控制
### 高效读取工具
1. `read_multiple_files`：使用 `glob` 模式批量读取多个文件的内容，方便提供模块级上下文
2. `extract_function_definition`：精确提取指定函数/方法的完整定义，包括注释和装饰器
3. `read_file_section`：读取文件的指定行范围，获取精确的代码片段
## 快速开始
### 安装与配置
1. 克隆仓库
```bash
git clone https://github.com/cytrogen/mcp-local-sync.git
cd mcp-local-sync
```
2. 安装依赖
```bash
npm install
yarn install
```
3. 配置同步路径
1. 打开 `src/index.ts` 文件
2. 找到 `SYNC_PATHS` 这个常量数组
3. 将其中的示例路径替换为你自己电脑上希望同步的项目的绝对路径。你可以配置一个或多个路径：
```ts src/index.ts
const SYNC_PATHS = [
"D:\\your\\project\\directory\\src",
"D:\\another\\project\\directory\\src"
];
```
4. 构建项目
运行构建命令，将 TypeScript 代码编译为 JavaScript：
```bash
npm run build
yarn run build
```
成功后，会在项目根目录下生成一个 `build` 文件夹。
### 连接到 Claude 桌面版
1. 找到并编辑 Claude 配置文件：
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
_如果文件或目录不存在，请手动创建它。_
2. 添加 MCP 服务器配置
将以下 JSON 内容添加到配置文件中（注意：必须将 `args` 中的路径替换为你自己项目 `build/index.js` 文件的绝对路径）：
```json
{
"mcpServers": {
"localProjectSync": {
"command": "node",
"args": [
"D:\\path\\to\\your\\mcp-local-sync\\build\\index.js"
]
}
}
}
```
3. 重启 Claude
完全退出并重新启动 Claude 桌面应用。成功后，你可以在聊天输入框下的 `Search and Tools` 菜单项内看到 `localProjectSync` 这个工具。
## 使用示例
### 基础项目探索
```javascript
// 1. 了解项目结构
list_project_files()
// 2. 分析项目架构
analyze_project_structure({
scope: "backend",
depth: 3
})
```
### 智能代码搜索
```javascript
// 普通文本搜索
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
})
```
### 精确代码提取
```javascript
// 提取完整函数定义（推荐用法）
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
})
```
### 批量文件分析
```javascript
// 读取模块内的所有服务
read_multiple_files({
patterns: ["modules/*/services/*.service.ts"],
maxFiles: 10
})
// 读取配置相关文件
read_multiple_files({
patterns: ["config/*.ts", "*.config.ts"],
maxFiles: 5
})
```
### 组合使用示例
```text
// 完整的代码探索流程
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"]}) // 查看相关文件
```
### 高级搜索技巧
```javascript
// 查找所有 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`