内容
center">
< <source mediaers-color-scheme: srcset="-dark.png">
media="(prefers-color-scheme: light)"="docs/logo-light.png <img alt=" MCP" src="docs/logo-light.png" width="500">
</picture>
</p>
# Synapse MCPCI](https://github.com/Juanmidevynapse-code-mcp/actions/workflows/ci.yml/badgehttps://github.com/Juanmidev1/synapse-code-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[
> 一个结构化的代码上下文 [模型上下文协议://modelcontextprotocol.io本地仓库连接到 AI 助手。
与将文件复制到提示符中不同，Synapse 让您的 AI可以动态探索您的代码在需要时代码。结果是上下文浪费，获得更答案，以及一个可扩展项目的 工作流 — 无需设置向量数据库或嵌入 API。
```
AI 助手 ──MCP──► Synapse MCP ──fs/git──► 您的仓库
(拉取) (服务器 (本地)
```
状态：**阶段，积极开发中。欢迎贡献和错误报告 —阅 [贡献](#contributing)。
---
## 为什么选择 Syn
大多数 AI 编码工具已经索引文件。Synapse 解决了不同的问题：**在规模上提供上下文质量**。
| 问题 | Synapse 解决方案 |
|---|---|
| 读取整个文件时，只需要其 API 接口 | `get_semantic_context`，使用 `outline_only` — 仅签名，≤ 的完整内容 |
不知道在的项目中存在哪些 `get_project_index`完整的符号映射，40% 的原始源代码大小，一次调用 |
| “审查我的更改” 需要手动粘贴差异 | `get_changed_files` — 结构化的 git 差异，默认情况下 git 感知 |
| 依赖关系兔子洞填充上下文窗口 | 可配置的 `depth` 导入遍历上限 |
上述压缩比率作为自动化测试预算强制执行 — 而不是市场估计。
### 为什么不使用向量嵌入？
大多数代码上下文 MCP 服务器使用由向量数据库（例如 Milvus、Qdrant）和嵌入 API（OpenAI、VoyageAI）支持的语义搜索。这使它们具有 Synapse 所没有的真正能力：根据概念含义查找代码（身份验证逻辑”），结构或文本。
Synapse 交换了这种能力取一组不同的属性：
零外部依赖 无需 API 密钥向量数据库，无需配置嵌入提供程序
- **成本** — 无需牌嵌入费用，无数据库账单
-本地和确定性** — 相同的输入始终产生上没有任何内容提前索引的内容为- **在任何仓库启动** — 首次无需索引步骤（](#performance)：在中为 120–257 毫秒）
如果许多语言的数百万行代码中进行自然语言语，则向量支持的服务器工具。如果您化上下文（签名，图，差异）建立基础设施，Synapse此而构建的。
工具
###_project_index`
返回项目的义映射：所有导出的函数、类、接口及其签名 — 不包括正文。在探索不熟悉的代码库时，这是正确的第一个```
# 项目索引：（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： email：string
createdAt：Date createUser（data：>）：User [```
**参数：**_pattern`（全局范围），`include_non_exported`，``（`"markdown"` · `"json"` 用于结构化输出）
使用 `output_format: "json原始符号数据作为结构，更容易以编程方式进行后期处理：
```{
"rootpath/to/project",
Files": 47 "totalSymbols": "files": {
"relativePathsrc/services/user-service "language":",
"symbols": }
]
}
**大型项目：** 输出随着导出的符号数量线性增长。对于具有 500+ monorepo 或使用 `file_pattern`范围限定在一时间 — 例如 `"src/services/**/*.ts"`。
---
### `get_semantic_context`
內容以及其本地依赖关系图 — AI 需要的一切，以便在上下文中理解代码。
添加 `outline_only: true获取签名而无需实现正文。输出由基准件强制执行，以确保 ≤ 50% 的完整，同时保留完整的结构理解。
**参数：**_path`（必填），`depth`（导入跳转：2），`outline_only`，`output_format`（`"markdown"` 默认值 · `"json"` 用于结构化输出）
---
###_changed_files`
列 git 引用以来更改状态（已添加修改 / 已删除重命名）分组，并的行数和完整。
```
自 `main来更改的文件（文件）：
**（2）：**
/payment.ts (+120)
tests/unit.ts (+89 −0已修改（5 src/models/order14 −3)
...
**摘要：** +18 行
```
：** `base_ref默认值：`HEAD`），`include，`file_pattern`
`get_project_tree的结构化视图，gitignore` 规则参数：** `，`max_depth`show_hidden`
---
### `search_codebase`
在项目中快速进行文本或正则表达式搜索，返回带有文件路径和行号的匹配项。当可用时使用 [ripgrep](https://github.com/BurntSushi/ripgrep)，否则使用纯 Node.js 扫描器。
**参数：** `query`（必填），`file_pattern`，`is_regex`max_results`
---
语言支持
Synapse 使用 [ts-morph://ts-morph.com)（TypeScript 编译）对 TypeScript 和 JavaScript 进行深入分析语言，它应用基于正则表达式的函数和类名| 功能 | TypeScript / JS | Python · Rust | 其他 |
|---|---|---|---|
| `get` | ✓ | ✓ | ✓ |
| `base` | ✓ | ✓ | ✓ |
| `get_semantic_context` —源代码 | ✓ | ✓ |
| `get_semantic_context` —关系图 | ✓ | — | — |
|_semantic_context outline_only` | ✓ 完整签名仅名称 | — |
| `get_project | ✓ 完整签名 | ✓ 仅名称 |关系图遍历 `import`` 链）仅 TypeScript/JavaScript语言，Synapse 仍然正常读取和 — 但不会遍历导入图。
> **注意：依赖关系图遍历遵循 *相对* 导入foo`，`../bar`）和别名*，通过 `tsconfig.json` `.paths` 配置（例如 `@/components/Foo`），只要在项目根目录下存在 `tsconfig.json即可。没有 `tsconfig.json` 的项目到仅限相对解析。
---
## 安装全局安装（推荐）：bash
npm install synapse-code-mcp
```
**无需安装**
```bashpx synapse-code-mcp --root /path/to/your/project
```
---
## 设置
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（）或 `%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 synapsecp --root /path/to/your/project
```
添加到 `~/.claude/settings.json`：json
{
"mcpServers": {
synapse": {
"command": "n "args": ["synapse-code-mcproot", "/path/to/your/project"]
}
}
```
### Cursor
添加到 `.cursor/mcp您的主目录或项目根目录中：json
{
"mcpServers": {
synapse": {
"command": "n "args": ["synapse-code-mcp",", "/path/to/your/project"]
}
```
### Windsurf
添加到 `~/./windsurf/mcp_config.json`：
{
"mcpServers": {
": {
"command": "npx "args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
}
```
> **提示：** 将 `/path/to/project` 替换为您要服务的仓库的。您可以运行多个 Synapse 实例 — 每个 每个实例在 `mcpServers不同的密钥。
---
## 配置
### CLI 标志
```
选项：
--root <path> 项目根目录（默认值：cwd）
-file-size <bytes> 跳过大于此默认值：524288 = 512 KB）
-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 编译器 `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` 将限定在一时间的一个区域。
---
## 安全
是一个 **只读** 服务器。它从不写入文件系统或修改 git。
- **路径遍历 — 每个都经过 `resolve(root, path)`解析的路径超出项目根目录，则会PATH_ESCAPE` 错误。AI 客户端接收错误代码，而非文件内容。
- **根目录范围** — 仅 `--root` 下的目录树可访问。指向外部的路径（例如 `../../etc/passwd`）在验证层被拒绝。
- **文件大小上限** — 大于 `Size`（默认 512 KB）的前被拒绝。
- **二进制 — 编译后的和二进制文件被和跳过。
无外部网络调用 Synapse MCP 客户端与io 管道通信发出任何 HTTP 请求 建议的工作**探索新：**
```
1_project_index()
→项目的完整结构，一
2_semantic_context("src/core/engine.ts", outline_only: true)
→读取实现的情况下的 API 接口
get_semantic_context/core/engine.ts")
读取完整源 相关文件的依赖关系```
**代码审查 PR：**
```
_changed_files(base_ref: "main")
查看更改内容，分类和总结
2.(base_ref: "main", include_diff)
→ 上完整的统一差异
get_semanticsrc/changed-file → 了解周围的上下文
```
**调试功能：**
```
search_codebase")
→ 查找符号的定义
2. get_context("src.ts", depth3)
→文件 + 所有
```
---
##
- **Node.js ≥ 18**
- **Git** — 仅 `get_changed_files` 需要
- **[ripgrep](https://githuburntSushi/ripgrep)** *(可选)* — 显著提高搜索速度；如果 `$PATH` 上没有 `rg`，Synapse 将回退到纯 Node.js 扫描器
---
## 开发
```bash
git clone https://github.com/Juanmidev1/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 检验器进行测试
```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/Juanmidev1/synapse-code-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 的问题以找到最佳入口。
---
## 许可证
[MIT](LICENSE)
