Skip to main content
Glama

Local Project Sync

by Cytrogen
README.md6.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`

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Cytrogen/local-project-sync'

If you have feedback or need assistance with the MCP directory API, please join our Discord server