← 程式碼對照

src/mcp — MCP server

agent 怎麼跟圖對話：單一工具 + 自動傳遞的使用指引
檔案：src/mcp/ · server-instructions.ts 是主 agent 指引的單一來源

大方向

MCP server 把 CodeGraph 暴露給 agent。兩個關鍵設計：預設只列 codegraph_explore（其它 7 個工具可用但不列出），以及使用指引直接塞進 MCP initialize response——主 agent 不用看文件就知道怎麼用。sub-agent 與非 MCP harness 看不到那個 response，所以安裝器另寫 marker-fenced 段落進 instructions 檔（見 installer）。

server-instructions.ts src/mcp/MCP initialize 回傳的使用指引——主 agent 的單一來源。

內容重點：結構性問題直接答（圖就是 pre-built 索引，grep/read 是重複做工）；codegraph_explore 幾乎什麼都能用；相信結果別再 grep 驗證；編輯後看 staleness banner。README 說「The exact text is src/mcp/server-instructions.ts — the single source of truth for the main agent」，所以它必須與 user-facing tool guidance 保持同步（CLAUDE.md 特別註記）。

tools.ts / engine.ts src/mcp/工具定義與實作（explore 的組裝 + 7 個薄工具）。

tools.ts 定義工具清單與 CODEGRAPH_MCP_TOOLS allowlist 邏輯；engine.ts 組 explore 的答案（用 ContextBuilder + traverser）。7 個未列工具回的東西已內嵌在 explore 回應裡。projectPath 參數讓「server 自己 root 沒有索引」時也能查別的專案。

transport / daemon 連線 src/mcp/ + src/sync/stdio transport + 共享背景 server（local socket）。

agent 以 stdio 啟動 server。daemon 機制用 local socket 讓多個 session 共享一個背景 server（省資源）；WSL2 / Windows 磁碟路徑上 socket 不可靠時，server fallback 為 in-process 服務。CODEGRAPH_NO_DAEMON=1 強制每個 session 自己跑（見 疑難排解）。connect-time catch-up 在每次（重）連線時做快速對帳（見 自動同步）。

staleness banner / pending files src/mcp/debounce 窗口內，把「未入索引的檔」誠實告訴 agent。

explore 回應前檢查 CodeGraph.getPendingFiles()（見 main）：引用到 pending 檔 → 前置 ⚠️ banner 叫 agent 直接 Read；沒引用的 pending 檔 → 小 footer。已用 Claude Code 驗證 agent 會照做。

看完這頁你應該能說出：為什麼只有 explore 被列（其它工具已內嵌）、server-instructions 為什麼要與工具指引同步、daemon/socket 的 fallback 邏輯、以及 staleness banner 的資料來源。