justrach/codedb

Zig code intelligence server and MCP toolset for AI agents. Fast tree, outline, symbol, search, read, edit, deps, snapshot, and remote GitHub repo queries.

codedb – 为 AI agent 提供快速的代码智能服务器

是什么 – codedb 是一个用 Zig 编写的轻量级、零依赖服务器，它能为本地代码库构建丰富的索引（trigram 全文检索、倒排词索引、符号轮廓、调用图、依赖图等）。它通过 Model Context Protocol (MCP) —— 一个基于 stdio 的 JSON-RPC 接口 —— 暴露这些索引，AI 编程助手（Claude Code, Cursor, Gemini CLI, Codex 等）可以调用它来获取快速、结构化的代码上下文。它不会编辑文件；编辑工作仍由用户常用的编辑器完成。

核心能力

结构化索引：支持多种语言（Zig, C/C++, Python, Rust, Go, …）并为其他语言提供轻量级轮廓。
Trigram 加速搜索 和 O(1) 单词查找。
符号查找、调用点发现 以及 调用路径 计算。
依赖图（import 或 markdown 链接）和近期变更追踪。
MCP 工具（内置 22 个命令）供 agent 可以通过单个 RPC 调用进行调用。
HTTP 模式 (codedb serve) 供非 MCP 客户端使用。
文件监听器 增量式地保持索引实时更新（单个文件的重新索引时间小于 2 ms）。

为什么对 AI agent 很重要 – Agent 需要简洁、节省 token 的上下文。codedb 返回结构化的 JSON（或纯文本）且仅包含相关的符号、调用者或代码片段，与原始的 grep/ripgrep 输出相比，token 使用量减少了数百到数千倍。基准测试显示，其查询延迟为亚毫秒级（≈0.05 ms）对比传统工具的 CLI 启动时间约为 55 ms 且每次搜索约 5-7 ms。

安装

macOS / Linux – 一行命令脚本会自动下载适当的已签名二进制文件，并自动在支持的 AI 编程工具中注册。
```
curl -fsSL https://codedb.codegraff.com/install.sh | bash
```

Windows – PowerShell 安装程序：

irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5841/install/install.ps1 | iex

npm – codedeebee 包是一个轻量级启动器，在安装时会获取原生二进制文件。CLI 仍然是 codedb。
所有二进制文件均经过 SHA-256 验证；macOS 构建版本是经过代码签名和公证的。

快速开始

# 启动 MCP server (会自动注册到 Claude, Cursor, 等)
codedb mcp /path/to/project

# 或者作为简单的 HTTP daemon 运行
codedb serve /path/to/project   # 监听 localhost:7719

典型 agent 工作流：

Tree – codedb_tree → 包含符号数量的完整文件树。
Outline – codedb_outline src/main.zig → 带有行号的函数/结构体。
Symbol – codedb_find AgentRegistry → 定义位置。
Search – codedb_search "handleAuth" → trigram 加速的全文检索。
Callers / Call-path – codedb_callers 或 codedb_callpath 来追踪使用情况。

所有这些都可以通过 HTTP (curl localhost:7719/...) 或直接通过 AI 助手使用的 MCP JSON-RPC 通道进行调用。

架构 (高层级)

Indexer – 在启动时运行一次，解析支持的语言，并构建：
- Trigram 索引（整数 doc IDs, 批量合并）用于快速模糊文本搜索。
- Inverted word 索引 用于 O(1) 标识符查找。
- 结构化轮廓（函数, 结构体, imports）按文件存储。
- Dependency graph 链接 import 或 markdown 链接。
Snapshot – 整个索引可以序列化为 codedb.snapshot 以实现 instant daemon restart。
MCP server – 基于 stdio 的轻量级 JSON-RPC 2.0 层；每个工具都是一个组合了预构建索引的单个 RPC 方法。
File watcher – 过滤后的目录遍历更新内存中的索引；单个文件变更的成本 < 2 ms。
Cross-platform – 支持 macOS (ARM & Intel), Linux (ARM & x86_64), 和 Windows 的原生二进制文件。

数据与隐私

仅在本地运行；没有任何网络流量，除非你启用了可选的 DeepWiki 远程 MCP 用于公共 GitHub 仓库。
HTTP server 默认绑定到 localhost；不提供身份验证层。
敏感文件 (.env, keys, 等) 会自动被阻止进行索引。

谁可能会使用它？

构建 AI 编程助手 的开发者，他们需要快速、节省 token 的代码上下文。
运行 Claude Code, Cursor, Gemini CLI, 或类似 agent 的团队，希望有一个即插即用的本地知识库。
研究人员 正在进行代码的检索增强生成 (RAG) 编写实验。

当前状态

Alpha – API 正在稳定化。核心功能（MCP tools, trigram search, word index, structural outlines, dependency graph）已达到生产就绪状态并被日常使用。
持续工作中：更深层的解析器覆盖范围、增量式基于段的索引、WASM target、多项目支持、mmap-backed trigram index。

总结 – codedb 为 AI agent 提供了一个快速、结构化的代码库视图，而无需引入重量级工具。其亚毫秒级的查询延迟和极小的 token footprint 使得它成为任何 LLM 驱动的编程工作流的实用后盾。