内容
# Synapse MCP
[](https://github.com/Eltortilla1/synapse-code-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](#开发)
> 一个结构化代码上下文服务器，通过[模型上下文协议](https://modelcontextprotocol.io)将您的本地仓库连接到AI助手。
与将文件复制到提示符相比，Synapse允许您的AI助手动态探索您的代码库 - 只需在需要时提取所需的代码。结果：减少上下文浪费，获得更智能的答案，以及一个可扩展到大型项目的workflow，无需设置向量数据库或嵌入式API。
```
AI 助手 ──MCP──► Synapse MCP ──fs/git──► 您的仓库
（拉取） （服务器） （本地）
```
> **状态：** 早期阶段，积极开发中。欢迎贡献和错误报告 - 请参阅[贡献](#贡献)。
---
## 为什么选择Synapse？
大多数AI编码工具已经索引文件。Synapse解决了一个不同的问题：**大规模上下文质量**。
| 问题 | Synapse解决方案 |
|---|---|
| 读取整个文件时只需要其API表面 | `get_semantic_context`，使用`outline_only` - 仅签名，≤ 50％完整内容 |
| AI不知道在不熟悉的项目中存在哪些文件 | `get_project_index` - 完整的符号映射，≤ 40％原始源大小，一次调用 |
| “审查我的更改”需要手动粘贴差异 | `get_changed_files` - 结构化的git差异，默认情况下git感知 |
| 依赖关系兔子洞填充上下文窗口 | 可配置的`depth`上限导入遍历 |
上述压缩比率作为自动测试预算强制执行 - 不是营销估计。
### 为什么不使用向量嵌入？
大多数代码上下文MCP服务器使用由向量数据库（例如Milvus，Qdrant）和嵌入式API（OpenAI，VoyageAI）支持的语义搜索。这使它们具有Synapse所没有的真正能力：根据概念含义查找代码（“查找身份验证逻辑”）而不是根据结构或文本。
Synapse用一套不同的属性来权衡这种能力：
- **零外部依赖** - 无需API密钥，无需向量数据库，无需配置嵌入式提供程序
- **零循环成本** - 无需按令牌计费的嵌入式费用，无需托管数据库账单
- **完全本地和确定性** - 相同的输入始终产生相同的输出，机器上没有任何内容离开，任何时候都不需要索引
- **在任何仓库上立即启动** - 首次使用前无需索引步骤（请参阅[性能](#性能)：120–257毫秒在真实仓库上）
如果您需要跨多个语言的数百万行代码进行自然语言语义搜索，则向量支持的服务器是更好的工具。如果您想要结构化上下文（签名，依赖关系图，差异）而不建立基础设施，Synapse就是为您而建。
---
## 工具
### `get_project_index`
返回项目的压缩语义映射：所有导出的函数、类、接口和类型及其签名 - 没有函数体。在探索不熟悉的代码库时，这是正确的第一个调用。
```
# 项目索引：my-app（47个文件，312个符号）
## src/services/user-service.ts
UserService（类）[导出]
构造函数（db：Database）
findById（id：string）：Promise<User | null>
create（data：CreateUserDto）：Promise<User>
## src/models/user.ts
User（接口）[导出]
id：string
email：string
createdAt：Date
createUser（data：Partial<User>）：User [导出]
```
**参数：** `file_pattern`（全局模式，用于缩小范围），`include_non_exported`
> **大型项目：** 输出随着导出的符号数量线性增长。对于具有500+文件的monorepo或项目，使用`file_pattern`将索引范围缩小到一次一个区域 - 例如`"src/services/**/*.ts"`。
---
### `get_semantic_context`
在文件的本地依赖关系图中返回文件的内容 - AI需要的所有内容来理解代码上下文。
添加`outline_only: true`以获取签名而无需实现主体。输出受基准测试套件的约束，确保内容长度≤ 50％，同时保留完整的结构理解。
**参数：** `file_path`（必填），`depth`（导入跳转，默认：2），`outline_only`
---
### `get_changed_files`
列出自git引用以来更改的文件，按状态分组（添加/修改/删除/重命名），并可选地包含行数和完整统一差异。
```
自 `main` 以来更改的文件（8 个文件）：
**已添加（2）：**
src/services/payment.ts (+120 −0)
tests/unit/payment.test.ts (+89 −0)
**已修改（5）：**
src/models/order.ts (+14 −3)
...
**摘要：** +245 −18 行
```
**参数：** `base_ref`（默认：`HEAD~1`），`include_diff`，`file_pattern`
---
### `get_project_tree`
存储库的结构化视图，遵循 `.gitignore` 规则。
**参数：** `path`，`max_depth`，`show_hidden`
---
### `search_codebase`
在项目中快速进行文本或正则表达式搜索，返回带有文件路径和行号的匹配项。当可用时使用 [ripgrep](https://github.com/BurntSushi/ripgrep)，否则使用纯Node.js扫描器。
**参数：** `query`（必填），`file_pattern`，`is_regex`，`max_results`
---
## 语言支持
Synapse使用 [ts-morph](https://ts-morph.com)（TypeScript编译器API）对TypeScript和JavaScript进行深入分析。对于其他语言，它使用基于正则表达式的函数和类名提取。
| 功能 | TypeScript / JS | Python · Go · Rust | 其他 |
|---|---|---|---|
| `get_project_tree` | ✓ | ✓ | ✓ |
| `search_codebase` | ✓ | ✓ | ✓ |
| `get_semantic_context` — 完整源代码 | ✓ | ✓ | ✓ |
| `get_semantic_context` — 依赖关系图 | ✓ | — | — |
| `get_semantic_context outline_only` | ✓ 完整签名 | ✓ 仅限名称 | — |
| `get_project_index` | ✓ 完整签名 | ✓ 仅限名称 | — |
依赖关系图遍历（跟随`import`/`require`链）仅限于TypeScript/JavaScript。对于所有其他语言，Synapse仍然正常读取和搜索文件 - 它只是不会遍历导入图。
> **限制：** 依赖关系图遍历仅跟随**相对**导入（`./foo`，`../bar`）。通过`tsconfig.json` `paths`配置的路径别名（例如`@/components/Foo`）不会被解析，并且将被静默跳过 - 对于严重依赖别名导入的项目，依赖关系图将不完整。解决别名的支持在[路线图](ROADMAP.md)中跟踪。
---
## 安装
**全局安装（推荐）：**
```bash
npm install -g synapse-code-mcp
```
**无需安装即可运行：**
```bash
npx synapse-code-mcp --root /path/to/your/project
```
---
## 设置
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["synapse-code-mcp", "--root", "/absolute/path/to/your/project"]
}
}
}
```
### Claude Code（CLI）
```bash
claude mcp add synapse -- npx synapse-code-mcp --root /path/to/your/project
```
或直接添加到 `~/.claude/settings.json`:
```json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
}
}
}
```
### Cursor
将以下内容添加到 `.cursor/mcp.json`，位于您的主目录或项目根目录：
```json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
}
}
}
```
### Windsurf
将以下内容添加到 `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
}
}
}
```
> **提示：** 将 `/path/to/your/project` 替换为要服务的仓库的绝对路径。您可以运行多个Synapse实例 - 每个项目一个，每个项目在 `mcpServers` 下都有不同的密钥。
---
## 配置
### CLI标志
```
选项：
--root <path> 项目根目录（默认：cwd）
--max-file-size <bytes> 跳过大于此大小的文件（默认：524288 = 512 KB）
--max-search-results <n> 搜索结果上限（默认：50）
--max-tree-depth <n> 树视图的最大目录深度（默认：5）
--max-dependency-depth <n> 语义上下文的导入跳转（默认：2）
--log-level <level> 调试 | 信息 | 警告 | 错误（默认：信息）
```
### 每个项目的配置文件
在项目根目录下放置一个 `synapse.config.json` 文件，以覆盖该项目的默认值：
```json
{
"maxFileSize": 1048576,
"maxDependencyDepth": 3,
"extraIgnorePatterns": ["*.generated.ts", "**/__mocks__/**"]
}
```
所有字段都是可选的。CLI标志优先于`synapse.config.json`。
### 性能
在真实的开源TypeScript仓库中测量（单次运行， `--depth 1` 克隆，无预热缓存）：
| 仓库 | 索引文件 | 时间 | 堆增长 |
|---|---|---|---|
| [zod](https://github.com/colinhacks/zod) | 55 | **120毫秒** | 3 MB |
| [TypeScript编译器](https://github.com/microsoft/TypeScript) `src/` | 247 | **257毫秒** | 24 MB |
自动基准测试套件在合成测试用例（3000个最小`.ts`文件）上强制执行上限，以防止在最坏情况下出现回归：
| 操作 | CI预算（合成测试用例） |
|---|---|
| `get_project_tree` — 3000个文件 | 5秒 |
| `get_semantic_context` — 深度3 | 10秒 |
| `get_changed_files` | 2秒 |
| `get_project_index` — 60个文件 | 30秒 |
| `get_project_index` — 600个文件 | 120秒 |
CI预算是宽松的安全裕度，而不是性能估计 - 它们的存在是为了防止灾难性的回归（例如意外的O（n²）错误），而不是预测实际时间。上面的真实仓库数字是预期性能的有意义参考。对于大型monorepo（1000+文件），使用`file_pattern`将索引范围缩小到一次一个区域。
---
## 安全
Synapse是一个**只读**服务器。它永远不会写入文件系统或修改git仓库。
- **路径遍历保护** - 每个文件读取都经过`resolveAndValidate(root, path)`，如果解析的路径逃离项目根目录，则会抛出`PATH_ESCAPE`错误。AI客户端接收错误代码，而非文件内容。
- **根目录范围** - 仅 `--root` 下的目录树可访问。指向外部的路径（例如 `../../etc/passwd`）在验证层被拒绝。
- **文件大小上限** - 大于 `maxFileSize`（默认512 KB）的文件在读取前被拒绝。
- **二进制检测** - 编译后的工件和二进制文件被自动检测和跳过。
- **无外部网络调用** - Synapse仅通过本地stdio管道与MCP客户端通信。它不发出任何HTTP请求。
---
## 建议的工作流程
**探索新代码库：**
```
1. get_project_index()
→ 了解项目的完整结构，一次调用
2. get_semantic_context("src/core/engine.ts", outline_only: true)
→ 在不阅读实现的情况下检查模块的API表面
3. get_semantic_context("src/core/engine.ts")
→ 读取完整源代码 + 相关文件的依赖关系图
```
**代码审查前的PR：**
```
1. get_changed_files(base_ref: "main")
→ 查看更改内容，分类汇总
2. get_changed_files(base_ref: "main", include_diff: true)
→ 上下文中的完整统一差异
3. get_semantic_context("src/changed-file.ts")
→ 了解更改文件周围的上下文
```
**调试功能：**
```
1. search_codebase("handlePayment")
→ 查找符号的定义和使用位置
2. get_semantic_context("src/services/payment.ts", depth: 3)
→ 拉取文件 + 所有本地依赖项
```
---
## 需求
- **Node.js ≥ 18**
- **Git** - 仅 `get_changed_files` 需要
- **[ripgrep](https://github.com/BurntSushi/ripgrep)** *(可选)* - 显著提高搜索速度；如果 `$PATH` 上没有 `rg`，Synapse 将回退到纯 Node.js 扫描器
---
## 开发
```bash
git clone https://github.com/Eltortilla1/synapse-code-mcp.git
cd synapse-code-mcp
npm install
npm run dev # 监视模式（tsx，无编译步骤）
npm test # 运行所有测试（Vitest）
npm run typecheck # 类型检查，无需发出
npm run lint # ESLint
npm run build # 编译到dist/
```
### 使用MCP Inspector进行测试
```bash
npm run build
npx @modelcontextprotocol/inspector dist/index.js --root .
```
这将打开一个浏览器UI，您可以在其中交互式地调用所有工具并检查它们的输入/输出。
### 项目结构
```
src/
index.ts CLI入口点，参数解析
server.ts MCP服务器，工具注册
tools/ 薄工具处理器（仅限验证和格式化）
core/
fs/ 文件树构建，文件读取，忽略解析
search/ ripgrep适配器 + 纯Node.js备用
analysis/ 依赖关系图（ts-morph），大纲提取器，项目索引器
git/ Git适配器（差异，更改文件）
config/ 配置加载和Zod验证
types/ 共享TypeScript接口
utils/ 记录器（pino），路径帮助程序，类型错误
tests/
unit/ 每个模块的单元测试
integration/ 工具处理器集成测试
protocol/ 端到端MCP协议测试（InMemoryTransport）
performance/ 基准测试套件，时间和堆预算
```
---
## 路线图
查看 [ROADMAP.md](ROADMAP.md) 以了解计划内容和社区贡献的想法。
---
## 贡献
该项目处于积极的早期开发阶段。欢迎提交错误报告、功能请求和拉取请求 - 代码库故意设计得小而简单易导航。
- [CONTRIBUTING.md](.github/CONTRIBUTING.md) - 如何设置环境、运行测试、提交约定和架构规则
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - 社区标准（Contributor Covenant 2.1）
- [ROADMAP.md](ROADMAP.md) - 计划内容和社区PR开放
新加入项目？浏览标记为 [`good first issue`](https://github.com/Eltortilla1/synapse-code-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 的问题以找到最佳入口点。
---
## 许可证
[MIT](LICENSE)
