Local Project Sync

本地代码知识库同步 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
配置同步路径
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
})

组合使用示例

// 完整的代码探索流程
analyze_project_structure() // 了解架构
search_code_content({query: "UserService", useRegex: false}) // 找到位置
extract_function_definition({functionName: "createUser"}) // 提取具体方法
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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

A Model Context Protocol (MCP) server that enables AI applications to access and analyze local code repositories without manual uploads, providing file listing, content reading, code searching, and project structure analysis capabilities.

Related MCP Servers

MCP Local File Reader
sworddut
-
security
A
license
-
quality
A Model Context Protocol (MCP) server that allows AI models to safely access and interact with local file systems, enabling reading file contents, listing directories, and retrieving file metadata.
Last updated -
13
9
JavaScript
MIT License
AgentModeofficial
agentmode
A
security
F
license
A
quality
An all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.
Last updated -
2
Python
Google Research MCP
mixelpixx
-
security
A
license
-
quality
Model Context Protocol (MCP) server that provides AI assistants with advanced web research capabilities, including Google search integration, intelligent content extraction, and multi-source synthesis.
Last updated -
28
3
TypeScript
MIT License
File MCP Server
d-issy
A
security
F
license
A
quality
A Model Context Protocol (MCP) server that enables AI assistants to perform comprehensive file operations including finding, reading, writing, editing, searching, moving, and copying files with security validations.
Last updated -
7
TypeScript

View all related MCP servers