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 代理的快速程式碼智慧伺服器

這是什麼 – codedb 是一個以 Zig 編寫的輕量級、無依賴伺服器，可為本地程式碼庫建立豐富的索引（三字詞全文、反向詞彙、符號輪廓、呼叫圖、相依圖等）。它透過 模型上下文協定 (MCP) 來公開這些索引 – 一個基於 stdio 的 JSON-RPC 接口，讓 AI 驅動的程式碼助理（Claude Code、Cursor、Gemini CLI、Codex 等）能呼叫以取得快速、結構化的程式碼上下文。它不會編輯檔案；編輯仍交由使用者的正常編輯器處理。

主要功能

結構化索引 支援多種語言（Zig、C/C++、Python、Rust、Go 等），並為其他語言提供輕量級輪廓。
三字詞加速搜尋 與 O(1) 詞彙查找。
符號查找、呼叫點發現 與 呼叫路徑 計算。
相依圖（匯入或 markdown 連結）與近期變更追蹤。
MCP 工具（22 個內建指令）讓代理可透過單一 RPC 呼叫執行。
HTTP 模式（codedb serve）支援非 MCP 用戶端。
檔案監視器 可增量更新索引（單一檔案重新索引耗時低於 2 毫秒）。

對 AI 代理的重要性 – 代理需要簡潔、節省 token 的上下文。codedb 僅回傳相關符號、呼叫者或程式碼片段的結構化 JSON（或純文字），與原始 grep/ripgrep 輸出相比，可將 token 使用量減少數百至數千倍。基準測試顯示查詢延遲低於毫秒（約 0.05 毫秒），遠低於傳統工具的 ~55 毫秒 CLI 啟動時間與 ~5–7 毫秒/搜尋時間。

安裝

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 伺服器（自動註冊至 Claude、Cursor 等）
codedb mcp /path/to/project

# 或以簡單 HTTP 守護程序運行
codedb serve /path/to/project   # 監聽 localhost:7719

常見代理工作流程：

目錄樹 – codedb_tree → 帶有符號數量的完整檔案樹。
輪廓 – codedb_outline src/main.zig → 帶行號的函式/結構。
符號 – codedb_find AgentRegistry → 定義位置。
搜尋 – codedb_search "handleAuth" → 三字詞快速全文搜尋。
呼叫者 / 呼叫路徑 – codedb_callers 或 codedb_callpath 用於追蹤使用情況。

所有這些皆可透過 HTTP（curl localhost:7719/...）或直接透過 AI 助理使用的 MCP JSON-RPC 通道呼叫。

架構（高階）

索引器 – 啟動時執行一次，解析支援的語言，建立：
- 三字詞索引（整數文件 ID，批次合併）用於快速模糊文字搜尋。
- 反向詞彙索引 用於 O(1) 標示符查找。
- 結構化輪廓（函式、結構、匯入）依檔案儲存。
- 相依圖 連結匯入或 markdown 連結。
快照 – 整個索引可序列化為 codedb.snapshot，以實現即時守護程序重啟。
MCP 伺服器 – 在 stdio 上的輕量級 JSON-RPC 2.0 層；每個工具為單一 RPC 方法，組合預先建立的索引。
檔案監視器 – 經過過濾的目錄遍歷會增量更新記憶體索引；單一檔案變更耗時低於 2 毫秒。
跨平台 – 提供 macOS（ARM 與 Intel）、Linux（ARM 與 x86_64）與 Windows 的原生二進位檔。

資料與隱私

僅在本機運作；除非啟用可選的 DeepWiki 遠端 MCP 以存取公開 GitHub 倉庫，否則不會產生網路流量。
HTTP 伺服器預設綁定至 localhost；不提供驗證層。
敏感檔案（.env、金鑰等）會自動排除於索引之外。

哪些人會使用它？

開發者 建構需要快速、節省 token 的程式碼上下文的 AI 程式碼助理。
團隊使用 Claude Code、Cursor、Gemini CLI 或類似代理，希望獲得即插即用的本地知識庫。
研究人員 探索程式碼的檢索增強生成（RAG）實驗。

目前狀態

Alpha – API 正在穩定中。核心功能（MCP 工具、三字詞搜尋、詞彙索引、結構化輪廓、相依圖）已可投入生產，每日使用。
持續進行的工作：更深入的解析器覆蓋、增量區段式索引、WASM 目標、多專案支援、mmap 支援的三字詞索引。

總結 – codedb 為 AI 代理提供快速、結構化的程式碼庫檢視，無需引入龐大的工具。其低於毫秒的查詢時間與極小的 token 使用量，使其成為任何 LLM 驅動程式碼工作流程的實用骨幹。