codesynapse

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg"> <img src="assets/logo-light.svg" alt="codesynapse" height="60"> </picture> <br/> **代码智能MCP服务器** — 为AI编码助手提供架构级知识的工具。 [](https://github.com/sohilladhani/codesynapse/actions/workflows/ci.yml) [](https://crates.io/crates/codesynapse-cli) [](LICENSE) [](https://www.rust-lang.org) [快速开始](#快速开始) · [MCP工具](#mcp工具) · [语言支持](#语言支持) · [配置](#配置) · [卸载](#卸载) · [故障排除](#故障排除) · [贡献](#贡献) <br/> <a href="https://www.producthunt.com/products/codesynapse?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-codesynapse" target="_blank" rel="noopener noreferrer"><img alt="codesynapse - Code graph as MCP tools makes your AI stops hallucinating | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1180306&theme=light&t=1782391600666"></a> </div> --- AI编码工具能很好地回答关于单个文件的问题。但它们无法理解**架构** — 类层次结构、调用链、变更的爆炸半径、哪个模块拥有某个概念。`grep`和文件搜索返回的是噪音，而不是信号。 Codesynapse解决了这个问题。它从源代码中构建结构化知识图（节点 = 类、函数、文件；边 = 调用、继承、实现、包含），将多个模块的图合并成单个全局图，并暴露**32个MCP工具**，支持混合BM25 + 稠密向量搜索。每次与Claude Code或Cursor的会话都以完整的图上下文开始 — 而不是一张空白的画布。 完全在本地运行。不需要GPU，不需要云API，不需要基础设施。 --- ## 演示 <img src="assets/demo.gif" alt="codesynapse demo — module add, module list, query" width="100%"> <!-- To regenerate: install vhs (https://github.com/charmbracelet/vhs) then run: vhs assets/demo.tape --> --- ## 为什么是codesynapse？ | | Python graphify | graphify-rs | semble | code-review-graph | codegraph | cbm | Sourcegraph Cody | continue.dev | **codesynapse** | |---|---|---|---|---|---|---|---|---|---| | **语言** | Python | Rust | Python | Python | TypeScript | C | Cloud | VS Code ext. | **Rust** | | **MCP工具** | ✗ | ✗ | 2 | 30 | 10 | ~8 | ✗ | ✗ | **32** | | **结构化图** | 部分 | 通用知识图 | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | **✓** | | **爆炸半径** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **混合BM25 + 稠密** | ✗ | 仅BM25 | ✓ | 可选 | ✗ (FTS5) | ✗ | ✓ | ✗ | **✓** | | **完全本地** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | **✓** | | **无需云API** | ✓ | ✓ | ✓ | ✗ (语义) | ✓ | ✓ | ✗ | ✗ | **✓** | | **多模块图** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **跨模块层次结构** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✗ | **✓** | | **文件读取消除** | — | — | — | — | 100% | 部分 | — | — | **100%** | | **默认无遥测** | ✓ | ✓ | ✓ | ✓ | ✗ (需选择加入) | ✓ | ✗ | ✗ | **✓ (需选择加入)** | | **运行时** | Python | Rust | Python | Python | Node.js | C二进制 | 云 | Node.js | **Rust二进制** | **[codegraph](https://github.com/Tgedin/codegraph)** 是最接近的替代品 — TypeScript，本地，10个MCP工具，爆炸半径，多模块。主要差距：仅限词法FTS5搜索（无稠密嵌入），因此同义词和概念查询会错过BM25+稠密RRF捕获的结果。 **[cbm (codebase-memory-mcp)](https://github.com/DeusData/codebase-memory-mcp)** 是用C编写的二进制文件，带有SQLite图存储 — 快速的冷启动索引（无需嵌入传递），但没有混合搜索，需要每次查询读取多个文件（观察到8-10 vs 0 for codesynapse）。 **semble** 使用相同的Model2Vec + BM25 + RRF搜索栈，但仅限搜索 — 无结构图，无爆炸半径，无层次结构。 **code-review-graph** 有图 + MCP，但使用Python，需要云API进行语义搜索。 **graphify-rs** 是原始Python graphify工具的Rust重写版本 — 通用知识图，不是MCP原生或代码智能焦点。 Codesynapse是 [Python graphify](https://github.com/safishamsi/graphify) 的Rust重写版本，具有完整的MCP集成、结构化图分析和零云依赖。 --- ## 基准测试 在真实的开源仓库中进行测量（redis, tokio, django-framework）。使用Docker， `--cpus=4 --memory=8g`，3次运行的中位数。完整的测量方法和每个问题的分数： [BENCHMARKS.md](BENCHMARKS.md)。 竞争对手： [codegraph](https://github.com/Tgedin/codegraph) （TypeScript，SQLite FTS5）， [cbm/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) （C，SQLite图存储，无嵌入）。 **索引速度** — 冷启动索引时间： | 仓库 | codesynapse | codegraph | cbm | |------|-------------|-----------|-----| | redis (C, ~700个文件) | **3.8s** | 60.8s | 5.9s | | tokio (Rust, ~900个文件) | **4.6s** | 36.8s | 2.0s | | django-framework (Python, ~2k个文件) | **17.5s** | 306s | 12.4s | codesynapse的索引速度比codegraph **快8-17倍**。cbm的索引速度比codesynapse快是因为它跳过了嵌入传递 — 但这意味着每个查询都需要读取多个文件（观察到8-10 vs 0 for codesynapse）。 **查询准确率** （Claude评判，0-10分，在问题中答案符号名称不出现的情况下 — 例如 "什么处理访问控制？" → `IsAuthenticated`）： | | codesynapse | codegraph | cbm | 基线 | |---|---|---|---|---| | 平均分数 | **8.9** | 9.0 | 8.7 | 8.6 | | 每查询文件读取次数 | **0** | 0 | 8-10 | — | 分数在工具之间相当。codesynapse的优势在于操作：零文件读取意味着每会话的令牌成本更低，大型代码库中没有上下文爆炸。codegraph的仅限词法搜索（SQLite FTS5）应该在同义词查询上挣扎，但Claude通过后续工具调用进行补偿 — 因此两者通过不同的路径达到类似的分数。 --- ## 工作原理 ```mermaid flowchart TD A[("源代码\n(任意仓库)")] -->|并行tree-sitter AST\n30+种语言| B["每模块 graph.json"] B -->|global_add — 前缀节点ID，合并| C[("全局-graph.json\n~/.codesynapse/")] C -->|embed_global_graph\npotion-code-16M · CPU-only · mtime-gated| D[("embeddings.json\n~/.codesynapse/")] C & D --> E[["MCP服务器\n32种工具 · 混合BM25 + 稠密RRF"]] E --> F["Claude Code · Cursor · OpenCode\nCodex CLI · Hermes · Kiro · 任意MCP客户端"] style A fill:#f6f8fa,stroke:#57606a,color:#24292f style B fill:#ddf4ff,stroke:#54aeff,color:#0550ae style C fill:#dafbe1,stroke:#4ac26b,color:#1a7f37 style D fill:#fff8c5,stroke:#d4a72c,color:#4d2d00 style E fill:#ede9fe,stroke:#8957e5,color:#512a97 style F fill:#ffeef8,stroke:#bf3989,color:#6e1e5c ``` **关键设计选择： | 决策 | 原因 | |---|---| | 混合BM25 + 稠密RRF | BM25精确处理符号名称；稠密解决同义词差距。RRF融合提供两者的最佳效果。 | | Model2Vec `potion-code-16M` | 静态嵌入 — 查询时无需前向传递，~1.5ms查询，CPU-only，64 MB模型。 | | Sled嵌入式数据库 | 零依赖，基于文件的节点ID快速随机访问。无需服务器进程。 | | Tree-sitter AST提取 | 涵盖30+种语言的语法覆盖率。无需语言服务器或构建系统。 | | 每模块 → 全局合并 | 启用跨模块爆炸半径和层次结构，无需将所有模块加载到内存中。 | | mtime-gated嵌入再生 | 仅当`global-graph.json`更新时再生嵌入。图不变时零开销。 | --- ## 语言支持 | 组 | 语言 | |---|---| | **系统** | Rust, C, C++, Go, Zig, Fortran, Verilog | | **JVM** | Java, Kotlin, Scala, Groovy | | **Web / 前端** | JavaScript, TypeScript, Svelte, Vue, PHP | | **脚本** | Python, Ruby, Lua, Bash, PowerShell | | **移动 / Apple** | Swift, Objective-C, Dart | | **函数式** | Haskell, Elixir, Racket, Julia | | **其他** | SQL, C#, CMake, Pascal | --- ## 安装 **前提条件：** - ~500 MB可用磁盘（图存储 + 模型，首次`setup`时下载） - 首次运行时需要互联网连接（仅限模型下载） **选项A — 一行命令** Linux / macOS： ```bash curl -fsSL https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.sh | sh ``` Windows (PowerShell)： ```powershell irm https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.ps1 | iex ``` 或从 [releases](https://github.com/sohilladhani/codesynapse/releases/latest) 下载特定二进制文件： | 平台 | 二进制文件 | |---|---| | Linux x86_64 | `codesynapse-linux-x86_64` | | macOS Apple Silicon | `codesynapse-macos-aarch64` | | Windows x86_64 | `codesynapse-windows-x86_64.exe` | ```bash chmod +x codesynapse-* sudo mv codesynapse-* /usr/local/bin/codesynapse ``` **选项B — 包管理器** macOS (Homebrew)： ```bash brew tap sohilladhani/codesynapse brew install codesynapse ``` Windows (Scoop)： ```powershell scoop bucket add cs https://github.com/sohilladhani/scoop-codesynapse scoop install codesynapse ``` Nix： ```bash nix run github:sohilladhani/codesynapse # 直接运行 nix profile install github:sohilladhani/codesynapse # 永久安装 ``` 或添加到您的flake： ```nix inputs.codesynapse.url = "github:sohilladhani/codesynapse"; # then: https://github.com/sohilladhani/codesynapse" # then: inputs.codesynapse.packages.${system}.default ``` **选项C — 从源代码构建** 需要Rust稳定工具链 ([安装](https://rustup.rs)): ```bash cargo install codesynapse-cli ``` --- ## 快速开始 ```bash # 1. 在Claude Code和/或Cursor中注册MCP服务器（自动检测两者） codesynapse setup # 其他客户端（如果未自动检测到）： codesynapse opencode install # OpenCode codesynapse codex install # Codex CLI codesynapse hermes install # Hermes Agent codesynapse kiro install # Kiro # 2. 索引一个仓库 codesynapse module add myrepo /path/to/your/repo # 3. 重启您的AI客户端 # 4. 提出架构问题 — 32种MCP工具现在可用 ``` 就是这样。从这一点开始，像 *"什么处理身份令牌过期？"* 或 *"显示UserService的爆炸半径"* 这样的查询会从图谱中获得答案 — 而不是从文件搜索。 **添加更多仓库：** ```bash codesynapse module add backend /path/to/backend codesynapse module add frontend /path/to/frontend # 图谱被合并 — 跨模块查询自动生效 ``` **刷新代码更改后：** ```bash codesynapse module refresh myrepo ``` **列出索引模块：** ```bash codesynapse module list ``` **删除模块：** ```bash codesynapse module remove myrepo # 从全局图谱中修剪其节点并注销 ``` **使用git保持图谱更新（可选）：** ```bash codesynapse hook install # 安装后合并git钩子 — 在pull时自动刷新 ``` --- ## MCP工具 六类32种工具，可从Claude Code，Cursor或任何MCP兼容的客户端调用。 | 类别 | 工具 | |---|---| | **图谱搜索** | `codesynapse_query_vector`, `codesynapse_query_semantic`, `codesynapse_blast_radius`, `codesynapse_blast_radius_scored`, `codesynapse_blast_radius_multi`, `codesynapse_hierarchy`, `codesynapse_list_graphs`, `codesynapse_module_summary`, `codesynapse_build` | | **代码阅读** | `codesynapse_resolve`, `codesynapse_outline`, `codesynapse_read`, `codesynapse_read_method`, `codesynapse_read_with_callees` | | **导航** | `codesynapse_find_callers`, `codesynapse_find_usages` | | **图谱分析** | `codesynapse_query_graph`, `codesynapse_get_node`, `codesynapse_get_neighbors`, `codesynapse_get_community`, `codesynapse_god_nodes`, `codesynapse_graph_stats`, `codesynapse_shortest_path`, `codesynapse_find_all_paths`, `codesynapse_weighted_path`, `codesynapse_community_bridges`, `codesynapse_diff`, `codesynapse_pagerank`, `codesynapse_detect_cycles`, `codesynapse_smart_summary`, `codesynapse_find_similar` | | **可观察性** | `codesynapse_stats` | 完整参数参考和示例： [docs/MCP-TOOLS.md](docs/MCP-TOOLS.md) **Claude Code中的常见查询：** ``` "What handles auth token expiry?" → codesynapse_query_vector "Show blast radius of UserService" → codesynapse_blast_radius "What does UserRepository extend?" → codesynapse_hierarchy "Read the validate() method" → codesynapse_read_method "Who calls PaymentService.charge()?" → codesynapse_find_callers ``` --- ## 配置 将`codesynapse.toml`放在项目根目录下。所有字段都是可选的。 ```toml # 导出图谱的输出目录（默认：codesynapse-out/） output = "codesynapse-out" # 跳过LLM提取doc/paper文件（默认：false） no_llm = false # 仅索引源代码，跳过文档和论文（默认：false） code_only = false # 导出格式： "json", "html", "graphml", "obsidian" formats = ["json", "html"] # 用于文档/论文语义提取的LLM配置（可选） [llm] provider = "anthropic" # "anthropic" | "openai" | 任意OpenAI兼容 model = "claude-sonnet-4-20250514" api_key = "sk-..." # 或设置ANTHROPIC_API_KEY / OPENAI_API_KEY环境变量 base_url = "https://..." # 可选，用于OpenAI兼容提供商 # 自定义模型路径（默认：自动解析codesynapse setup） [embeddings] model_path = "./models/potion-code-16M" ``` --- ## 仓库布局 ``` codesynapse/ ├── codesynapse-core/ # 提取，图谱，嵌入，全局图谱 ├── codesynapse-cli/ # CLI二进制文件（模块添加/刷新/列表，构建，设置） ├── codesynapse-mcp/ # MCP服务器 — 32种工具，JSON-RPC via stdio ├── codesynapse-serve/ # BM25 + 稠密混合搜索引擎 ├── codesynapse-tui/ # 终端UI ├── codesynapse-grpc/ # gRPC服务器 ├── codesynapse-graphql/ # GraphQL API ├── codesynapse-wasm/ # WebAssembly绑定 ├── models/ │ └── potion-code-16M/ # 静态嵌入模型（由setup下载） ├── tests/ # 集成测试 └── docs/ ├── ARCHITECTURE.md └── MCP-TOOLS.md ``` 运行时数据位于`~/.codesynapse/`： ``` ~/.codesynapse/ ├── global-graph.json # 合并图谱（所有模块） ├── embeddings.json # 节点ID → Vec<f32>稠密嵌入 ├── modules.conf # 名称|路径模块注册表 ├── global-manifest.json # 模块哈希 + 元数据 ├── tool_stats.jsonl # MCP工具调用日志 ├── models/potion-code-16M/ └── modules/<name>/graph.json ``` --- ## 卸载 **从所有AI客户端中删除：** ```bash # 重新运行setup并手动从setup写入的配置文件中删除条目： # Claude Code: ~/.claude.json （键：mcpServers.codesynapse） # Cursor: ~/.cursor/mcp.json （键：mcpServers.codesynapse） # Windsurf: ~/.codeium/windsurf/mcp_config.json # OpenCode: ~/.config/opencode/opencode.json ``` **删除特定模块：** ```bash codesynapse module remove myrepo ``` **完全清理** （删除所有索引数据）： ```bash rm -rf ~/.codesynapse/ ``` --- ## 手动MCP设置 如果`codesynapse setup`无法自动检测您的客户端，请手动添加以下条目： **Claude Code** (`~/.claude.json`)： ```json { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` **Cursor** (`~/.cursor/mcp.json`)： ```json { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` 对于其他客户端，请将相同的`command`/`args`对传递给其MCP服务器配置。 --- ## CLI技能（无MCP备用） 如果MCP被您的组织网络策略阻止，codesynapse会附带一个适用于Claude Code的CLI技能和一个适用于Cursor的规则文件。您的AI客户端将直接调用`codesynapse`，而不是使用MCP协议。 **Claude Code** — 复制到您的项目： ```bash mkdir -p /path/to/your/project/.claude/skills cp -r integrations/claude-code/skills/codesynapse-cli /path/to/your/project/.claude/skills/ ``` **Cursor** — 复制到您的项目： ```bash mkdir -p /path/to/your/project/.cursor/rules cp integrations/cursor/rules/codesynapse-cli.mdc /path/to/your/project/.cursor/rules/ ``` `integrations/`目录随存储库提供。重启您的客户端后复制。 --- ## pi扩展 对于 [pi](https://github.com/pi-ai/pi) 用户，请安装codesynapse扩展： ```bash pi install npm:codesynapse-pi ``` 这将连接12个精选的codesynapse工具，并在每个pi会话中自动注入图谱感知。 --- ## 故障排除 **MCP服务器未连接** - 验证`codesynapse`是否在您的PATH上：`which codesynapse` - 再次运行`codesynapse setup` — 它会重写客户端配置文件 - 在设置后重启您的AI客户端 **图谱查询无结果** - 检查模块是否已索引：`codesynapse module list` - 重建全局图谱：`codesynapse build` - 确保模型已下载：`codesynapse setup` （在第一次运行期间下载`potion-code-16M`） **代码更改后结果过时** - 刷新模块：`codesynapse module refresh myrepo` - 或安装git钩子以自动刷新：`codesynapse hook install` **`codesynapse setup` 表示没有嵌入模型** `codesynapse setup` 自动下载模型。如果失败： 1. 检查您的互联网连接并重新运行`codesynapse setup` 2. 从HuggingFace手动下载： ``` https://huggingface.co/minishlab/potion-code-16M/resolve/main/model.safetensors https://huggingface.co/minishlab/potion-code-16M/resolve/main/tokenizer.json https://huggingface.co/minishlab/potion-code-16M/resolve/main/config.json ``` 将所有三个文件放入`~/.codesynapse/models/potion-code-16M/`，然后重新运行`codesynapse setup`. **图谱查询慢** - 启动后第一次查询较慢 — 嵌入加载到磁盘 - 随后的查询速度很快（~1.5毫秒编码 + BM25 + 余弦） --- ## 遥测 遥测 **默认关闭**。如果您想帮助改进codesynapse，请显式启用它： ```bash codesynapse telemetry on # 启用 codesynapse telemetry off # 退出 + 删除本地队列 ``` 启用后，codesynapse会发送匿名的每日汇总数据：工具名称，调用次数和粗略的令牌节省桶。无查询内容，无文件路径，无源代码，无IP。参见 [TELEMETRY.md](TELEMETRY.md) 了解完整的数据契约。 --- ## 贡献 欢迎贡献。请在开启PR之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 - **错误报告：** 使用 [错误报告模板](.github/ISSUE_TEMPLATE/bug_report.md) - **功能请求：** 使用 [功能请求模板](.github/ISSUE_TEMPLATE/feature_request.md) - **代码：** 运行 `cargo test --workspace` 和 `cargo clippy --workspace -- -D warnings` 在提交之前 本项目遵循 [Contributor Covenant](CODE_OF_CONDUCT.md) 行为准则。 --- ## 许可证 MIT — 参见 [LICENSE](LICENSE)。