内容
# codebase-memory-mcp (Zig)
**适用于 AI 编程代理的最快最小代码智能引擎** — 原始 [C 实现](https://github.com/DeusData/codebase-memory-mcp) 的高性能 Zig 重写。
将代码库索引到持久的 **SQLite 属性图知识图谱** 中，使用 tree-sitter AST 解析超过 30 种语言，并使用正则表达式回退以实现全面覆盖。作为一个 **单个 2.2 MB 静态二进制文件** 发布，运行时依赖为零。
[](LICENSE)
[](https://github.com/dajneem23/z-codebase-mcp/actions/workflows/ci.yml)
[](https://github.com/dajneem23/z-codebase-mcp/actions/workflows/bench.yml)
## 为什么选择 Zig？
原始 C 实现将 158 个 tree-sitter 语法文件捆绑到二进制文件中（257 MB）。我们的 Zig 重写在运行时加载语法文件，并使用更精简的单次索引流水线。
| 指标 | C 原始实现 | Zig 重写实现 | 改进 |
| --- | --- | --- | --- |
| 二进制文件大小 | 257 MB* | **2.2 MB** | **117 倍更小** |
| 内存（空闲） | ~120 MB | **~8 MB** | **15 倍更小** |
| 内存（索引） | ~500 MB | **~50 MB** | **10 倍更小** |
| 编译语言 | 基线 | **2.5 倍更快** | 14 个仓库的平均值 |
| 启动时间 | ~200ms | **~10ms** | **20 倍更快** |
| 语法加载 | 编译时 | 运行时（dlopen） | 模块化 |
* C 二进制文件嵌入了 158 个编译后的 tree-sitter 语法文件；我们的实现按需加载它们。
## 主要功能
- **14 个 MCP 工具** — 与 C 原始实现完全兼容
- **Tree-sitter AST 解析** — 30 多种语言，带有编译后的语法 `.dylib`/`.so` 文件
- **正则表达式回退** — 无语法时可用：Zig、Go、Rust、TypeScript、Python、C/C++
- **SQLite 属性图** — FTS5 全文搜索、WAL 模式、ACID 安全
- **BM25 排名** — 结构增强（函数 +10、路由 +8、类 +5）
- **类 Cypher 查询** — `MATCH (n:Function)-[r:CALLS]->(m) RETURN n, r, m`
- **Leiden 社区检测** — 实际模块边界来自调用图
- **调用链跟踪** — BFS 遍历，风险分类跳跃距离
- **Git 变更分析** — 共同变更耦合分数，影响符号
- **架构决策记录** — ADR 的完整 CRUD
- **图增强 grep** — 文本搜索丰富结构上下文
- **单次 AST 遍历** — `walkAll()` 在一次树遍历中检查所有节点类型
## 快速入门
需要 [Zig](https://ziglang.org/) 0.16.0 或更高版本。
```bash
git clone https://github.com/dajneem23/z-codebase-mcp.git
cd z-codebase-mcp
# 调试构建
zig build # → zig-out/bin/cbm (~10 MB)
# 发布构建（推荐）
zig build -Doptimize=ReleaseFast # → zig-out/bin/cbm (~2.2 MB)
```
### MCP 服务器
将以下内容添加到代理的 MCP 配置中：
```json
{
"mcpServers": {
"codebase-memory-mcp": {
"command": "/path/to/zig-out/bin/cbm"
}
}
}
```
对于 Claude Code，请在项目根目录或 `~/.claude/claude_desktop_config.json` 中添加 `.mcp.json`。
### CLI 模式
可以直接从命令行调用所有 14 个工具：
```bash
# 索引代码库
cbm cli index_repository '{"repo_path":"/path/to/repo"}'
# 按名称或关键词搜索
cbm cli search_graph '{"project":"myproject","query":"handleRequest"}'
# 跟踪调用链
cbm cli trace_path '{"project":"myproject","function_name":"main","mode":"calls"}'
# 架构概览
cbm cli get_architecture '{"project":"myproject"}'
# Cypher 查询
cbm cli query_graph '{"project":"myproject","query":"MATCH (n:Function)-[r:CALLS]->(m) RETURN n.name, m.name LIMIT 10"}'
# Git 变更影响分析
cbm cli detect_changes '{"project":"myproject","depth":20}'
# 架构决策记录
cbm cli manage_adr '{"project":"myproject","mode":"update","title":"Use SQLite for storage","content":"..."}'
```
## 所有 14 个 MCP 工具
### 索引
| 工具 | 描述 |
| --- | --- |
| `index_repository` | 将代码库索引到知识图谱中。支持 `full`、`moderate`、`fast` 和 `cross-repo-intelligence` 模式。 |
| `index_status` | 检查项目的索引进度和统计信息。 |
| `list_projects` | 列出所有索引的项目及其元数据。 |
| `delete_project` | 删除项目及其所有节点、边和元数据。 |
### 搜索和查询
| 工具 | 描述 |
| --- | --- |
| `search_graph` | BM25 全文搜索，结构增强。三种模式：自然语言 `query`、正则表达式 `name_pattern` 和 `semantic_query` 向量搜索。支持分页 via `offset`/`limit`。 |
| `search_code` | 图增强模式搜索（grep 丰富调用图上下文）。返回去重结果，按结构重要性排名。 |
| `query_graph` | 对属性图进行类似 Cypher 的查询。支持 `MATCH`、`WHERE`、`RETURN`、`ORDER BY`、`LIMIT` 和聚合函数。 |
| `get_code_snippet` | 按限定名称读取特定符号的源代码。返回精确的文件 + 行范围。 |
### 分析
| 工具 | 描述 |
| --- | --- |
| `trace_path` | BFS 调用链遍历，`inbound`/`outbound`/`both` 方向。模式：`calls`、`data_flow`、`cross_service`。可选的风险分类跳跃距离（CRITICAL/HIGH/MEDIUM/LOW）。 |
| `get_architecture` | 高级架构概览：包、服务、依赖、热点和 Leiden 社区检测集群。 |
| `detect_changes` | Git 历史分析 — 映射更改文件到影响符号，计算共同变更耦合分数。 |
| `get_graph_schema` | 返回知识图谱中的所有节点标签和边类型。 |
### 元数据
| 工具 | 描述 |
| --- | --- |
| `manage_adr` | ADR 的 CRUD。支持 `get`、`update` 和 `sections` 模式。 |
| `ingest_traces` | 引入运行时轨迹（HTTP 请求、异步事件、数据流）以丰富知识图谱。 |
## 图数据模型
### 节点标签
`Project`、`Package`、`Folder`、`File`、`Module`、`Class`、`Function`、`Method`、`Interface`、`Enum`、`Type`、`Route`、`Variable`
### 边类型
| 边 | 描述 |
| --- | --- |
| `CALLS` | 函数/方法调用 |
| `HTTP_CALLS` | 服务之间的 HTTP 请求/响应 |
| `ASYNC_CALLS` | 消息队列 / 事件驱动通信 |
| `IMPLEMENTS` | 类实现接口 |
| `DEFINES` | 文件/模块定义符号 |
| `DEFINES_METHOD` | 类定义方法 |
| `OVERRIDE` | 方法覆盖父方法 |
| `IMPORTS` | 模块导入关系 |
| `USAGE` | 一般用法（类型引用、变量访问） |
| `FILE_CHANGES_WITH` | Git 历史中的共同变更耦合 |
| `CONTAINS_FILE` | 包/文件夹包含文件 |
| `CONTAINS_FOLDER` | 文件夹包含子文件夹 |
| `CONTAINS_PACKAGE` | 项目包含包 |
| `HANDLES` | 路由处理程序绑定 |
## Cypher 查询示例
通过 `query_graph` 运行：
```cypher
-- 服务之间所有 HTTP 调用
MATCH (a)-[r:HTTP_CALLS]->(b)
RETURN a.name, b.name, r.url_path, r.method
LIMIT 20
-- 名称中带有"Handler"的函数
MATCH (f:Function)
WHERE f.name =~ '.*Handler.*'
RETURN f.name, f.file_path, f.start_line
-- main() 调用什么（最多 3 跳）？
MATCH (n:Function {name: 'main'})-[r:CALLS*1..3]->(m)
RETURN n.name, m.name, length(r) AS hops
-- 最多调用函数（高 fan-in）
MATCH (a)-[r:CALLS]->(b:Function)
RETURN b.name, count(r) AS callers
ORDER BY callers DESC
LIMIT 20
-- 死代码：无调用者和无调用目标的函数
MATCH (f:Function)
WHERE NOT (()-[:CALLS]->(f)) AND NOT (f)-[:CALLS]->()
RETURN f.name, f.file_path
```
## 语言支持
### Tree-sitter 语法（编译，运行时加载）
| 层级 | 语言 |
| --- | --- |
| **编译** | Go、Python、Rust、Zig、C、C++、JavaScript、TypeScript、TSX |
语法 `.dylib` 文件从源代码通过 `tree-sitter generate` 编译，并在运行时通过 `dlopen` 加载。要编译语法：```bash
cd grammars
for lang in go python rust zig c cpp javascript typescript tsx; do
git clone --depth 1 "https://github.com/tree-sitter/tree-sitter-${lang}" "$lang" 2>/dev/null || true
(cd "$lang" && tree-sitter generate 2>/dev/null && cp *.dylib "../${lang}.dylib") &
done
wait
```
### 正则表达式回退（始终可用）
| 质量 | 语言 |
| --- | --- |
| **优秀** | Zig、Go、Rust、C、C++ — 编译语言解析干净 |
| **良好** | Python、TypeScript、JavaScript、Java、C#、Kotlin |
| **功能性` | Ruby、PHP、Swift、Lua、Scala、Haskell、OCaml |
正则表达式回退检测函数、方法、类、接口、枚举和文件内调用边。它预过滤行 `isInterestingLine()`（跳过空白、注释、导入）以提高速度。
## 性能
### 独立基准测试（M1 MacBook Pro，ReleaseFast）
| 仓库 | 语言 | 文件 | 符号 | 边 | 时间 | 文件/秒 | 符号/秒 |
| --- | --- | --- | --- | --- | --- | --- |
| z-codebase-mcp | Zig | 43 | 817 | 2,052 | 0.24s | 179 | 3,404 |
| arrow-rs（93 MB） | Rust | 559 | 13,830 | 114,425 | 2.93s | 191 | 4,720 |
| caddy | Go | 326 | 1,761 | 26,514 | 0.69s | 472 | 2,552 |
| traefik | Go | 937 | 10,648 | 86,073 | 2.57s | 364 | 4,143 |
| ollama | Go | 874 | 12,762 | 297,172 | 2.80s | 312 | 4,558 |
| aseprite（194 MB） | C/C++ | 5,156 | 12,761 | — | ~8s | 644 | 1,595 |
| react | JS | 4,584 | 72K | 155K | 23s | 199 | 3,130 |
| bun（280 MB） | Zig | 12,087 | 841,526 | — | ~140s | 86 | 6,011 |
| v8（247 MB） | C++ | 16,170 | 577,075 | 872,711 | 85s | 190 | 6,789 |
### Zig vs C — 对比（22 个仓库，ReleaseFast）
#### Zig 优势（22 个仓库中的 16 个）
| 仓库 | 语言 | 文件 | Zig | C | 加速比 | Zig 符号 | C 符号 | C 边 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **bitcoin** | C++ | 1,993 | 3.66s | 41.87s | **11.4×** | 6,900 | 36,293 | 175,127 |
| **node** | C++/JS | 34,650 | 252s | 1,154s | **4.5×** | 1,195,988 | 1,064,070 | 2,386,368 |
| **ollama** | Go | 874 | 2.80s | 8.33s | **3.0×** | 12,762 | 149,083 | 297,172 |
| **claude-code** | TS | 26 | 0.20s | 0.44s | **2.2×** | 656 | 3,024 | 3,822 |
| **reth** | Rust | 1,266 | 4.18s | 8.83s | **2.1×** | 17,748 | 54,778 | 187,578 |
| **caddy** | Go | 326 | 0.69s | 1.37s | **2.0×** | 1,761 | 4,767 | 26,514 |
| **rustdesk** | Rust | 322 | 1.20s | 2.43s | **2.0×** | 5,074 | 14,827 | 53,786 |
| **golang/go** | Go | 10,648 | 25s | 48s | **1.9×** | 81,880 | 247,574 | 1,474,135 |
| **traefik** | Go | 937 | 2.57s | 4.96s | **1.9×** | 10,648 | 26,693 | 86,073 |
| **ziglang/zig** | Zig | 16,987 | 51s | 86s | **1.7×** | 174,073 | 886,039 | 1,358,190 |
| **arrow-rs** | Rust | 559 | 3.08s | 4.94s | **1.6×** | 13,830 | 20,538 | 114,425 |
| **rust-lang/rust** | Rust | 36,422 | 97s | 111s | **1.1×** | 239,973 | 385,572 | 1,573,773 |
| **v8** | C++ | 16,170 | 115s | 130s | **1.1×** | 577,075 | 251,175 | 872,711 |
| **bun** | Zig | 12,087 | 279s | — | — | 841,526 | — | — |
| **aseprite** | C/C++ | 5,156 | ~8s | — | — | 12,761 | — | — |
#### C 优势（22 个仓库中的 5 个 — 全部为 JS/TS 密集型）
| 仓库 | 语言 | 文件 | Zig | C | 比率 | Zig 符号 | C 符号 | C 边 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **react** | JS | 4,584 | ~~81s~~ **23s** | 9s | 0.4× | ~~416K~~ **72K** | 51,722 | 155,390 |
| **vue** | JS | 425 | ~~7.6s~~ **1.9s** | 0.92s | 0.5× | ~~48K~~ **8.5K** | 3,769 | 11,288 |
| **TypeScript** | TS | 39,283 | ~~348s~~ ~120s | 83s | 0.7× | ~~1.4M~~ ~400K | 294,716 | 794,793 |
| **three.js** | JS | 1,623 | ~~49s~~ **21s** | 10s | 0.5× | ~~307K~~ **94K** | 55,850 | 188,605 |
| **electron** | C++/JS | 1,509 | 12s | 3.6s | 0.3× | 73,266 | 23,012 | 54,691 |
> 🎉 **新增 tree-sitter JS 语法！** React: 81s → 23s (3.4×)，vue: 7.6s → 1.9s (4×)，three.js: 49s → 21s (2.3×)。删除线 = 正则表达式回退；粗体 = 使用 tree-sitter 语法。
#### 平局
| 仓库 | 语言 | 文件 | Zig | C | 比率 | Zig 符号 | C 符号 | C 边 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **union** | Rust/Zig | 2,023 | 10.2s | 9.3s | 0.9× | 53,872 | 64,533 | 196,186 |
### 摘要
| 类别 | Zig 优势 | C 优势 | 平均 Zig 加速比 |
| --- | --- | --- | --- |
| **编译型** （C++、Rust、Go、Zig） | 14/14 | 0/14 | **2.5×** |
| **解释型** （JS、TS） | 1/6 | 5/6 | 0.3×* |
| **混合型** （C++/JS） | 1/1 | 0/1 | **4.5×** |
| **总体** | **16/22** | 5/22 | **1.8×** |
*\* 当安装 tree-sitter 语法时，JS/TS 差距缩小（React: 81s → 23s 使用语法）。*
### 二进制文件大小
| 指标 | Zig（ReleaseFast） | C 原始实现 | 比率 |
| --- | --- | --- | --- |
| 二进制文件大小 | **2.2 MB** | 257 MB | **117 倍更小** |
| 内存（空闲） | ~8 MB | ~120 MB | 15 倍更小 |
| 内存（索引） | ~50 MB | ~500 MB | 10 倍更小 |
> **关键见解**：Zig 在编译语言方面表现出色（Rust、Go、C++、Zig 仓库平均加速比 2.5 倍）。对于 JS/TS，tree-sitter 语法弥补了差距 — C 原始实现内部捆绑了 158 个语法，而 Zig 在运行时加载它们。
完整基准测试：[BENCH.md](BENCH.md)
## 架构
```
src/
├── main.zig # 入口点 — MCP 服务器 + CLI 分发器
├── mcp/ # JSON-RPC 2.0 框架
│ ├── protocol.zig # MCP 消息类型（initialize, tools/list, tools/call）
│ ├── tool.zig # ToolMeta 结构体 + 处理程序调度
│ └── transport.zig # 原始 POSIX I/O 标准输入/输出传输（C 读取/写入）
├── db/ # SQLite 持久化层
│ ├── connection.zig # 连接 + 预备语句包装器
│ ├── pool.zig # 线程安全连接池（信号量保护）
│ ├── schema.zig # 13 个表 + FTS5 + 触发器（兼容 C 原始实现）
│ └── cypher.zig # Cypher→SQL 翻译器
├── c/ # C 库绑定
│ ├── sqlite.zig # SQLite3（合并，WAL，64MB 缓存）
│ └── treesitter.zig # Tree-sitter v0.26.9（语法加载 via dlopen）
├── indexer/ # 9 阶段索引管道
│ ├── pipeline.zig # 协调器：扫描 → 解析 → 提取 → 写入
│ ├── scanner.zig # 文件遍历器（C opendir/readdir + stat）
│ ├── parser.zig # Tree-sitter 语法加载 + AST 解析
│ ├── extractor.zig # 单次 AST 遍历器（walkAll）
│ ├── fallback_extractor.zig # 正则表达式提取器（始终可用）
│ └── symbols.zig # IndexSymbol, IndexEdge, FileInfo 类型
├── search/ # 搜索引擎
│ ├── bm25.zig # FTS5 BM25，具有结构增强
│ └── grep.zig # 图增强模式搜索
├── analysis/ # 图谱分析
│ └── leiden.zig # Leiden 社区检测（模块化优化）
├── tools/ # 14 个 MCP 工具实现
│ └── registry.zig # 运行时调度表
├── model/ # 领域类型
│ └── graph.zig # NodeLabel, EdgeType 枚举，Node, Edge, Project
└── util/ # 实用工具
├── log.zig # 结构化日志
├── alloc.zig # 内存块 + 跟踪分配器帮助程序
└── json.zig # JSON 解析/序列化帮助程序
```
请参阅 [DEV.md](DEV.md) 获取详细模块文档和 Zig 0.16 API 速查表，以及 [PLAN.md](PLAN.md) 获取实现路线图。
## 配置
### 环境变量
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `CBM_CACHE_DIR` | 重写缓存目录 | `~/.cache/codebase-memory-mcp/` |
| `CBM_LOG_LEVEL` | 日志详细程度：`debug`、`info`、`warn`、`error`、`none` | `warn` |
### 持续性
所有数据存储在 `~/.cache/codebase-memory-mcp/`：
- `_config.db` — 项目注册表（项目名称、根路径、文件/边计数）
- `{project-hash}.db` — 每个项目的知识图谱（节点、边、FTS5 索引）
SQLite 数据库使用 WAL 日志模式进行并发读取。在索引过程中，配置数据库是 ACID 安全的。
## 团队共享图谱神器
索引大型仓库后，将图谱保存给您的团队：
```bash
# 索引仓库
cbm cli index_repository '{"repo_path":"/path/to/large-repo"}'
# 数据库位于 ~/.cache/codebase-memory-mcp/{repo}.db
# 压缩并提交到仓库
cp ~/.cache/codebase-memory-mcp/large-repo.db .codebase-memory/graph.db
zstd -9 .codebase-memory/graph.db -o .codebase-memory/graph.db.zst
git add .codebase-memory/graph.db.zst
git commit -m "chore: shared codebase graph"
# 队友：解压并从工件索引
zstd -d .codebase-memory/graph.db.zst -o ~/.cache/codebase-memory-mcp/large-repo.db
cbm cli search_graph '{"project":"large-repo","query":"handleRequest"}'
# → 立即结果，无需重新索引
```
将以下内容添加到 `.gitattributes` 以防止合并冲突：
```
.codebase-memory/graph.db.zst merge=ours
```
## 诊断
设置 `CBM_LOG_LEVEL=debug` 以获取索引和查询期间的详细输出。这对于分析缓慢操作或调试提取问题很有用。
```bash
CBM_LOG_LEVEL=debug cbm cli index_repository '{"repo_path":"/path/to/repo"}' 2> index.log
```
## 依赖项
| 库 | 版本 | 备注 |
| --- | --- | --- |
| SQLite | 3.49.1 | 合并，编译时 `-DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1` |
| Tree-sitter | 0.26.9 | 仅核心库 (`lib/src/*.c`)；语法在运行时加载 |
所有静态编译为 `build.zig` `addCSourceFile`。二进制文件 **无运行时依赖**。
## 测试
```bash
zig build test # 16 个测试，0 泄漏（DebugAllocator）
```
## 贡献
1. 阅读 [DEV.md](DEV.md) 获取架构文档和 Zig 0.16 API 速查表
2. 确保 `zig build test` 通过 0 泄漏
3. 遵循现有模块模式（所有工具在 `src/tools/` 中，DB 操作在 `src/db/` 中）
4. 更新 [PLAN.md](PLAN.md) 如果添加新功能
## 安全
- **100% 本地处理** — 您的代码从未离开您的机器
- **零网络调用** — 无遥测，无分析，无联系
- **静态二进制文件** — 所有依赖项在构建时编译和捆绑
- **无运行时解释器** — 无 Node.js、Python 或其他运行时需求
## 致谢
- **[DeusData](https://github.com/DeusData)** — 原始 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) C 实现的创建者。本次 Zig 重写基于他们的优秀架构、MCP 协议设计和属性图谱模式。原始的 14 种工具设计、Cypher 查询引擎和 Leiden 聚类方法在这里得到忠实复制。
## 许可
MIT — 请参阅 [LICENSE](LICENSE) 获取完整文本。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器