讀完本章後、你應該能對自己用的 tool / MCP server 回答：能讀寫哪些路徑、能跑哪些 shell command、能連哪些網路位址、副作用有沒有 dry-run / preview、出錯時怎麼回退。

本章目標

1. 認識 tool use 跟 MCP server 在三層架構中的位置。
2. 區分「讀取類 tool」跟「副作用類 tool」的權限判讀差異。
3. 知道個人 dev 場景下、第三方 MCP server 的信任邊界跟驗證流程。
4. 用「沙箱 / 白名單 / 副作用可逆性」三個維度評估具體 tool / MCP 的風險。
5. 認識常見的 tool use 副作用洩漏路徑跟對應的最低防護。

tool use 跟 MCP server 在哪一層

tool use 跟 MCP server 同時跨三層架構 的兩層、但跟模型本身的權限模型分離：

 1介面層（VS Code / Continue.dev / CLI）
 2  ↓
 3推論伺服器（Ollama / llama-server / LM Studio）
 4  ↓
 5模型（GGUF 權重）
 6
 7旁邊另一條：
 8  ↓
 9MCP server（獨立 process、自己的權限）
10  └── 對檔案 / shell / 網路的具體 API

關鍵特性：

1. 模型本身不執行 tool：模型只生成 tool call JSON、實際執行由「LLM client」（如 Continue.dev、Claude Desktop）跟 MCP server 完成。
2. MCP server 是獨立程式：可以是 Node / Python script、可以呼叫任何系統 API、權限上限是「跑該 server 的 user 的權限」。
3. 權限不是模型給的、是 OS / user 給的：模型再怎麼「同意」執行 rm -rf /、實際上能不能跑取決於 OS 的權限模型跟 MCP server 自己的 sandbox。

事實查核註：Model Context Protocol（MCP） 是 Anthropic 在 2024 年底發布的開放協議、各家 LLM client 跟 MCP server 實作的成熟度、權限粒度依版本演進。本章描述以 2026 年 5 月主流實作為基準、引用前以 MCP 官方規格跟各 client / server 的 README 為準。

「讀取類」跟「副作用類」tool 的權限差異

tool 可以粗分成兩類、權限判讀完全不同：

讀取類的判讀重點是「讀到的內容會被傳到哪」：

1. 讀到的 code 變 prompt 的一部分、prompt 送到本地模型→沒外洩
2. 同樣 prompt 送到雲端 LLM→傳到雲端、跟雲端 LLM 的資料政策走（見 6.4 跨雲端 / 本地資料邊界）
3. 讀取會被 log→log 累積、需要管理

副作用類的判讀重點是「可逆性」：

1. write file 蓋掉原內容→可能無法回復（沒備份的話）
2. run shell rm / git push→不可逆或需要 force pull 才能還原
3. 發 HTTP request、轉帳、call API→送出去就回不來
4. 操作 production 資料庫→可能影響其他人

三個維度評估具體 tool / MCP 的風險

對任何 tool / MCP server、可以用三個維度做初步評估：

 1┌────────────────────────────────────────────────────┐
 2│ 維度一：沙箱                                       │
 3│   能做什麼 = 跑該 server 的 user 能做什麼          │
 4│   有沒有 chroot / Docker / namespace 隔離？        │
 5│                                                    │
 6│ 維度二：白名單                                     │
 7│   能讀寫的路徑、能跑的指令、能連的網址有沒有限定？  │
 8│   還是 "all paths" / "any shell" / "any URL"？     │
 9│                                                    │
10│ 維度三：副作用可逆性                               │
11│   出錯能不能 rollback？                            │
12│   有沒有 dry-run / preview / confirm？             │
13└────────────────────────────────────────────────────┘

對應的判讀範例：

實務上、社群常見的 MCP server 多半屬於「白名單較弱」「副作用直接套用」的設計、需要使用者自己加防護。

第三方 MCP server 的供應鏈信任

MCP server 是可執行程式碼、信任邊界比 GGUF 模型權重高一個層級。常見的 MCP server 來源：

1. 官方 reference server（如 Anthropic 維護的 @modelcontextprotocol/server-*）：相對較高信任、有官方 maintain。
2. 知名專案的 MCP server（如 GitHub、Notion、Slack 等公司自己出的）：跟該公司的軟體分發信任度一致。
3. 社群 MCP server：個人或小團隊維護、信任度視 maintainer 與 download 量、看 code 是基本動作。

裝任何 MCP server 前的最低判讀：

1. 看 source repo：是不是知名作者、stars 數、最後 commit 時間、issues 是否活躍。
2. 看實際做什麼：MCP server 的 README 通常列出提供的 tools、跑起來會碰到的權限。
3. 跑在最小權限環境：能用 Docker / chroot / nice -n 19 之類就用、不要直接用 root / admin。
4. 不要用 curl | sh 安裝：用 npm install / pip install / go install 等有 package manager 介入的方式、留下 install log。

事實查核註：MCP server registry、套件管理工具的供應鏈安全機制依版本演進、Anthropic 跟其他主要 client 廠商可能引入官方 marketplace 或簽章機制、建議引用前以當前 MCP 官方狀態為準。

個人 dev 場景的最低防護建議

對「我想用 tool use 但又怕 LLM 把檔案搞壞」的工作流、最低防護建議：

1. codebase 用 git track：所有寫入操作前確認 working tree clean、出問題能 git checkout 還原。git stash 是更輕的選擇。
2. 重要檔案 backup：dotfile、SSH key、雲端 API key 等不在 git track 範圍的、用 Time Machine / rsync / cloud sync 之類做日常 backup。
3. 跑 LLM agent 時用獨立 user / 容器：對「想試 agent 但怕」的場景、開個專用 macOS user 或 Docker container、user 沒 sudo、檔案存取限定 workspace。
4. MCP server 的 config 加白名單：能設 allowed paths / allowed commands / allowed URLs 的 server 都先設、預設拒絕、按需開放。
5. 看不懂的 tool call 不要 confirm：Continue.dev / Claude Desktop 等 client 通常會 prompt 使用者確認 tool 執行、看不懂的 JSON 先別按。

tool use 副作用洩漏的常見路徑

個人 dev 場景常見的 tool use 副作用洩漏路徑：

1. LLM 誤把 secret 寫進 commit：tool use 帶 git commit、LLM 從 .env 讀到 API key 又寫進 commit message。對應防護：MCP server 加 .env 黑名單、commit hook 掃 secret。
2. LLM 套用 broken patch 蓋掉檔案：apply_patch 失敗 / 部分套用、留下無法 compile 的狀態。對應防護：套 patch 前 git stash 或 git add -p 先存 working tree。
3. LLM 從 issue / PR 內容引發指令：讀進 issue 的 prompt 內容包含 prompt injection、誘導跑非預期指令。對應防護：tool 跑前明確讓使用者確認（見 6.3 prompt injection）。
4. LLM 觸發 production 操作：MCP server 連到 production DB、LLM 跑 DROP TABLE。對應防護：production credential 絕對不放在 tool use 可達的環境。

給讀者的 tool / MCP 評估清單

每次裝新 MCP server / 啟用新 tool 之前、跑一次評估：

1[ ] 來源是知名作者 / 官方專案 / 我能 audit 的開源 repo
2[ ] README 列出的 tool 列表、跟我的使用情境匹配
3[ ] 該 server 跑在最小權限環境（user / sandbox / container）
4[ ] 副作用類 tool 有 confirm / preview 機制
5[ ] workspace 內容受 git track、能 rollback
6[ ] 不放 production credential / SSH key 在該 server 可達的環境
7[ ] 啟用後跑簡單測試、確認 tool call 行為符合預期

下一章

下一章：6.3 IDE 場景的 prompt injection、處理 tool use 副作用最常見的觸發來源。

狀態：大綱階段、部分章節待完成內容。

本模組整理 LLM 應用層的核心原理：模型裝起來、能對話之後、要怎麼跟外部世界互動、怎麼組成可用的工作流、怎麼測它跑得對不對。模組零到模組三建立的是「模型本身」的心智模型；本模組建立的是「模型作為系統元件」的心智模型。

寫這個模組的核心約束是「只寫不會過時的部分」。LangChain、LlamaIndex、aider、Cline 等工具半年一個世代、寫具體 API 半年後就過時；但「retrieval 在做什麼」「為什麼 LLM 需要 tool use」「agent loop 為什麼會失敗」「eval 軸怎麼選」這些原理跨工具世代都成立。本模組刻意避開具體實作教學、把焦點放在跨世代的設計取捨。

章節列表

為什麼這個順序

本模組章節順序的設計脈絡：

1. 先 4.0 Prompt 技術光譜：within-call 增強是後續所有設計的基底、先建立「prompt 層能做什麼、邊界在哪」的座標。
2. 接 4.1 RAG 原理 + 4.2 RAG 檢索增強：應用層最常見的模式、把「LLM + 外部知識」這個基本組合走過一遍、概念對映到每個讀者都用過的 @codebase 等實務經驗。
3. 再 4.3 Tool use：RAG 是「LLM 讀外部資料」、Tool use 是「LLM 對外部世界做事」、兩條延伸方向自然接續。
4. 再 4.4 Agent 架構 + 4.5 人機協作：把 Tool use 從「單次呼叫」延伸到「自主多步」、自然進入 agent；agent 自主後立刻面對人類介入時機問題。
5. 再 4.6 應用層協議：前面章節涉及 function calling、structured output、MCP 等術語、本章把這三個概念放回正確的層級、避免混為一談。
6. 再 4.7 Workflow + 4.8 Multi-agent：上層整合、把多 LLM call 跟多 agent 組合的設計模式整理成跨 framework 不變的概念地圖。
7. 4.9 起進入 production / 細節：部署資源、衍生產物管理、long context、embedding 內部、eval / benchmarking、tracing、judge——每個都是 production 場景遇到的具體議題。
8. 最後 hands-on：把上述所有原理串成具體案例、看「實際做的時候、原理怎麼落」。

每章可以單獨讀、但若你是第一次接觸 LLM 應用層、照順序讀最不容易迷路。

跟其他模組的分工

適合的讀者

不在本模組內的主題

1. 具體 framework 教學：LangChain、LlamaIndex 等的 API 用法、隨版本變、交給官方文件。
2. 具體 prompt 寫法：跨模型跨任務不可遷移、本模組 4.0 寫的是 prompt 技術 landscape 的結構、不是具體寫法。
3. 具體 agent 工具配置：aider、Cline 等的安裝設定、隨工具版本變、見 1.6 延伸方向 的入口資訊。
4. 訓練 / fine-tuning：屬於改變模型本身、見 3.4 訓練流程。

驗證日期：2026-05-12 環境：Python 3.11+、stdlib only（json / subprocess / urllib） 依賴：RAG demo 的 index.pkl（見 RAG demo） 協議版本：MCP 2025-03-26

MCP 是什麼層的東西

回顧 4.6 應用層協議 的層級劃分：

• Function calling：模型訓練建立的能力（模型層）。
• Structured output：sampling 階段約束（推論層）。
• MCP：LLM application ↔ 外部 tool server 的協議（架構層）。

MCP 不管「模型怎麼呼叫工具」、它管「工具怎麼被暴露給 application」。本 demo 寫的是 server 端：server 不知道是哪個 LLM 在用它、不假設客戶端用 function calling 還是 structured output、它只專注「把 tool 透過 JSON-RPC 暴露出去」。

這跟 OpenAI 相容 API 的設計哲學一致：定義最小可用標準、讓生態繞著標準長。

前置設定

不需要安裝 MCP SDK——本 demo 手寫 JSON-RPC 處理、為了 inspection 透明度。Production server 建議改用 官方 SDK（Python / TypeScript 都有）、處理 framing、capability negotiation、transport edge cases。

MCP 協議的最小子集

MCP server 要 handle 的核心 method：

四個 method 之外、還可以暴露 resources / prompts / sampling、本 demo 只做 tools。

Server 實作

完整檔案：scripts/mcp-demo/blog_mcp_server.py、約 150 行。

主迴圈：讀 stdin、分派 method、寫 stdout

 1def main():
 2    log(f"[blog-mcp-demo] starting, index={INDEX_PATH}, tools={list(TOOLS.keys())}")
 3    for line in sys.stdin:
 4        line = line.strip()
 5        if not line:
 6            continue
 7        try:
 8            msg = json.loads(line)
 9        except json.JSONDecodeError as e:
10            log(f"  parse error: {e}")
11            continue
12        method = msg.get("method")
13        rid = msg.get("id")
14        params = msg.get("params", {})
15        log(f"  → {method} (id={rid})")
16        if method not in HANDLERS:
17            respond(rid, error={"code": -32601, "message": f"Method not found: {method}"})
18            continue
19        handler = HANDLERS[method]
20        if handler is None:
21            continue  # notification, no response expected
22        try:
23            result = handler(params)
24            respond(rid, result=result)
25        except Exception as e:
26            log(f"  ✗ handler error: {e}")
27            respond(rid, error={"code": -32000, "message": str(e)})

每段做什麼：

1. log(...) 開機訊息：印到 stderr（不是 stdout）、讓人類能看到 server 啟動了、什麼 tools 可用。stdout 完全保留給 JSON-RPC 用。
2. for line in sys.stdin：MCP 的 stdio transport 是 line-delimited JSON—— 每個 message 一行、\n 結束。Python 的 file iteration 自動按行切。
3. line.strip() + if not line：空行 skip（不是 protocol error、只是 idle）。
4. json.loads(line) with try / except：parse 失敗（malformed input）不 crash、log error 繼續下一行。Protocol 訊息該是合法 JSON、parse error 表示 client 出錯。
5. msg.get("method") / msg.get("id") / msg.get("params", {})：JSON-RPC 2.0 標準三個欄位。get 而不是 []、避免 KeyError；params 預設空 dict、後面 handler 可以安全 .get("xxx")。
6. if method not in HANDLERS: respond(rid, error={"code": -32601, ...})：未知 method 回標準 JSON-RPC error -32601（Method not found）。Client 知道這個 method 不能用、但 server 不死。
7. if handler is None: continue：notification（如 notifications/initialized）對應的 handler 是 None、不該回 response。
8. try: result = handler(params); respond(rid, result=result)：呼叫 handler、把結果回給 client。
9. except Exception as e: ... respond(rid, error={"code": -32000, ...})：handler 內部錯誤回 -32000（generic server error）。確保 server 任何時候都不 crash、即使工具 bug 也讓 client 拿到 error response。

為什麼這樣設計：

• 為什麼用 line-delimited JSON、不是 length-prefixed：MCP spec 規定 stdio transport 是 newline-delimited。length-prefixed 是 LSP 的做法、解析複雜（要先讀 Content-Length header 再讀 N bytes）；newline-delimited 用 for line in sys.stdin 一行解決。
• 為什麼 stderr 不能寫 stdout：stdio transport 的 invariant——stdout 是 protocol channel、只能寫 JSON-RPC message。任何 stray print() / debug output 進 stdout、會被 client parse JSON 時炸（「multiple JSON values on one line」或 invalid JSON）。所有 log / debug / progress message 必須走 stderr。寫錯這條 server 看起來不工作、debug 很久才找到。
• 為什麼 dispatch 用 dict-of-handlers 而不是 if/elif chain：擴充性。加新 method 只要往 HANDLERS dict 加一項、不用改 main loop。也讓 dispatch logic 跟 method 實作分離、容易測試。
• 為什麼每個 handler 都用 try/except 包：「single point of failure」設計——任何 handler 例外不影響其他 method。Server 應該是 long-running daemon、不能因為一個 tool bug 死掉。
• 為什麼 errors 用 JSON-RPC error code 而不是 HTTP-style status：JSON-RPC 2.0 標準。-32700 parse error、-32600 invalid request、-32601 method not found、-32602 invalid params、-32603 internal error、-32000 to -32099 留給應用層自訂。

工具：search_blog

 1def tool_search_blog(query: str, top_k: int = 5) -> dict:
 2    records = load_index()
 3    q_vec = embed(query)
 4    scored = sorted(
 5        ((cosine(q_vec, r["embedding"]), r) for r in records),
 6        key=lambda x: x[0],
 7        reverse=True,
 8    )[:top_k]
 9    results = [
10        {
11            "source": r["source"],
12            "chunk_index": r["chunk_index"],
13            "score": round(score, 4),
14            "preview": r["text"][:160] + ("..." if len(r["text"]) > 160 else ""),
15        }
16        for score, r in scored
17    ]
18    return {"content": [{"type": "text", "text": json.dumps(results, ensure_ascii=False, indent=2)}]}

每段做什麼：

1. records = load_index()：lazy load index.pkl、第一次 call 載入記憶體、後續直接用 cached。Server 啟動時 lazy load 而不是 import 時 load、讓 server 即使在 Ollama 還沒起 / index 不存在時也能 boot（之後 call 才會報 error）。
2. q_vec = embed(query)：把 query 轉成 768 維向量、呼叫 Ollama embedding API、跟 RAG demo 的 embed 是同一個 function。
3. sorted((...) for r in records, key=lambda x: x[0], reverse=True)[:top_k]：generator expression + sorted 一次完成「算分 → 排序 → 取 top-K」。
4. results = [{...} for score, r in scored]：把 top-K 整理成 client 友善的 dict 結構、含 source、chunk_index、score、preview（前 160 字 + 省略號）。
5. {"content": [{"type": "text", "text": json.dumps(...)}]}：MCP tools/call 標準 response 格式——content 是 array、每個元素 type + payload。type: "text" 是文字 content、text 是實際內容（這裡是 JSON 字串、讓 LLM 可以 parse）。

為什麼這樣設計：

• 為什麼 generator expression 而非 list comprehension：(... for r in records) 是 generator、sorted 直接消費、不會在記憶體中建中間 list。對 463 records 影響不大、但展現 memory-efficient pattern。
• 為什麼 preview 切到 160 字：兩件事的平衡——讓 LLM 看到的 search result 短（不淹沒 LLM 的 context）、但夠判讀（160 中文字約 80 token、能看出 chunk 是不是相關）。如果 LLM 要完整內容、再 call read_chunk。
• 為什麼回傳 JSON 字串、不是 nested object：MCP content 規定每個 element 是 {type, payload}、type: "text" 的 text 必須是 string、不能直接放 nested object。要傳結構化資料、就把它 json.dumps 成字串。LLM 看到後可以自己 parse。
• 為什麼 ensure_ascii=False：預設 json.dumps 把非 ASCII 字元（如中文）轉成 \uXXXX、難讀。ensure_ascii=False 直接輸出 UTF-8、LLM 也能直接讀懂、節省 token 數（一個中文字 1 token vs 6 token 的 中）。
• 為什麼 round(score, 4)：score 是 float、原始可能是 0.7497284598827362、長且無意義。round(score, 4) 保留 4 位小數、0.7497、夠精確、wire size 短。

工具：read_chunk

1def tool_read_chunk(source: str, chunk_index: int) -> dict:
2    records = load_index()
3    for r in records:
4        if r["source"] == source and r["chunk_index"] == chunk_index:
5            return {"content": [{"type": "text", "text": r["text"]}]}
6    return {
7        "content": [{"type": "text", "text": f"Not found: {source}#chunk{chunk_index}"}],
8        "isError": True,
9    }

每段做什麼：

1. for r in records: if r["source"] == source and r["chunk_index"] == chunk_index: return ...：linear scan 找匹配的 record、找到回完整 text。
2. 找不到時 return {... "isError": True}：MCP 標準的「tool 內部失敗」訊號。isError: True 告訴 client「這個 tool call 失敗了」、content 內是 human-readable error message。

為什麼這樣設計：

• 為什麼 linear scan 而不是 dict lookup：可以改用 {(source, chunk_index): record} dict 變 O(1)。但 463 records 的 linear scan 是 < 1ms、optimize 不值得。Production 跟 vector DB 整合時、retrieval 系統自帶 indexing。
• 為什麼 isError: True 而不是 JSON-RPC error：分兩種錯誤：
  • Protocol error：method 不存在、params 不合法、JSON parse 失敗——回 JSON-RPC error 物件。
  • Tool semantic error：method OK、params OK、但 tool 邏輯上不能 complete（找不到資料、外部 service down）——回 normal response 加 isError: True。 MCP 設計這層分離、讓 client / LLM 區分「我做錯了」（協議層）跟「資料不存在」（語意層）。Production 設計工具時要仔細區分。

Tool 描述用 JSON Schema

 1TOOLS = {
 2    "search_blog": {
 3        "description": "Semantic search over blog content. Returns top-K relevant chunks with source paths.",
 4        "inputSchema": {
 5            "type": "object",
 6            "properties": {
 7                "query": {"type": "string", "description": "Natural language query"},
 8                "top_k": {"type": "integer", "default": 5, "minimum": 1, "maximum": 20},
 9            },
10            "required": ["query"],
11        },
12        "fn": lambda args: tool_search_blog(args["query"], args.get("top_k", 5)),
13    },
14    "read_chunk": {
15        "description": "Read the full text of a specific chunk by source path and chunk index.",
16        "inputSchema": {
17            "type": "object",
18            "properties": {
19                "source": {"type": "string", "description": "Markdown file path relative to content/"},
20                "chunk_index": {"type": "integer", "minimum": 0},
21            },
22            "required": ["source", "chunk_index"],
23        },
24        "fn": lambda args: tool_read_chunk(args["source"], args["chunk_index"]),
25    },
26}

每個 field 角色：

1. description：給 LLM 看的、解釋這個 tool 解什麼問題。LLM 看 description 決定何時 call。這是模型 follow tool 的最主要訊號——寫得清晰具體、模型用得對。
2. inputSchema：JSON Schema、描述 tool 接受的參數結構。LLM application 用這個 schema 約束 LLM 生成「合法的呼叫」。
3. properties：每個參數的型別 + 約束。
4. required：必填參數清單。LLM 漏掉時、client 端可以 reject、不會浪費 round-trip。
5. default：可選參數的預設值。傳的時候不給、tool 就用 default。
6. minimum / maximum：數值約束。top_k 設 1-20 是因為 < 1 沒意義、> 20 浪費 retrieval。
7. fn：實際 dispatch 用的 callable。本 demo 用 lambda 把 args dict 轉成 positional / keyword call。

為什麼這樣設計：

• 為什麼 description 要具體：LLM 看 description 決定 call 時機。「search the blog」對 LLM 來說太模糊（搜什麼？找什麼？）、改成「Semantic search over blog content. Returns top-K relevant chunks with source paths.」明確描述輸入跟輸出形狀、LLM 能判讀「使用者問技術問題時該 call 這個」。
• 為什麼 schema 用 JSON Schema、不是自訂格式：JSON Schema 是 web 標準、所有 LLM application 都認識、跨 framework 可移植。也是 function calling 跟 Tool use 原理 的 schema 描述語言。
• 為什麼 required 跟 default 兩個機制：對 LLM 看的 prompt 越清楚越好。required 告訴 LLM「不傳這個會錯」、default 告訴 LLM「可不傳、預設值是 X」。沒分清的話、LLM 可能總是傳所有參數、雜訊多。
• 為什麼 fn 用 lambda 包：實際 tool function 是 positional args、但 client 送的是 dict。lambda 把 dict 拆成 function call 的 args。也方便將來如果 tool function signature 變、只要改 lambda 不用改 dispatcher。

Client 實作（測試用）

完整檔案：scripts/mcp-demo/test_client.py。實際 production 用 Claude Desktop / Cursor 等 MCP-capable application。本 demo 寫一個 stdio client、模擬 application 行為：

 1proc = subprocess.Popen(
 2    [sys.executable, str(SERVER)],
 3    stdin=subprocess.PIPE,
 4    stdout=subprocess.PIPE,
 5    stderr=subprocess.PIPE,
 6    text=True,
 7    bufsize=1,
 8)
 9
10def send(method, params=None, rid=None):
11    msg = {"jsonrpc": "2.0", "method": method}
12    if params is not None:
13        msg["params"] = params
14    if rid is not None:
15        msg["id"] = rid
16    proc.stdin.write(json.dumps(msg) + "\n")
17    proc.stdin.flush()
18    if rid is None:
19        return None  # notification
20    line = proc.stdout.readline()
21    return json.loads(line)

每個參數做什麼：

1. subprocess.Popen([sys.executable, str(SERVER)], ...)：spawn server 當 child process。用 sys.executable 確保用同一個 Python interpreter（避免 venv 跟系統 Python 混用）。
2. stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE：三條 pipe 都接到 client、讓我們能讀寫 server 的 stdio。
3. text=True：自動處理 str ↔ bytes 編碼、直接讀寫字串、不用手動 encode/decode。預設是 binary mode。
4. bufsize=1：line buffering、每寫一行就 flush。沒這個的話、Python 預設 block buffering（4KB 才 flush）、client 寫的 message server 看不到、整個卡住。
5. proc.stdin.write(json.dumps(msg) + "\n")：寫 JSON 訊息、結尾加 \n（line-delimited）。
6. proc.stdin.flush()：強制立刻送出。即使有 bufsize=1、明確 flush 是好習慣、避免任何 buffer 累積。
7. if rid is None: return None：notification 不該等 response。
8. line = proc.stdout.readline() + json.loads(line)：讀一行 response、parse。

為什麼這樣設計：

• 為什麼 stdio 而不是 socket / HTTP：MCP stdio transport 的主要場景是「application spawn server」(Claude Desktop 開 Python 進程當 MCP server)。Stdio 自然形成 1-to-1 ownership、不需要 port allocation、不需要 auth。HTTP transport 也存在、用在 multi-client 場景。
• 為什麼 bufsize=1 這麼關鍵：Python 預設 stdio buffer 4KB。如果 server / client 任一邊寫了 short message 但沒 fill 4KB、message 不會被另一邊看到、protocol 卡死。看起來是 hang、debug 困難。bufsize=1 強制 line buffering、解決這個 deadlock。
• 為什麼 text=True：JSON-RPC 都是文字、binary mode 要手動 .encode() / .decode()、增加複雜度。text=True 自動處理 UTF-8。

跑通整條流程

1cd ~/Projects/blog
2python3 scripts/mcp-demo/test_client.py

• cd ~/Projects/blog：切到 repo 根、讓 SERVER 路徑相對解析正確。
• python3 scripts/mcp-demo/test_client.py：跑 test client、它會 spawn server 跟它對話。

預期看到五個階段：

1. initialize（握手）

 1=== 1. initialize ===
 2{
 3  "jsonrpc": "2.0",
 4  "id": 1,
 5  "result": {
 6    "protocolVersion": "2025-03-26",
 7    "capabilities": {"tools": {}},
 8    "serverInfo": {"name": "blog-mcp-demo", "version": "0.1.0"}
 9  }
10}

Protocol 意義：

• protocolVersion：server 支援的 MCP 版本。Client 要 negotiate（自己 cap 較新時要 downgrade）。
• capabilities.tools: {}：server 宣告「我支援 tools 功能」、空 object 表示沒額外 sub-feature。Client 拿到後知道可以 call tools/list。
• serverInfo：server 識別資訊、給 client 顯示用（debug、logging）。
• id: 1：對應 client 送的 request id、讓 client 知道這個 response 是哪個 request 的。

2. tools/list

Server 回兩個 tool 的完整 schema：

 1{
 2  "tools": [
 3    {
 4      "name": "search_blog",
 5      "description": "Semantic search over blog content...",
 6      "inputSchema": {...JSON Schema...}
 7    },
 8    {
 9      "name": "read_chunk",
10      "description": "Read the full text of a specific chunk...",
11      "inputSchema": {...}
12    }
13  ]
14}

Protocol 意義：這個輸出就是 LLM application 會塞給 LLM 的 tool 描述。LLM application 把這份 schema 用 function calling 機制給模型看、模型決定何時呼叫、傳什麼參數。Server 跟模型之間靠這層 schema 對齊、模型不直接呼叫 server、是經 application 中介。

3. tools/call: search_blog

Client 送：

1{
2  "method": "tools/call",
3  "params": {
4    "name": "search_blog",
5    "arguments": {"query": "什麼是 KV cache？", "top_k": 3}
6  },
7  "id": 3
8}

params 包兩件事：

• name：要 call 的 tool 名（matches tools/list 內某個 tool）。
• arguments：實際傳給 tool 的 dict、結構符合該 tool 的 inputSchema。

Server 回 cosine 搜尋結果（preview）：

1[
2  {"source": "llm/00-foundations/hardware-memory-budget.md", "chunk_index": 5, "score": 0.7497, "preview": "| Context 長度 | KV cache 估算..."},
3  {"source": "llm/00-foundations/why-llm-feels-slow.md", "chunk_index": 4, "score": 0.7212, "preview": "..."},
4  {"source": "llm/03-theoretical-foundations/attention-mechanism.md", "chunk_index": 7, "score": 0.7176, "preview": "..."}
5]

實測命中合理——KV cache 相關段落都被找到。

4. tools/call: read_chunk

Client 用 search 拿到的 source + chunk_index、call read_chunk 拿完整內容：

 1{
 2  "method": "tools/call",
 3  "params": {
 4    "name": "read_chunk",
 5    "arguments": {
 6      "source": "llm/00-foundations/hardware-memory-budget.md",
 7      "chunk_index": 5
 8    }
 9  }
10}

Server 回該 chunk 的完整 markdown 文字。這實現了「search → read」的兩段流程——避免 search 一次就把所有 chunk 完整內容塞給 LLM（context 暴炸）、讓 LLM 自己看 preview 決定要 deep dive 哪個。

5. 錯誤路徑

1=== 5. unknown method (error path) ===
2{"jsonrpc": "2.0", "id": 5, "error": {"code": -32601, "message": "Method not found: does/not/exist"}}

-32601 是 JSON-RPC 標準 error code for unknown method。Server 對未知 method 回標準 error、不 crash。Client 知道這個 method 不能用、繼續其他操作。

跟 Claude Desktop / Cursor 整合

把這個 server 接到實際 MCP-capable application：

Claude Desktop

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json：

1{
2  "mcpServers": {
3    "blog-search": {
4      "command": "/path/to/python3",
5      "args": ["<absolute-path-to-blog>/scripts/mcp-demo/blog_mcp_server.py"]
6    }
7  }
8}

每個 field 做什麼：

• mcpServers：MCP server 註冊表、key 是任意名稱（client 識別用）。
• command：spawn 用的 executable path。要寫絕對路徑、Claude Desktop 啟動時的 PATH 可能不含 python3。
• args：傳給 command 的 args list。第一個是 script path。

為什麼這樣設計：Claude Desktop 啟動時讀這個 config、對每個 server 用 subprocess.spawn(command, args) 起 child process、用 stdio 跟它對話。跟本 demo 的 test_client.py 做的事完全一樣、只是改成 GUI application 而已。

重啟 Claude Desktop 後、在對話框問「用 search_blog 找 KV cache 相關段落」、Claude 會自動 call tool 並用結果回答。

Cursor

.cursor/mcp.json（per-project）或全域設定類似結構。具體欄位看當下版本文件。

兩種整合的共通點：MCP server 自己不變、只要 application 端配置 path 跟 args、整合就完成。這正是 4.3 章節 N×M → N+M 的具體展現——本 server 不為任何特定 application 客製化、就能被多個 application 接到。

觀察跟原理對應

回到 4.6 應用層協議 的三層 framing：

這個分離正是 MCP 的核心收益：server 寫好之後、用什麼 LLM 跟它互動跟 server 無關。換掉 LLM、換掉 application、server code 完全不動。

何時這份 demo 會過時

• MCP protocol version：目前用 2025-03-26、未來會更新、但「server 暴露 tool 給 application」的 framing 不變。
• JSON-RPC 細節：可能 transport 形式增加（HTTP / WebSocket）、stdio 不會消失。
• Tool 描述格式：JSON Schema 是 web 通用標準、不會被換掉。

實作換代時、可以把手寫 JSON-RPC 換成官方 SDK、tool 內部邏輯（embedding / cosine / pickle）依需求換、但 protocol 骨架（initialize / tools/list / tools/call）會保留。

跑這個 demo 的指令總結

1# 前置：確認 Ollama 跑著、index.pkl 存在
2ollama list | grep nomic-embed-text
3ls scripts/rag-demo/index.pkl

• ollama list：列已下載 model、grep 過濾出 embedding model。沒看到表示要先 ollama pull nomic-embed-text。
• ls scripts/rag-demo/index.pkl：確認 RAG ingest 跑過、index 存在。沒看到要先跑 python3 scripts/rag-demo/ingest.py。

1# 自動測試 MCP server
2python3 scripts/mcp-demo/test_client.py

• 跑 test_client、spawn server、依序送 5 個 request 驗證 protocol。stdout 印 protocol 對話、stderr 印 server log。看到全部 5 階段 OK 就成功。

1# 手動跟 server 互動（看 protocol 原始 wire format）
2python3 scripts/mcp-demo/blog_mcp_server.py
3# 然後手打：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

• 直接 invoke server、它讀 stdin 等 request。手打 JSON-RPC 訊息、看 server 回。是學 protocol 最直接的方式——你會看到 wire format 真實長相、跟自動 client 包裝後不一樣。

完整 source 在 scripts/mcp-demo/、約 250 行 Python、stdlib only。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、本 demo 依賴的索引由 RAG demo ingest 產生、MCP + RAG 同跑的記憶體 / 程序預算見 RAG + MCP resource footprint、術語見 MCP。

本章把三者的層級差異拆開、解釋為什麼會出現 MCP、跟它們在實際應用中怎麼組合。具體 spec 細節（OpenAI function calling JSON 格式、Anthropic tools API、MCP server 實作）不在本章——這些半年一變、本章寫的是「換 spec 之後仍成立」的概念結構。

本章目標

讀完本章後你能：

1. 用一句話分別說清楚三者解什麼問題。
2. 看到「啟用 function calling」「設定 structured output」「裝 MCP server」這些句子時、知道在說哪一層。
3. 判斷一個 LLM 應用該用哪幾個組合、什麼情境只需要一部分。
4. 解釋為什麼 MCP 會出現、它複用了哪個成功模式。

三個概念的層級差異

三者正交、可獨立或組合：

• 用 function calling 但不用 structured output：訓練過 tool use 的模型直接呼叫工具、靠模型自律輸出合法 JSON。
• 用 structured output 但不用 function calling：模型沒訓練過 tool use、用 prompt + grammar 強制輸出合法格式。
• 用 MCP 但不用 function calling：MCP 標準化 tool 的暴露方式、模型用什麼機制呼叫不重要。
• 三者都用：function calling 讓模型穩、structured output 約束格式、MCP 提供 tool ecosystem。

把這張表記熟、再看 LLM 應用相關討論、會發現「這個工具支援 function calling」「我的應用要 MCP」這類句子實際在說不同層級。

Function Calling 是模型能力

Function calling 是模型在訓練階段建立的能力：SFT 階段大量「使用者 query + 該呼叫什麼工具 + 傳什麼參數」的範例、讓模型學會「看到 query 知道何時呼叫、怎麼呼叫」。

判讀模型 function calling 強弱的訊號：

• 該呼叫時呼叫、不該呼叫時不呼叫的準確度。
• 呼叫格式合法率（不亂寫 JSON）。
• 參數準確度（type 正確、value 合理）。
• 多工具情況下選對工具的準確度。

這四個訊號跨模型差異大、根因是訓練資料分佈：

• OpenAI / Anthropic 旗艦模型 SFT 階段 function calling 範例大量、表現穩定。
• Llama 3 / Gemma 4 / Qwen3 開源旗艦模型 SFT 階段也加 function calling、但範例量不一、表現有落差。
• 小型開源模型（< 14B）function calling 訓練嚴重不足；tool schema 複雜、多工具選擇、巢狀參數時失敗率高、單一工具 + 平坦 schema 仍可用。

理解這點的價值：看到「這個模型支援 function calling」的宣稱、要追問「訓練範例 coverage 多廣」、不是 binary 的支援 / 不支援、是 spectrum 的訓練深度。

Structured Output 是 Sampling 約束

Structured output 是推論階段的技巧、跟模型訓練無關：在 sampling（從機率分佈挑下一個 token 的步驟）時對每個 token 做 grammar / schema 約束、不合法 token 的機率（logit、token 機率的對數）被歸零、把不合法輸出的可能性壓到不會被 sample。

主要實作機制（適用 / 限制條件附在每項下）：

• JSON mode：每步 sampling 過濾、只允許「保持 JSON 仍合法」的 token。適用：絕大多數 OpenAI 相容 API 都有支援；限制：只保 JSON 合法、不保 schema 對位。
• Grammar-constrained sampling：用 grammar（描述合法語法的形式化規則、實作上常用 BNF 或 Lark grammar）描述完整輸出形狀、推論時逐 token 過濾。適用：需要嚴格自訂格式（DSL、特定 query language）；限制：要伺服器層支援（llama.cpp、vLLM 有、有些雲端 API 沒）。
• Schema-guided：依 JSON Schema 動態決定每步允許哪些 token、強制 enum / type / required 等約束。適用：複雜結構化資料；限制：實作複雜度高、跨伺服器一致性差。
• Logit bias：對特定 token 加 bias、間接引導 sampling、最弱但最靈活的方式。適用：簡單的 token 黑名單 / 白名單；限制：無法保證結構合法。

優勢相對 function calling：

• 跨模型可移植：不依賴模型訓練、任何能跑 sampling 的模型都能上。
• 可任意自訂格式：不限於 OpenAI 或某 provider 的 function spec、想定義什麼 schema 都行。
• 保證 100% 合法輸出：grammar 約束下不可能輸出 invalid JSON。

代價：

• 約束太嚴可能跟模型「自然」輸出衝突：模型本來想說 A、grammar 強制只能說 B、品質會降。
• 實作成本：grammar 解析跟動態 logit mask 在推論伺服器要支援、不是所有 server 都成熟。
• 跟模型訓練脫鉤：模型「不知道」自己被約束、可能還是用沒用 function calling 訓練的「猜測」方式生成。

實務上 structured output 跟 function calling 經常組合：function calling 訓練讓模型「自然」傾向合法輸出、structured output 約束兜底保證「真的合法」。

MCP 是 Server 協議

MCP（Model Context Protocol、2024 年由 Anthropic 提出）是「LLM application ↔ 外部 tool server 之間的標準化協議」。它不在模型能力層、不在 sampling 層、是更高層的架構規範。

要理解 MCP 的定位、回顧 LLM 生態的歷史問題：

每個 LLM application（Cursor、Continue.dev、Claude Desktop、aider 等）要接每個 tool（檔案系統、資料庫、search、自訂 API），都得寫 adapter。N 個 application × M 個 tool 的整合成本是 N×M、生態擴張時成本爆炸。

MCP 把這個成本拆成兩段：

• LLM application 端：實作 MCP client（一次）、之後支援任意 MCP server。
• Tool 端：實作 MCP server（一次）、之後被任意 MCP client 接到。

整合成本從 N×M 降到 N+M。同樣的 ecosystem effect 跟模組零的 OpenAI 相容 API 一樣——標準化中介把生態整合複雜度從乘法降到加法。

MCP 涵蓋的「server 該提供什麼」包括：

• Tool 註冊（這個 server 提供哪些 tool）。
• Tool schema（每個 tool 的參數定義）。
• Tool 呼叫協議（呼叫方式 + 回應格式）。
• Resource 暴露（檔案、文件等讀取資源）。
• Prompt template 共享（reusable system prompt）。

這些都在 protocol 層、模型怎麼用 tool（function calling 還是 structured output）不在 MCP 規範範圍——MCP 不管你模型強不強、它只管「tool 怎麼被暴露」。

為什麼會出現 MCP

MCP 是 LLM application 生態擴張到一定程度後的必然產物。觀察生態演化：

• 2023 早期：每個 LLM app 各自寫工具整合、Cursor 接 file system、Continue.dev 接 codebase、aider 接 git——各自的 adapter 邏輯互不通用。
• 2024 中期：function calling spec 標準化（OpenAI 跟 Anthropic 各自定義）、解決「模型怎麼呼叫工具」、但「工具怎麼暴露給 application」還是各家自己處理。
• 2024 底：Anthropic 提 MCP、把「工具暴露」也標準化、補完 ecosystem 拼圖。

複用 OpenAI 相容 API 的成功模式：

• OpenAI 相容 API：標準化「介面層 ↔ 推論伺服器」、所有 IDE plugin 都接這個。
• MCP：標準化「LLM application ↔ tool server」、所有 application 都接這個。

兩者都採用同個策略：定義最小可用標準、讓生態繞著標準長、所有 player 受益。

MCP 成熟度判讀訊號（不固化在某一個時間點、用這幾個 signal 重新評估）：

• Application 採納範圍：主要 LLM application（Claude Desktop、Cursor、Continue.dev、其他主流 IDE / chat 介面）是否原生支援。
• Tool server catalog 規模：社群維護的 MCP server 數量跟覆蓋範圍（檔案系統、git、Slack、雲端 API 等是否都有現成 server）。
• 本地推論生態接入度：Ollama、LM Studio 等本地伺服器是否原生支援 MCP（或仍以 OpenAI 相容 API 為主）。
• 跨平台一致性：Windows / macOS / Linux 上的 MCP server 行為是否一致、SDK 是否穩定。

四個訊號全部成熟前、MCP 仍處於「主要 application 支援、本地生態剛開始接」的擴張期；訊號逐步達標後、預期會像 OpenAI 相容 API 一樣成為應用層的默認標準。

它跟 function calling 的關係：MCP 提供 tool 的暴露機制、模型怎麼呼叫這些 tool 仍走 function calling（如果模型支援）或 structured output（如果用約束）。三者疊加而非互斥。

三者組合的實際工作流

一個完整 LLM application 的典型 stack：

 1使用者 prompt
 2  ↓
 3LLM application（Claude Desktop / Cursor / 自家應用）
 4  ↓ (MCP client、列出所有可用 tool)
 5MCP server pool（檔案系統 server、git server、自家 API server...）
 6  ↑
 7LLM application 把 tool 描述塞進 prompt
 8  ↓
 9推論伺服器（OpenAI API / Ollama / Anthropic API）
10  ↓ (function calling 訓練 + structured output 約束)
11模型輸出：「我要呼叫 tool X、參數是 Y」
12  ↓
13LLM application 用 MCP 把呼叫送到對應 server
14  ↓
15Server 執行、回應
16  ↓
17LLM application 把結果塞進 context、回到推論伺服器繼續

三者各司其職：

• Function calling 讓模型穩定輸出工具呼叫（訓練支撐）。
• Structured output 兜底保證呼叫格式合法（sampling 約束）。
• MCP 提供 tool ecosystem、application 不用為每個 tool 寫專屬 adapter（架構標準）。

少了任一個都還能跑、但效率跟生態擴展性降一級：

• 沒 function calling、靠 prompt + structured output、跨模型品質不穩。判讀訊號：同 prompt 在不同模型上 tool 呼叫格式錯誤率差 30% 以上。
• 沒 structured output、靠模型自律、偶有失敗。判讀訊號：< 30B 模型在複雜 schema 下 JSON 合法率 < 90%。
• 沒 MCP、每個 application 自己寫所有 tool 整合、ecosystem 不可規模化。判讀訊號：團隊維護 > 5 個 tool adapter、每換 LLM provider 重寫一輪。

常見的組合誤用

三者組合在以下情境會失敗、是判讀「我的應用為何不穩」的常見候選：

• Structured output 蓋過 function calling 訓練：模型訓練時用 Anthropic tools 格式、應用強制套 OpenAI function spec 的 grammar、模型輸出「合法但語意空洞」的 JSON（schema 對、欄位填湊數）。修法：用模型訓練過的 spec、避免在 grammar 層強制改寫。
• MCP server 在 prompt context 撐爆 tool 描述：MCP server 暴露幾十個 tool、每個都有 schema 跟 description、全塞進 system prompt 把 context budget 耗光。修法：dynamic tool selection（先讓 LLM 看「tool 摘要」選相關的、再把選中 tool 的詳細 schema 塞進 context）。
• Function calling + structured output 兩邊 schema 不一致：模型訓練的 function spec 跟 application 套的 JSON schema 欄位不對、模型輸出符合訓練 spec 但不符合 application schema、parser 失敗。修法：grammar 直接從 function spec 生、避免人工維護兩份。
• MCP server 沒做 input validation、prompt injection 通過 tool 結果污染 context：tool 回的內容沒檢查、惡意內容（如 PR 留言中的「請執行 rm -rf」）被模型當指令執行。修法：tool 輸出做 sanitization、可疑內容用 sandbox 標籤包起來、模型 prompt 明確區分「使用者指令」vs「tool 結果」。個人 dev 在自己機器上跑 MCP server 的權限模型（檔案系統 / shell / 網路存取邊界、第三方 MCP 信任）見 6.2；IDE 場景中 codebase / 外部文件 / 剪貼簿等 prompt injection 攻擊面見 6.3。

何時可以只用一部分

三者組合的需求視場景而定：

• 單純 structured 輸出（不呼叫工具）：只需 structured output、不需 function calling / MCP。例：把使用者輸入分類成 enum、輸出固定 schema 的 JSON。
• In-process tool（直接 Python function）：function calling + 簡單 dispatcher、不需 MCP。應用規模小時最直接。
• 跨 application 共用 tool：才需要 MCP。如果你只寫自己用的 app、in-process 比 MCP 簡單。
• 用較弱模型：可能只用 structured output、跳過 function calling。

三者的「最小可用組合」視應用複雜度而定。早期應用通常從 function calling 開始、規模化後加 MCP、品質要求高時加 structured output 兜底——演化路徑不必一步到位。

何時過時 / 何時不過時

不會過時的部分：

• 三個層級的分界（模型能力 / sampling 約束 / server 協議）。
• N×M → N+M 的標準化收益、跟 OpenAI 相容 API 的對應。
• 三者疊加而非互斥的設計取捨。
• 「最小可用組合」的判讀框架。

會變的部分：

• MCP 是 2024-2025 才標準化的協議、未來 5 年可能演化或被新協議補充（協議層更新慢、但會更新）。
• 各家 function calling spec 的具體格式（OpenAI / Anthropic / 開放標準會持續細化）。
• Structured output 的具體實作（grammar engines / JSON mode 會持續優化）。
• 哪些工具有 MCP server 可用（生態 catalog 會擴展）。

看到新協議或新 spec 時、回到本章三層 framing 問：它解的是哪一層？能不能跟既有的另兩層組合？這個問題的答案能很快定位新東西在 stack 中的位置。

下一章

下一章：4.7 Workflow 編排模式、把多 LLM call 組合的設計模式整理出來。

本篇紀錄 RAG demo 跟 MCP demo 跑起來的實測資源 footprint、提供本地多模型並存的 baseline、給寫 production 應用前的 sanity check。

驗證日期：2026-05-12 環境：M4 Pro 32 GB、Ollama 0.23.2、Python 3.14 Corpus：本 blog 的 content/llm/、71 個 markdown 檔、463 chunks

各階段資源 footprint

RAG / MCP 工作流通常分三階段、各自吃不同資源：

不同階段的瓶頸不一樣、優化目標也不同。

RAG Ingest 階段：one-shot 但批次密集

跑 python3 scripts/rag-demo/ingest.py 時：

1Found 71 markdown files under content/llm
2  [10/71] 86 chunks in 4.5s
3  [20/71] 181 chunks in 8.6s
4  ...
5  [70/71] 461 chunks in 22.2s
6Wrote 463 records to scripts/rag-demo/index.pkl (22.3s)

實測資源消耗：

Ingest 階段的特性：

• One-shot：corpus 不變不用重跑、index 寫一次永久用。
• 吃 CPU 多於 RAM：產生 embedding 是 forward pass、瓶頸在 GPU 算力、RAM 沒太大壓力。
• 磁碟寫小：每 chunk 約 8 KB（text 部分 ~5 KB + embedding 768 floats × 4 bytes = ~3 KB）、463 chunks 總共 ~3.7 MB。
• 可平行：sequential embed(chunk) 是最慢實作、用 batching API（如果 Ollama 支援）或多 worker、能快 5-10x。

規模 extrapolation：

10K docs 以上就應該考慮：

• Batching embedding（單次 request 送 50 個 chunks）
• 並行 worker（Python multiprocessing、4-8 worker）
• 換 vector database（避免把全部資料用 pickle 塞 RAM）

RAG Query 階段：retrieval 加 generation

跑 python3 scripts/rag-demo/query.py --show-retrieved "問題" 時：

1Loaded 463 chunks from scripts/rag-demo/index.pkl
2=== Retrieved chunks ===
3  0.870  llm/knowledge-cards/transformer.md#chunk2
4  ...
5（LLM 生成 response）

實測資源消耗（單次 query）：

Query 階段的特性：

• 第一次 cold start：要載 chat model 進 RAM、5-10 秒首字延遲。
• 後續 query 都快：embedding model + chat model 都在 RAM、retrieval 毫秒級、只剩 generation 時間。
• RAM 占用 = embedding model + chat model + index：
  • 463 chunks: 274 MB + chat model + 3.7 MB ≈ chat model + 280 MB
  • 100K chunks: 274 MB + chat model + ~800 MB 進 RAM、加上 mmap pickle 額外開銷
• 瓶頸是 chat model：retrieval 部分快、瓶頸完全在 generation。

多模型並存（embedding + chat）：

1# 看當前 RAM 占用
2ollama ps
3# NAME                       SIZE      UNTIL
4# nomic-embed-text:latest    274 MB    4 minutes from now
5# gemma3:4b                  5.5 GB    4 minutes from now

兩個 model 都載入時、Ollama RAM 占用約 6 GB。Ollama 的 OLLAMA_KEEP_ALIVE（預設 5 分鐘）會 idle 後分別 unload 兩個 model。

規模 sanity check：

跑 RAG 比 chat 額外要 ~300-1000 MB（embedding model + index）、不會太重。

MCP Server 階段：subprocess 常駐

跑 python3 scripts/mcp-demo/test_client.py 時、client 會 spawn blog_mcp_server.py 當 child process。

實測：

MCP server 的特性：

• 每個 client spawn 一個 server：Claude Desktop 開 5 個 MCP server、就有 5 個 Python subprocess。
• Index lazy load：本 demo load_index() 第一次 call 才 read pickle、之後 cached。Cold start 第一次 tool call 稍慢。
• Process lifecycle 在 client 端：client 死了、stdin EOF、server 自然結束。Client 沒清乾淨 spawn 多次就 leak process。

1# 看當前所有 MCP server
2ps aux | grep blog_mcp_server | grep -v grep
3
4# 如果 client crash 留下 zombie：
5pkill -f "blog_mcp_server.py"

多 MCP server 並存（如 Claude Desktop 接 git server + filesystem server + custom server）：

200 MB 在 32 GB Mac 上不顯眼、但 16 GB Mac + 多 MCP server + 大 chat model 就可能擠到。

RAG + MCP 整合：完整應用 stack

實際應用會疊起來：

1User 在 Claude Desktop 打字
2  ↓
3Claude Desktop (~200 MB)
4  ↓ MCP stdio
5blog_mcp_server.py (~50 MB)
6  ↓ HTTP /api/embeddings + /v1/chat/completions
7Ollama daemon (~200 MB)
8  ↓ load
9nomic-embed-text 模型 (~274 MB) + 主 chat model (~6 GB)

整體 RAM 占用範圍：

跟 resource-management 章 比、RAG / MCP 加 ~500 MB-1 GB overhead 在 chat 之上、是合理的 tradeoff（換來 retrieval + tool use 能力）。

各資源類型的關鍵指標

整理三 dimension 的關鍵指標跟監控方式：

RAM

1# 看 Ollama 載了哪些 model
2ollama ps
3
4# 看所有 LLM-related process
5ps aux | grep -E "ollama|comfyui|mcp" | grep -v grep | awk '{print $4, $11, $12, $13}' | sort -rn
6
7# 系統整體
8vm_stat | head -3

告警閾值：

• RAM 占用 > 80% 系統總量：開始考慮 unload model 或關掉 ComfyUI
• 看到 swap 增加（vm_stat | grep "Swapouts"）：已經 swap、要立刻減少 model

磁碟

1# Ollama models 累積
2du -sh ~/.ollama/models
3
4# RAG index 累積（多個 corpus）
5du -sh scripts/rag-demo/index*.pkl 2>/dev/null
6
7# ComfyUI checkpoints / VAE / LoRA / etc
8du -sh ~/Projects/ComfyUI/models/*

累積評估：

• Ollama: 每 model 1-20 GB、半年累積容易破 50 GB
• RAG index: 每 100K chunks ~800 MB、多 corpus 累積要管
• ComfyUI: 每 checkpoint 4-7 GB、加 LoRA / VAE / ControlNet 等可達 50+ GB

Process / Port

1# 一鍵 audit 所有 LLM service
2for p in 11434 1234 8080 8188 8000; do
3  echo "=== port $p ==="
4  lsof -i :$p 2>/dev/null | head -2
5done
6
7# 找 zombie subprocess（沒 parent 的 mcp server）
8ps aux | grep "mcp_server" | grep -v grep

告警訊號：

• 同 port 兩個 process listen：明顯有 zombie、要 kill
• 多個 mcp_server PPID = 1（被 reparent 到 init）：原 client 死了沒清乾淨

RAG 應用的長期累積管理

跑超過幾週、會累積：

清理 idiom：

1# 每月跑一次的 cleanup
2llm-rag-cleanup() {
3  echo "[*] Old indexes (>30 days):"
4  find scripts -name 'index*.pkl' -mtime +30 -ls
5  echo "[*] Ollama models (review):"
6  ollama list
7  echo "[*] Python caches:"
8  find ~/Projects -name __pycache__ -type d | head -10
9}

跟 production 的差距預告

本篇紀錄的數字、是「single-user、single-machine、no concurrency」的 baseline。Production 場景多了幾個維度：

Production 視角詳細展開見 4.9 Production 部署的資源評估原理。

何時這篇會過時

不會過時的部分：

• 三階段 footprint 分類（ingest / query / server）
• RAM / 磁碟 / process 三 dimension 的監控指令
• 多模型並存的 RAM 預估方法
• 長期累積管理 idiom

會變的部分：

• 具體 RAM / 磁碟數字（隨模型架構、量化方法演化）
• OLLAMA_KEEP_ALIVE 等具體環境變數名
• 哪些 vector DB 主流（會持續演化）

讀的時候若 RAM 占用跟本篇對不上、可能是新 model 架構效率改變、用同樣方法量自己環境的 baseline 即可。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、實作配對見 RAG demo 跟 MCP demo、Ollama / ComfyUI 共用的 lifecycle 管理見 Resource management、Apple Silicon 統一記憶體預算原理見 0.5 記憶體預算。

跑這篇實測的指令總結

 1# 1. RAG ingest 階段 RAM 量
 2ollama ps  # 先看 baseline
 3python3 scripts/rag-demo/ingest.py &
 4INGEST_PID=$!
 5ollama ps  # 看 embedding model 載入後
 6vm_stat | head -3
 7wait $INGEST_PID
 8
 9# 2. RAG query 階段 RAM 量
10ollama ps  # 看 idle 後 unload
11python3 scripts/rag-demo/query.py --show-retrieved "test query"
12ollama ps  # 看 chat model 載入
13
14# 3. MCP server 階段 process / RAM
15python3 scripts/mcp-demo/test_client.py &
16CLIENT_PID=$!
17sleep 2
18ps aux | grep blog_mcp_server | grep -v grep
19wait $CLIENT_PID
20
21# 4. 完成釋放
22ollama list | tail -n +2 | awk '{print $1}' | xargs -I {} \
23  curl -s http://localhost:11434/api/generate -d "{\"model\":\"{}\",\"keep_alive\":0}"

codebase-memory-mcp（下稱 cbm）的核心定位是「把整個 codebase 預先解析成可被 LLM 廉價查詢的知識圖譜」。它要替代的是 agent 在不熟悉的 codebase 上「拿 grep / glob / read 連環翻檔」的探索 pattern——人類用 IDE 編輯、agent 用 cbm 探索、兩者服務不同的工作流。

設計上跟其他「graph + LLM」工具的關鍵分野，在於它不內嵌任何 LLM 做自然語言 → 查詢轉換：

Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you’re already talking to is the query translator.

所以 cbm 自己只是個提供高品質 graph 查詢 API 的 server，「翻譯自然語言」這件事直接讓呼叫端的 agent 做。這個取捨對 Claude Code 這類 host 是理想的，因為 host 端已經有一顆夠強的模型在跑。

部署形態決定它的甜蜜點

cbm 是單一靜態 binary，所有依賴（155 種 tree-sitter grammar、SQLite、tokenizer）都在 binary 內，安裝後沒有外部 runtime 依賴。

這個取捨直接影響它的甜蜜點：

• 跨平台分發成本低，CI 上跑也方便
• 不需要為個別語言裝 toolchain（不像 LSP 路線要對應 language server）
• 但代價是「能力上限」被 binary 內附的 grammar 跟自寫的 type resolution 算法綁住，無法靠 IDE 生態的成熟度借力

知道這個取捨之後，後面所有能力差異都解釋得通：能做的事多半是「靜態可推導」的，需要 query 外部 toolchain（如 IDE language server）的場景多半要靠別的工具補。

索引架構：多 pass + RAM-first

cbm 的索引流程是 RAM-first 的多 pass pipeline，pass 之間有明確的責任分工：

執行期用 LZ4 壓縮的記憶體 SQLite 加速，所有 pass 跑完一次性 dump 成持久化 DB（路徑 ~/.cache/codebase-memory-mcp/，WAL mode）。team 共享情境下可加跑 zstd 壓縮（best tier 用 zstd -9 + index strip、fast tier 用 zstd -3 走 watcher 增量），匯出成 .codebase-memory/graph.db.zst artifact 給 CI / 隊友共用。

Pass 排序遵循明確的依賴關係：calls 一定在 definitions 之後（因為 call edge 要連到已被建出來的 function / method node）、HTTP links 一定在 calls 之後（需要先有 call edge 才能比對 route 跟 handler）、configuration / tests 是 cross-cutting 的最終層（前面的結構與 call graph 都齊備、它們才能掛上 CONFIGURES / TESTS edge）。實務影響：HTTP links pass 在「單 service repo」上等於 no-op、configuration pass 在「缺 IaC manifest」的 repo 上也是 no-op、這兩個 pass 的價值高度依賴 repo 結構。

這個架構的副作用是：單次完整 index 速度快（README 聲稱 Linux kernel 3 分鐘），但增量更新採背景 git polling（IDE-style file watcher 是即時觸發、cbm 是定期掃描），對「邊改邊查」的工作流會有秒級延遲。

11-signal 語意搜尋：cbm 最強的差異化

如果只看 README 寫的「BM25 全文搜尋」，會嚴重低估 cbm 的搜尋能力。實際上 search_graph 的 ranking 是 11 個 signal 的加權組合：

表格列了 9 個明確 signal、README 另說有 11 個（剩 2 個是 implementation detail 沒公開細節）。實務上 11-signal 的價值在於幾個高權重 signal 各自負責不同 query 類型——權重分配有明顯的高低差：

• RRI 是 cbm 對「重要符號優先」的 graph 結構 prior。一個被大量檔案 import 的核心 class、即使在 query 字串裡只有間接匹配、RRI 也會把它往上推。這層對「找這個 codebase 的入口 / 主要抽象」類 query 特別重要。
• Data flow 是 cbm 對「概念上接近、但符號名沒共字」的 query 的關鍵 signal。例如查「金額顯示」、formatAmount 跟 _buildPriceDisplay 在符號名上沒共字、但 data flow 能捕捉「formatAmount 的回傳值流入了 _buildPriceDisplay 的 widget」這層連結。
• Graph diffusion 是 cbm 對「擴散式相關性」的最終 boost——已經被前面 signal 推到高分的符號，會把分數擴散到 graph 上鄰近的符號。實務影響：monorepo 上效果最強（跨 module 鄰近性有意義）、單一檔案的小專案上幾乎沒效果。

加上一層 cbm_camel_split tokenizer：對 getMoneyField 這類 identifier 做 camelCase / snake_case 切詞，所以查 money field display 能命中 getMoneyField、MoneyFieldRenderer 之類符號。

這套組合的判讀價值在於：對「我不知道精確符號名」的概念性查詢，cbm 是少數能給出合理 top-N 的工具。例如查「金額顯示相關」、結果裡會出現 formatAmount 實作 + _buildPriceDisplay + getBalanceDisplay，這些都跟「金額顯示」業務概念相關、不會被 displayName / displayTags 這種只共享 display 子字串的雜訊淹沒。

下一步路由：要看實測案例，見 三 MCP 工作流與 Dart 實測。

Hybrid type resolution：只給五個語言的特殊待遇

cbm 對 Go / C / C++ / TypeScript / JavaScript（JS 含 JSX、TS 含 TSX）額外跑一層 type resolution，README 描述是：

Clean-room reimplementation of tsserver / typescript-go’s type resolution algorithms — parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files.

換言之，這幾個語言的 CALLS edge 在 syntactic match 之上多了一層 type-aware dispatch resolution，效果接近 LSP。其他 149 個語言只跑純 tree-sitter pass，能力會降到「結構抽得到、call edge 抽得很有限」。

實測對照（在某 Dart 商業專案上）：

1cbm 索引完成統計：3,038 nodes、6,355 edges
2其中 CALLS edge 總數：2（整個專案僅 2 條）

這個數字反映 cbm 的設計選擇——hybrid resolution 名單只涵蓋 5 個語言、Dart 在名單外——所以 trace_call_path 對 Dart symbol 一律回 0 caller，這個 0 屬於 by design 行為。對 Go / TS 主力專案，這個能力上限會完全不一樣。

判讀訊號：開發前先確認自己的主力語言在不在那五個語言內。在的話 cbm 是準 LSP；不在的話它只是個「結構 + 全文搜尋」工具，呼叫鏈相關問題要靠別的 MCP 補。

跨 service 鏈接：first-class HTTP_CALLS edge

cbm 的另一個差異化能力是把 REST / gRPC / GraphQL / tRPC route 當 first-class node，建立跨 service 的 HTTP_CALLS edge：

• Route 偵測：對應主流 web framework（Express / NestJS / FastAPI / Gin / Rails 等）的 route 定義語法
• Call site 比對：以 route pattern 比對 client 端的 URL 字面值或變數，附 confidence score
• 額外的 channel edge：Socket.IO / EventEmitter / 各種 pub-sub 的 EMITS / LISTENS_ON

這層能力對單一 monorepo 內的多 service 架構（microservice repo / BFF / API gateway pattern）特別有價值——可以查「這個前端 API call 對應哪個後端 handler」這種跨 service 問題。對單一 service 的單體 repo，這層能力派不上用場。

實際使用前提：要 index 的 repo 必須同時包含 client 跟 server 端，分散在多 repo 的話 cbm 不會自動跨 repo 連邊。

Cypher 子集：支援的查詢與邊界

cbm 提供的 query_graph 是 Cypher 的真子集——覆蓋大部分 read-only query 語法、省略 mutation 與部分 aggregation 語法：

支援：

• MATCH 含 label / relationship type / 變長路徑
• WHERE 含比較 / regex / CONTAINS
• RETURN 含 property access、COUNT、DISTINCT
• ORDER BY、LIMIT

不支援：

• WITH（不能多階段 pipeline）
• COLLECT（不能 aggregate 成 list）
• OPTIONAL MATCH（不能 left-join）
• labels(n) / type(r) 等函數呼叫
• AS 別名
• 任何 mutation（純讀）

幾個限制各自踩到的事故型態：

• WITH 缺席：所有需要「先 match 一組、再 filter / aggregate」的二階段 query 都寫不出來。例如「列出每個 module 內最常被呼叫的 function」這種 Top-K per group 的 query、在 Cypher 是 MATCH ... WITH module, COUNT(*) AS c ORDER BY c LIMIT 1、在 cbm 要拆成「先 list modules、再對每個 module 跑一次 callers query、外層排序」。
• OPTIONAL MATCH 缺席：left-join 場景做不到。例如「列出所有 class、附上它的 supertype（若有）」這種「主結果不該因為某個關係缺失就丟掉」的 query 寫不出來。cbm 上的做法是先抓全部 class、再對每個 class 跑一次 supertype query、在 client 端合併。
• labels(n) 缺席：拿不到 graph 內所有 node label 種類的清單。想做「我的 graph 裡有哪幾類 node」這種 schema 探索類 query、得退回 get_graph_schema 拿固定的 schema 介紹、看不到 instance 層真實分布。
• AS 別名缺席：query 結果直接是 node / relationship object、沒法 rename 欄位給 downstream consumer。

這些限制的共通實際影響：想做 group-by-count 類的 graph stats 查詢得退回 search_graph 逐 label 抽。例如「列出每個 file 有幾個 method」這種一行 Cypher 在標準 Neo4j 能寫的、在 cbm 上要拆成多次 query 在外層彙整。

判讀訊號：若 query 需要 WITH ... COLLECT(...) AS xs 這類二階段語法，先別硬寫 Cypher，改用 search_graph 加 client 端聚合。

安裝行為與兩個要注意的小坑

cbm 的 install.sh 對 ~/.claude/settings.json 動的範圍比 README 寫得多。實際安裝會：

• 下載對應平台 binary、剝 macOS quarantine、ad-hoc sign
• 自動偵測 11 種 coding agent，逐一注入 MCP server config
• 對 Claude Code 寫入 .claude/.mcp.json、4 個 Skill、PreToolUse hook
• Hook 名稱：cbm-code-discovery-gate，攔截 Grep / Glob 注入結構化 context

兩個實際踩過的小坑：

Hook matcher 與 README 不一致。README 描述「intercepts Grep/Glob — never Read」，實際安裝版本 matcher 是 "Grep|Glob|Read|Search"，連 Read 也被擋。修法：手動把 matcher 改成 "Grep|Glob|Search"。注意 codebase-memory-mcp update 可能會把這行改回原樣，每次升級要重新確認。

uninstall 不清 hook。卸載 binary 不會主動把 ~/.claude/settings.json 裡的 hook 條目移除。決定不再用 cbm 時要手動清掉 PreToolUse 下的 cbm-code-discovery-gate 條目，否則之後安裝其他工具或除錯時會看到神祕的 BLOCKED 訊息。

14 個 MCP tool 的分類

特別值得提的兩個：

• manage_adr：把 Architecture Decision Records 當持久化資源管理。對長期專案有累積架構決策需求的場景有用，但若團隊已用 ADR-tools 或 Notion 管 ADR，這層會重複。
• ingest_traces：餵 runtime trace 進來驗證 HTTP_CALLS edge 是否反映實際的 runtime 調用。可以把靜態推測的 cross-service edge 與真實 runtime 行為對齊。實務上要先有 distributed tracing 基礎建設才開得了，門檻偏高。

適用 / 不適用情境的判讀

適用情境：

• 主力語言在 Go / C / C++ / TS / JS 名單內 → 享受 hybrid type resolution。判讀方法：對 5 個熱門 class 跑 trace_call_path、若 caller 數跟 IDE「Find Usages」結果對得上、表示 hybrid 正常工作。
• 概念性 / 自然語言搜尋需求高 → 11-signal scoring 是少數能勝任的 MCP。判讀方法：對「我只記得功能類別、不記得名字」的 query 跑 cbm 跟其他工具的 search、若 cbm top-10 命中率明顯高、值得當主要入口。
• 跨 service 的 monorepo → first-class HTTP_CALLS edge 抽得到 cross-service 鏈。判讀方法：repo 內若有多個 service 用 HTTP / gRPC / GraphQL 互相呼叫、又分散在同一個 git tree 內、cbm 能跨 service 連邊；若只是單 service repo 這條沒效。
• 偏好單 binary 部署 → 不想為個別語言裝 toolchain、cbm 是少數零外部依賴的選項。

不適用情境：

• 主力語言不在 hybrid resolution 名單（如 Dart / Swift / Kotlin）且核心需求是 caller / blast radius 追蹤。判讀方法：在自己 repo 跑 cbm trace_call_path 對 5 個熱門 class、若 caller 數明顯偏低或 0、表示 cbm 在這語言只剩結構抽取、要靠 LSP 工具補。
• 要 symbol-level 編輯（rename / replace_symbol_body）— cbm 純讀、沒這層。判讀方法：要做「rename method 並更新所有 reference」這類 atomic refactor 時、cbm 完全幫不上忙、要走 LSP 工具。
• 要編譯 diagnostic 整合 — cbm 不接 LSP、沒法把 type error / unused import 拋給 agent。

搭配建議：在不在 hybrid resolution 名單的語言上，cbm 通常需要配合一個 LSP-based MCP（如 serena）做 caller / impact 補位，加上一個 tree-sitter call graph 工具（如 codegraph）做日常結構查詢。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

cbm 的核心價值在三件事：單 binary 部署、11-signal 語意搜尋、跨 service HTTP/RPC 鏈接。前兩件對任何語言都成立，第三件對微服務 monorepo 特別有意義。

它的能力上限被 hybrid type resolution 的語言名單卡死——名單內等於準 LSP，名單外只是個結構抽取器。評估時第一個要問的問題是：「我的主力語言在不在那五個（Go / C / C++ / TS / JS）？」答案決定 cbm 是主刀還是輔刀。

codegraph 的設計動機很具體：Claude Code 探索 codebase 時 spawn 的 Explore agent 會用 grep / glob / read 連續刷檔，每個 tool call 都吃 token。codegraph 把這層探索預先做好，agent 直接查預建好的 graph。

When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call. CodeGraph gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure.

跟 cbm 比，codegraph 的 scope 更窄、更專注：不做跨 service 鏈接、不做 ADR / runtime trace 管理、不做 11-signal 語意搜尋，只把 call graph 跟 symbol relationship 做好。這個取捨讓它的 MCP tool 只有 10 個、每個責任都很單一。

技術架構：tree-sitter + per-language query + FTS5

codegraph 的核心 pipeline：

1tree-sitter parse → per-language query 抽 nodes/edges
2                  → 解析 reference（import / extends / implements / calls）
3                  → 寫進 SQLite + FTS5

關鍵設計：對每個語言寫專屬的 tree-sitter query——比起通用 AST visitor 路線、這個設計能對特定語言的 dispatch pattern 抽到更精確的 node 跟 edge。

Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).

這個設計選擇直接決定了 codegraph 對非主流語言（如 Dart / Svelte / Liquid）的支援深度——因為每個語言都有專屬 query，所以 19+ 語言裡的 Dart 真的有 working call graph，不像純 tree-sitter wrapper 那樣只能抽結構。

實際支援的 19+ 語言：

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Lua、Luau、Pascal/Delphi。

過濾規則：「Files larger than 1 MB are skipped」（generated bundle / minified JS / vendored blob 自動忽略）。

Auto-sync：native OS file watcher + 2s debounce

codegraph 預設啟用 file watcher、用 native OS 事件（macOS FSEvents / Linux inotify / Windows ReadDirectoryChanges）：

• Debounce window：2 秒（避免快速連續存檔重複觸發）
• 過濾範圍：只看 source 檔案（按副檔名）
• 行為描述：「Incremental sync. The graph stays current as you code — no configuration needed」

這層比 cbm 的「背景 git polling」更貼近 IDE — 改完檔案 2 秒內 graph 就同步好，「邊改邊問」工作流更順。

判讀訊號：剛存完檔立刻問 caller 還是漏，等 3 秒再試一次；持續漏的話跑 codegraph status 看 indexed 數字對不對得上預期。

Call graph 抽取的能力與聲稱

codegraph 對 caller / callee / impact / trace 這四個查詢的覆蓋是它的主賣點。README 對 codegraph_trace 的聲稱是：

Follow dynamic-dispatch hops (callbacks, React re-render, interface→impl) that grep can’t.

實際機制 README 沒詳細寫，從 source 推測是「對某些常見動態 dispatch pattern 寫了專屬 query」——比如 React component 的 JSX → component definition 解析、interface method → implementation 對應這類。

這個 claim 在實測上有但有限——對 type-inferred receiver 仍會漏。例如 Dart 上（Money 在該專案是 extension type）：

1final Money samplePrice = ...;
2samplePrice.multiplyByRate(rate);   // ← codegraph 抽不到這條 edge

samplePrice 是 local variable，要做型別推斷才知道 receiver 是 Money。tree-sitter 看到的只是 <identifier>.multiplyByRate(...)、不知道 samplePrice 的型別、無法 dispatch 到 Money.multiplyByRate。

判讀訊號：對「靠型別解析才能找到的 callsite」會漏。如果專案大量使用 generics、type aliasing、factory pattern 隱藏型別、duck typing，codegraph 的 caller 數字會系統性偏低。重要 refactor 別只看它的數字決策。

下一步路由：實測對照數字見 三 MCP 工作流與 Dart 實測。

Caller 跟 callsite 的計數單位差異

codegraph 的 codegraph_callers 採用的計數單位是「caller symbol 數」（同一個 method 內呼叫目標兩次仍然只算 1 個 caller）——跟「callsite 數」屬於兩種不同的統計方式。

這個設計的影響：跟 LSP-based 工具（如 serena）對比時，數字會看起來「少」，但這是計數規則的差異、跟精度差距屬於兩個不同議題。寫實測 baseline 時要把這個單位寫死，避免「codegraph 回 3、serena 回 9」被誤判成「codegraph 漏 6 個」。

實際上這 3 vs 9 的差距要分兩段看：codegraph 抓到的 3 個 caller symbol 對應 6 個 callsite（同一個 method 內有多處呼叫、被計數規則合併成 1 caller）、剩下的 3 個 callsite 在第 4 個檔案（product.dart）、是真的漏（type-inferred dispatch）。算術：6 callsite（codegraph 算 3 caller）+ 3 callsite（真的漏）= serena 的 9。要拆開看才知道哪部分是計數差異、哪部分是能力差距。

14 web framework 的 route 識別

codegraph 內建對 web framework 的 route 識別：

Django、Flask、FastAPI、Express、NestJS、Laravel、Drupal、Rails、Spring、Gin / chi / gorilla / mux、Axum / actix / Rocket、ASP.NET、Vapor、React Router、SvelteKit。

README 標稱「14 個」、實際展開後是 15 條（Gin / chi / gorilla / mux 跟 Axum / actix / Rocket 各算一組路由生態）。這個小落差源自分組計數方式、不影響功能。

這層的角色是讓 codegraph_search 能用 URL pattern 找到對應 handler，不必去猜 handler 函式名。但跟 cbm 的 first-class HTTP_CALLS edge 不一樣，codegraph 沒做「client URL 字面值 → server route 比對」，所以單一 service 內找 handler 可以、跨 service 鏈接做不到。

判讀訊號：純前端 / 純後端 repo 上這層夠用；要跨 service 追 cross-service call 仍要靠 cbm 或別的工具。

10 個 MCP tool 的責任分工

設計上有四個值得單獨展開的 tool：

codegraph_explore 是為了省 tool call — 不用對 N 個 symbol 各呼叫一次 codegraph_node、一次拿到所有 source。這直接呼應 codegraph 整體「省 token / 省 tool call」的設計目標。

codegraph_trace 單一 call 涵蓋整個路徑、每一跳的 function body 直接 inline 在結果裡。對「X 怎麼影響到 Y」這種多跳問題，傳統做法要 N 次 codegraph_callers + N 次 codegraph_node，trace 把這壓成 1 次。代價是若兩個 symbol 之間沒有 static-resolvable 路徑（如 type-inferred dispatch 中斷），會直接回「No direct path」、不會主動找替代解釋。

codegraph_context 跟 codegraph_explore 的責任差別常被搞混。codegraph_explore 是「我已經知道要看哪幾個 symbol」、一次拿原始碼；codegraph_context 是「我有個 task description、不知道相關 symbol 是哪些」、由它從 task 內容拉出可能相關的 graph 鄰域。前者是「精確檢索」、後者是「概念性彙整」。實務上 task agent 開新任務時用 codegraph_context、debug 細節時用 codegraph_explore。

codegraph_impact 是 blast radius 工具、但它的精度被 tree-sitter syntactic 限制卡住——跟 caller / callee 同源、type-inferred dispatch 的影響範圍會漏。實務影響：對「rename method 會影響什麼」這類重要 refactor 不能單看它的數字、要走 LSP 工具 cross-check。判讀訊號：codegraph_impact X 回的 affected symbol 數明顯少於預期、且 X 是被廣泛使用的 type / method 時、blast radius 多半有漏、要補 LSP 驗證。

Token efficiency benchmark：方法論與限制

README 聲稱「~35% cheaper · ~70% fewer tool calls · 100% local」、median 跨 7 codebase：

• Cost: 35% reduction
• Tokens: 57% fewer
• Time: 46% faster
• Tool calls: 71% fewer

方法論：

Claude Opus 4.7 run headlessly. WITH = CodeGraph’s MCP server enabled, WITHOUT = empty MCP config. Same question per repo, 4 runs per arm, median reported.

7 個 benchmark codebase：

幾個要注意的解讀偏差：

Benchmark 集中在 codegraph 強項語言。VS Code / Django / Tokio 都是 codegraph 的核心支援語言、且 LSP 生態成熟。Dart / Svelte / Liquid 這類 long-tail 語言沒列在 benchmark 內，token 節省效果在那些語言上是否成立不知道。

Empty MCP config 的對照組不一定貼近實務。沒裝任何 MCP 時 agent 的 baseline 探索行為跟「裝了其他 MCP」不同。實務 stack 通常多個 MCP 並用，這個 35% 對「加裝 codegraph 進已有 MCP stack」的邊際效益會打折。

判讀訊號：benchmark 數字當「值得試」的參考、不當「裝了就省 35%」的硬保證。實際省多少要在自己的 stack 上跑同樣 question set 才知。

安裝行為

1npm i -g @colbymchenry/codegraph
2codegraph install --target claude --location global -y
3cd your-project && codegraph init -i

codegraph install 會把 MCP server 條目寫進 ~/.claude.json 的 mcpServers、codegraph init -i 在當前 repo 建 .codegraph/codegraph.db、啟動 watcher。

跟 cbm 不一樣：codegraph 不寫 PreToolUse hook、不攔截 Grep/Glob。它純粹當 MCP server 提供 tool、決策權留給 agent，對既有工作流的干擾較小。

CLI mode 是另一個方便點：所有 MCP tool 在 CLI 都有對應指令（codegraph callers X / codegraph trace X Y），不必等 Claude Code 重啟載入 MCP 就能先在 terminal 驗證效果。

適用 / 不適用情境的判讀

適用情境：

• 主力語言在 19+ 支援列表內，且需要可靠的 caller / impact / trace 查詢
• 「邊改邊問」工作流（auto-sync 2s debounce 比較貼近 IDE）
• 希望 MCP 保持原生 grep / glob 行為、把決策權留給 agent 自主判斷（避開 hook 層強制介入）
• 要 CLI 跟 MCP 雙管道使用（CLI 可先試、MCP 給 agent 用）

不適用情境：

• 語言不在支援列表（codegraph 不像 cbm 一次 vendor 155 個 grammar）
• 需要跨 service 的 client URL → server route 鏈接（codegraph 只認 route definition）
• 需要 symbol-level atomic edit（codegraph 純讀、沒 rename / replace_symbol_body）
• 重要 refactor 要保證不漏 callsite（tree-sitter syntactic 上限會漏 type-inferred dispatch）

搭配建議：對 type-inferred dispatch 漏的部分，可以靠 LSP-based 工具（如 serena）補位。對概念性自然語言搜尋，cbm 的 11-signal scoring 比 codegraph 的 symbol pattern match 更強。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

codegraph 的核心價值是用 per-language tree-sitter query 把 call graph 做成 19+ 語言通用的 MCP 服務，加上 auto-sync 跟 CLI 雙管道。它的 scope 聚焦在 call graph、比 cbm 窄很多、但聚焦範圍內品質很高。

它的型別解析靠 tree-sitter syntactic：receiver 是顯式型別宣告或 literal 的 callsite 解得好、receiver 要靠型別推斷的 callsite 會漏。判斷 codegraph 在自己專案上的可信度，先估專案有多少比例的 call 是 type-inferred receiver——比例高就要配 LSP 工具補位、比例低就放心用。

serena 的核心定位是「把現成 LSP 生態包成適合 agent 用的高階抽象」。它不自建 type system、不自寫 parser，直接 spawn 各語言對應的 language server（Dart 用 dart analysis_server、TS 用 tsserver、Rust 用 rust-analyzer 等），把 LSP 的能力轉成 MCP tool。

設計哲學是 README 自己歸納的「agent-first tool design」：

Involves robust high-level abstractions, distinguishing it from approaches that rely on low-level concepts like line numbers or primitive search patterns.

換言之，serena 的所有編輯都是 symbol-level——讓 agent 直接用 symbol 語意操作（「把 X function 的 body 整個換掉」、「在 Y class 後面插一段」、「rename Z」），跳過 line number 跟 text patch 這層 raw text 處理。對應的是 LSP 路線本來就有的 symbol 結構與 reference 追蹤。

跟 tree-sitter 路線的本質分野：tree-sitter 只給結構、不給型別；LSP 給的是「IDE 等級的真型別系統」。代價是 LSP 要每個語言裝對應 language server、執行期 spawn process、per-session 維護狀態。

部署形態：兩個 backend、執行期 spawn LSP

serena 提供兩個 backend：

Language Server backend 是 OSS 用戶會接觸的路線。serena 透過 LSP 抽象涵蓋 40+ 語言、實際能力依各語言 LSP 成熟度而定——Python / TypeScript / Go / Rust / Java / C# / Dart 等主流語言由 serena 內建 bootstrap 自動下載 server、冷門語言（如 Liquid / Pascal）需要使用者自己準備 server binary、無 server 的語言視同 fallback 到純文字工具。判讀訊號：跑 activate_project 後若 serena 沒在背景 spawn 對應 LSP、表示該語言走 fallback 路線、find_referencing_symbols 等型別敏感 tool 不可用。

對 Dart 而言：serena 啟動時 spawn dart analysis_server、跟 Flutter SDK 內附的同一隻。所以 serena 對 Dart 的能力等同 dart analysis_server 暴露的能力——比 tree-sitter 路線高一個量級。

Per-session 模型與 activate_project

serena 的 LSP backend 是 per-session 的：

• 沒有持久化 graph DB（不像 cbm / codegraph 把結果寫進 SQLite）
• 每個 session 啟動時要 activate_project、spawn 對應 language server、warm up index
• Session 結束 server 也跟著 terminate，下次重來

activate_project 的角色是告訴 serena「這個 session 接下來要分析哪個 project root」，serena 才知道要 spawn 哪幾個 language server、index 哪個 workspace。一個 session 內可以切多次 project，但同時只 active 一個。

這個模型的取捨很清楚：

• 好處：永遠拿到當下最新狀態（不會有 stale index 問題）、不必管 watcher / debounce
• 代價：每次 session warm-up 有秒級至分鐘級延遲（大專案 LSP indexing 慢）、跨 session 不能重用結果

判讀訊號：第一次查詢回得慢、之後快——這是 LSP indexing warm-up。若每次查都慢、檢查 LSP 是否因記憶體不足重啟。

Symbol-level atomic edit 的價值

serena 的 editing tool 都是 symbol-level：

• replace_symbol_body：取代某個 function / method / class 的 body
• insert_after_symbol / insert_before_symbol：在指定 symbol 前後插入內容
• safe_delete_symbol：刪除 symbol 並檢查 reference
• rename_symbol：rename symbol、自動更新所有 reference（LS backend 限 symbol 範圍、JetBrains backend 額外支援 file / directory 層級重命名）

對比 Edit tool 用「old_string / new_string」做 text-level patch：

實務上的價值：type-sensitive refactor 的事故率大幅降低。改 method 不會手抖把 indentation 改錯、rename 不會漏改 reference。代價是 symbol 路徑必須寫成包含父層的完整形式（ClassName/methodName）。

判讀訊號：寫 replace_symbol_body 後若 LSP 報 syntax error、先 get_diagnostics_for_file 看具體錯在哪、別直接 retry 同個 patch。

find_referencing_symbols：LSP 路線的型別精確 caller 來源

對 Dart / Swift / Kotlin 這類 tree-sitter 工具支援薄弱的語言，find_referencing_symbols 是少數能拿到「型別精確的 caller 清單」的 MCP tool。

實測對 Dart Money.multiplyByRate（某商業專案、Money 是 extension type）：

1serena find_referencing_symbols → 4 個檔案、9 個 callsite
2codegraph callers              → 3 個 caller symbol（漏 3 個 callsite）
3cbm trace_call_path            → 0 callers（Dart 不在 hybrid resolution 名單）

差距來源就是型別解析：samplePrice.multiplyByRate(...) 這種 receiver 是 local variable 的 callsite，要知道 samplePrice 的型別是 Money 才能 dispatch 到正確 method。LSP 走 dart analysis_server 拿到完整型別資訊，所以這層 dispatch 是精確的。

下一步路由：對照數字與 5 個實測實驗見 三 MCP 工作流與 Dart 實測。

30+ MCP tool 的分類

serena 的 tool 數量比 cbm / codegraph 都多、覆蓋更廣的工作流：

幾個值得單獨展開的類別：

檢索類是 serena 跟 LSP 黏最緊的入口——find_symbol / find_declaration / find_implementations 走 LSP 的 textDocument 命令、find_referencing_symbols 是 LSP references 的 wrapper。這層是 serena 不可替代的核心、所有需要型別精確的查詢都從這走。

get_diagnostics_for_file 是把 LSP 的編譯診斷直接暴露給 agent。改完 code 不必跑 build 就能知道有沒有 type error / unused import / missing await。對 type-sensitive refactor 是必備。

Symbol-level edit vs text-level edit 的選用：symbol-level（replace_symbol_body / insert_after_symbol / safe_delete_symbol / rename_symbol）對「有明確 symbol 邊界的修改」最穩、不會踩到 indentation 或 escape 問題；text-level（replace_content / search_for_pattern）保留給「跨 symbol 邊界、或非 code 內容」的場合（如改 markdown、config、log 字串）。判讀訊號：要動的內容能不能用「ClassName/methodName」這種 symbol path 定位？能就走 symbol-level、不能就 text-level。

execute_shell_command 是 LSP-only 工具裡的「逃生門」——LSP 本身不執行命令、但實務上 agent 需要跑 test / build / git status / 任意 CLI 工具來驗證自己的修改。這條等於把 LSP-based 工具補成「能 query 又能執行」的完整 workflow 工具。安全考量：因為它能跑任意 shell command、Claude Code 對 serena 的 trust level 要跟 Bash tool 對齊看待、不要假設它「只是讀取工具」。

Memory system 採用「跨 session 的 markdown 筆記檔」形式、屬於自由格式存儲。用途接近 agent 的本地長期記憶——存「這個專案的 setup 注意事項」、「上次 refactor 的決策紀錄」、「常用的 codebase pattern」。跟 cbm 的 manage_adr（結構化 ADR）走相反取向：serena 把 schema 留給使用者自定、manage_adr 給定 ADR 欄位結構。

Project 類（activate_project / get_current_config / onboarding / initial_instructions）是 serena 對「agent 第一次接觸新專案要先讀什麼」的明確協議。onboarding 讓 agent 主動 read 專案 onboarding doc、initial_instructions 給 agent 一份 serena 自己的使用手冊、activate_project 切 project root、get_current_config 暴露當前 session 的配置給 agent debug。這層降低盲目探索成本、是把 serena 從「LSP wrapper」抬升到「agent-first」的關鍵。

Per-session 與持久化 graph 的搭配問題

serena 的 per-session 模型在「單純查 caller / refactor」工作流很合適，但對「自然語言搜尋 / 跨 session 累積 graph context」就不夠。

實際差距：

• 想用「金額顯示相關」這種概念性 query 找 symbol → serena 沒有 BM25 / 11-signal scoring、只有 search_for_pattern（regex / literal）跟 find_symbol（exact name match）
• 想跨 session 累積「這個 codebase 有哪些 module」的整體 inventory → serena 每次重 index、沒有持久化的 graph 可查
• 想做跨 service HTTP_CALLS 鏈接 → serena 沒有這層

判讀訊號：搜尋需求若是「我知道某個 symbol 的精確名稱、要找它的 references」就用 serena；若是「我不知道精確名稱、用概念找」要配合 cbm。

安裝行為

serena 在 Claude Code 是 plugin 形式：在 plugin marketplace enable 即可，不需要單獨 npm i。Plugin 啟動時 serena 會 spawn LSP，第一次 activate 某個 project 時 indexing 完成才能跑 query。

跟 cbm / codegraph 的差異：

• 不寫 PreToolUse hook、不攔截既有 grep / glob 行為
• 不在 ~/.claude.json 直接加 mcpServers（plugin 機制管理）
• 每個 project 要顯式 activate——第一次 session 進新 project 時 agent 要主動跑 activate_project 或在 plugin config 預設 project root

要注意的點：

Language server 缺失時的失敗模式。對冷門語言（如 Liquid / Pascal）若環境沒裝 language server、activate_project 會回失敗但不會主動裝。需要使用者自己準備 server binary。Dart / TS / Python / Go / Rust 等主流語言 serena 會 bootstrap 處理。

JetBrains backend 是付費。OSS 用戶只能用 LS backend、得不到 debug 整合那組能力。

適用 / 不適用情境的判讀

適用情境：

• 主力語言有成熟 LSP（Dart / TS / Python / Go / Rust / Java / C# 等）
• 型別敏感的 refactor 場景（rename / extract method / 跨檔 reference 更新）
• 要編譯 diagnostic 即時反饋（取代 build / test cycle 的部分功能）
• Symbol-level atomic edit 的可靠性比 graph 持久化重要

不適用情境：

• 主力語言 LSP 不成熟或不存在（serena 沒得借力）
• 需要概念性 / 自然語言搜尋（用 cbm 的 11-signal scoring）
• 需要跨 session 累積的 graph context（serena per-session、不持久化）
• 需要跨 service HTTP/RPC 鏈接（serena 沒這層）

搭配建議：serena 是「型別精確 + 編輯出口」的角色。在它擅長的語言上做 caller 追蹤 / refactor、把概念性搜尋讓給 cbm、把日常結構查詢讓給 codegraph。三者怎麼分工見 三 MCP 工作流與 Dart 實測。

結論

serena 的核心價值在三件事：直接借 LSP 拿型別精確的 reference、symbol-level atomic edit 的可靠性、編譯 diagnostic 即時整合。前兩件對任何成熟 LSP 語言都成立，第三件對「改完 code 想立刻驗 type error」的工作流特別重要。

它的能力上限取決於「目標語言 LSP 成熟度」——LSP 強的語言上 serena 是強工具、LSP 弱的語言上 serena 也跟著弱。它的能力下限取決於「持久化 graph 與自然語言搜尋」這兩層空白——這兩層要靠別的 MCP 補齊。

評估 code intelligence MCP 不能只看 README benchmark：每個工具的 benchmark 都選自己擅長的 codebase 跟語言，readme 數字只能參考、不能直接套到自家 stack。

這次選一個 Dart 商業專案做對照場域有兩個理由：

• Dart 是三個工具的「中間地帶」——cbm 不在 hybrid resolution 名單、codegraph 列為 full support、serena 借 dart analysis_server 有完整 LSP。三條技術路線在同一語言上的能力差距會被最大化。
• Dart 大量用 extension type、generic、factory pattern，這些是 type-inferred dispatch 的高發場景，能逼出每個工具的真實精度差。

在 Go / TypeScript 上跑同樣對照，結論會反過來——cbm 的 hybrid resolution 在那裡會接近 LSP 精度，三刀流的必要性會降低。所以這篇結論限定「LSP 成熟但 cbm 不在 hybrid resolution 名單」的語言。

本質差異：tree-sitter syntactic vs LSP type-aware

三個工具在 Dart 上的能力差距，根源是兩條技術路線的本質落差：

tree-sitter syntactic：只看語法結構。看到 a.b() 知道有個 method call、不知道 a 是什麼型別、不知道 b() 連到哪個 declaration。對 receiver 是 literal 或顯式型別宣告的 callsite 可以解、對 local variable / parameter / 推斷型別的 callsite 會漏。

LSP type-aware：走 language server 內建的型別推斷引擎。跟 IDE 用同一套後端、能解出 a 的真實型別、再從 type declaration 找到對應的 method。所以 reference 是型別精確的。

cbm 的 hybrid type resolution（限 Go / C / C++ / TS / JS）是把 LSP 的型別解析算法 clean-room 重寫進 binary、所以那幾個語言上 cbm 等於有 LSP 級精度但沒 LSP 依賴。Dart 沒得到這個待遇，所以 cbm 在 Dart 上只剩純 syntactic 結構抽取。

判讀訊號：看一個工具對某語言的能力強弱，問「它在這語言上做型別解析嗎？」——做的話接近 LSP，不做的話只是個結構抽取器。

這個 framework 建立後、下節展開到 9 個維度的設計對照。

三個工具的設計差異對照

三個工具雖然都是「code intelligence MCP」，設計取向互補：

這張表的判讀重點：三者擅長的事不重疊。cbm 強在「找東西」、codegraph 強在「日常 call graph + auto-sync」、serena 強在「型別精確 reference + 編輯出口」。

對照表的維度很多、但實務上踩到事故的多半集中在三個維度，把它們各自展開：

Type resolution 決定 caller 數字的可信度。Dart / Swift / Kotlin 這類「LSP 完整、但 cbm 走純 syntactic 路線」的語言上、tree-sitter 工具回的 caller 數字是 lower bound（實際值通常更高）。samplePrice.multiplyByRate(...) 這種 type-inferred receiver 是這層差距的主戰場。判讀訊號：對熱門 class 跑同一 query、若 tree-sitter 工具 caller 數比 LSP 工具低過半、type-inferred dispatch 在這語言是主流模式、tree-sitter 結果只能當 starting point。

Sync 機制決定「邊改邊問」是否可用。codegraph 的 native OS file watcher + 2s debounce 最貼近 IDE、cbm 的背景 git polling 有秒級至分級延遲、serena 的 session warm-up 是「啟動時等一次、之後即時」。事故型態：在 codegraph 改完檔案立刻問 caller 多半 OK、在 cbm 立刻問會拿到 stale graph。判讀訊號：問完 query 對結果存疑時、先檢查工具的 sync 狀態（cbm 跑 index_status、codegraph 跑 codegraph_status、serena 直接重 query）。

持久化模式決定跨 session 的累積成本。cbm / codegraph 寫 SQLite、跨 session 重用；serena per-session、每次 spawn LSP warm up。對「短任務反覆 ad-hoc 查詢」cbm / codegraph 邊際成本更低、對「會做 symbol-level edit 跟 diagnostic」serena 的 per-session warm up 是必要 cost。判讀訊號：第一次 query 慢、之後快——LSP indexing warm up、正常；每次 query 都慢——LSP 可能因記憶體不足重啟、需排查。

下面的實測是這張表在 Dart 上的數字驗證。

Dart 實測對照：同題不同工具

實測環境：

1專案類型：Dart 商業專案（POS / 零售領域）
2Branch：refactor/money-value-object
3索引規模：
4  cbm:        3,038 nodes,  6,355 edges（Dart 沒 CALLS edge）
5  codegraph:  6,244 nodes, 12,223 edges（含 CALLS edge）
6  serena:     per-session、無索引統計

cbm 跟 codegraph 的 nodes 約 2x、edges 約 2x，差異關鍵不在 nodes（cbm 缺 import / enum_member 等次要 node）、而在「有沒有 CALLS edge」——這直接決定 caller / impact 類查詢能不能用。

實測數字的適用範圍：本節的所有 callsite / caller / impact 數字（含查詢 1-5）都是單一 Dart 商業專案的內部 baseline、不保證跨專案重現。Dart 上 type-inferred receiver 比例高的專案會放大三個工具的差距、比例低的專案會縮小差距。換到 Swift / Kotlin / Rust 等語言上、絕對數字會不同但「tree-sitter syntactic vs LSP type-aware」的差距方向通常一致。讀者要套用結論時、先在自家 repo 跑一遍同題對照、看自己的數字落差。

查詢 1：誰呼叫了 Money.multiplyByRate

codegraph 漏掉的 3 個 callsite 共同特徵：

1// lib/data/models/product/product.dart
2final Money samplePrice = ...;
3samplePrice.multiplyByRate(Decimal.parse('0.9'));
4samplePrice.multiplyByRate(Decimal.parse('0.6'));

samplePrice 是 local variable、要型別推斷才知道是 Money。tree-sitter 看到的只是 <identifier>.multiplyByRate(...)、解不出 dispatch target。

serena 透過 dart analysis_server 拿到完整型別資訊、知道 samplePrice 宣告是 Money、能精確 dispatch。

查詢 2：誰呼叫了 LocaleSymbolConfig.formatAmount

這題 codegraph 跟 serena 的差距比較小——formatAmount 在很多地方是用顯式 receiver 呼叫（如 LocaleSymbolConfig.cny.formatAmount(...)），tree-sitter 對顯式 receiver 解得到。

兩邊數字的差異主因是 caller symbol 數 vs callsite 數的計數單位差：

• codegraph 算 caller symbol（一個 method 內呼叫幾次都算 1）
• serena 算 callsite

寫實測 baseline 時這個單位要寫死、否則 3 vs 9 看起來像精度差距、實際上一部分只是計數規則不同。

查詢 3：Money 符號的內部結構

Dart extension type 是相對新的特性、tree-sitter grammar 對它的支援深度不一。serena 走 LSP 直接拿到 dart analysis_server 對 extension type 的完整解析。

對需要「列出某 class / extension 所有 member」的場景、serena 是 Dart 上 LSP 級精度最可信的選項（其他 MCP 在 Dart extension type 上做不到完整 member 列舉）。

查詢 4：概念性搜尋「金額顯示」相關函式

對「我不知道精確名稱、只記得功能類別」這種 query：

前 4 名兩邊都抓到核心 formatAmount 實作，第 5 名後分歧明顯：

• cbm 補進的 getBalanceDisplay / _buildPriceDisplay / connectExternalDisplay 都跟「金額顯示」概念相關（顯示金額 / 顯示餘額 / 外接顯示器）
• codegraph 補進的 displayName / displayTags 只是符號名含 “display” 子字串、跟金額無關

差異來源是 cbm 的 11-signal scoring + cbm_camel_split 對 camelCase 切詞做語意切分（getMoneyField → get + money + field）。codegraph 的 search 是 symbol pattern match、沒對自然語言 query 做語意處理。

這題的判讀很關鍵——cbm 在「找東西」的角色不能被 codegraph 取代。即使 codegraph 在 Dart 上有可用的 call graph、它的 search 仍然贏不了 cbm 的概念性 query。

查詢 5：Money 的 impact 範圍 / cross-symbol trace

Money 是該專案大量使用的 value object、實際被使用的檔案橫跨 receipt_data 實作、settlement、cart_item、order_dto 等業務模組。codegraph 只回 1 個檔案 5 個 symbol、嚴重低估 blast radius。

漏掉的原因跟查詢 1 同源——something.multiplyByRate(...)、Money 在 factory 內被隱式構造這些都不在 tree-sitter 能解的範圍。MoneyFieldRenderer 之所以被抓到、是因為它的 field 顯式宣告為 Money，這是少數 tree-sitter syntactic 能抓的場合。

對 cross-symbol trace：

1codegraph_trace(from: "Money/multiplyByRate", to: "ProductSpecification")
2→ "No direct path"、建議跳到 dynamic dispatch

graph 上根本沒這條 edge（漏掉的 product.dart 那 3 個 callsite 正是這條 trace 的關鍵跳）、所以 trace 直接失敗。

判讀訊號：重要 refactor 不能單看 codegraph 的 impact 數字。要走 serena find_referencing_symbols 二次確認；對 cbm 不在 hybrid resolution 名單的語言、blast radius 必須用 LSP 工具驗證。

三刀流工作流

實測結論：cbm / codegraph / serena 各有不可替代的角色，組合使用才是 Dart 主力專案的合理 stack。

 1找東西（不知道精確名稱、概念性 query）
 2  → cbm search_graph(query="...")           ← 11-signal scoring 對概念性 query 最強
 3
 4知道精確名稱、找 caller / callee
 5  → codegraph_callers / codegraph_callees   ← auto-sync 2s 反應最快
 6  ↓
 7  發現結果可能不完整（type-inferred dispatch 多的場合）
 8  → serena find_referencing_symbols         ← LSP 完整精度補位
 9
10重要 refactor 確認 blast radius
11  → serena find_referencing_symbols         ← 不能單靠 codegraph_impact
12
13符號層級的編輯
14  → serena replace_symbol_body / rename     ← symbol-level atomic edit
15
16跨 service HTTP/RPC 鏈接（若 monorepo 含 client + server）
17  → cbm HTTP_CALLS edge                     ← 三個工具中只有 cbm 有這層

幾個關鍵的判讀原則：

入口跟出口要分清楚：cbm 是「廣度索引 + 模糊搜尋」的入口、拿到 qualified name 後轉給 serena 做精確查詢與編輯。codegraph 補在中間、做日常結構查詢。

重要 refactor 必走 serena 補位：codegraph 的 caller / impact 在 Dart 上系統性偏低、不能單看數字判斷影響範圍。決定 rename 或大幅修改 method 之前、用 serena 跑一次 find_referencing_symbols 對齊。

Hook 不要打架：cbm 會寫 PreToolUse hook 攔截 Grep / Glob / Read / Search（README 描述只擋前兩者、實裝版本含 Read / Search）、codegraph / serena 都不寫 hook。同時用三個工具時、注意 cbm hook 是否誤判把正常的 markdown grep 也擋掉（實測有 false positive）。

對其他語言 stack 怎麼變化

這個三刀流結論限定 Dart。不同語言 stack 的真實壓力不一樣、推薦組合也跟著變——把幾個常見 stack 各自展開。

Go / TypeScript / C / C++ 主力

這層是 cbm 的甜蜜點：hybrid type resolution 涵蓋這四個語族、CALLS edge 抽得到、cbm 的 caller / blast radius 精度接近 LSP。實務影響是「cbm 在 Dart 上需要 codegraph + serena 補位」的場景大幅縮小——cbm 自己就能處理 caller / impact、加上它原本就強的 11-signal 概念搜尋跟跨 service HTTP_CALLS，等於一個工具撐住「找東西」「caller / impact」「cross-service」三層。

serena 在這個 stack 仍是 symbol-level edit 跟 compile diagnostic 的關鍵來源——cbm 純讀、沒 rename / replace_symbol_body、沒 LSP 診斷整合。所以合理組合是「cbm + serena 雙刀流」、codegraph 的角色被 cbm 取代掉。判讀訊號：在自家 repo 跑 cbm trace_call_path 對 5 個熱門 class、若 caller 數跟 serena 的 find_referencing_symbols 對得上、codegraph 確實可以省下。

Swift / Kotlin / Rust 主力

這層跟 Dart 場景結構接近：serena 透過 sourcekit-lsp / kotlin-language-server / rust-analyzer 能拿到完整型別解析、cbm 不在 hybrid resolution 名單只剩純 syntactic。所以「三刀流」的論證仍適用。

但 codegraph 在這三個語言的 query 品質要實測——19+ 列表內這幾個都列為 supported、實際解析深度因語言成熟度而異。Swift 特別容易踩坑的點是 Objective-C interop（dispatch table 跨語言）跟 protocol extension 的型別推斷、Kotlin 則是 reified generics 跟 inline function、Rust 是 trait method 跟 macro 展開後的 callsite。判讀訊號：對自家專案最常用的 dispatch pattern 寫一個 minimal example、跑 codegraph callers、看抓不抓得到。

Python 主力

三個工具的 Python 支援都成熟、但著力點不同：cbm 對 Python 有完整 hybrid resolution、codegraph 對 Python 是核心支援語言之一（VS Code benchmark 在它的 7 codebase 列表內）、serena 透過 pyright / pylsp 拿型別資訊。

Python 的特殊壓力是 dynamic dispatch（duck typing / monkey patching / metaclass / getattr）——這層任何 static 工具都會漏。判讀訊號：對自家 codebase 跑「找 X class 的所有 method 呼叫」、若大量真實 callsite 在 type annotation 缺失的位置、所有工具都只能給 lower bound。實務組合多半雙刀（codegraph + serena）夠用、cbm 對 Python 的不可替代價值在 cross-service HTTP_CALLS（Django / FastAPI 跨 service 場景）。

冷門語言 / DSL（Liquid / Pascal / Svelte template 等）

這層 serena 多半沒 LSP 可借（除非自備 server）、cbm 純 syntactic（hybrid 名單外）、codegraph 是少數仍有 query 的工具——但 query 品質要看 codegraph 對該語言投入多深、Pascal / Delphi / Liquid 這類列表末段的支援度可能只到 symbol 抽取、callsite 不一定有。

實務上對這層語言、退回 grep + codegraph 比強推三刀流合理——caller / impact 用 codegraph 試、不夠就 grep 補、別期待 LSP 級精度。判讀訊號：若 codegraph status 顯示 indexed file 多但 edges 數明顯偏低（< 1 條 edge per file）、call graph 多半沒抽起來、視同純 syntactic 工具用。

共通的評估方法

無論哪個 stack、第一次裝 MCP 前在自家 repo 跑「找重要 class / function 的所有 caller」這個基準題、把不同工具的數字並列比較、再決定組合。README benchmark 是行銷數字、自家 stack 跑出的數字才是真實 baseline。

評估新 MCP 工具的 checklist

從這次踩三個（含一個跳過實裝的 GitNexus）的經驗回推、未來評估新 code intelligence MCP 要先確認：

License：商業專案要 MIT / Apache 2.0 / BSD。PolyForm Noncommercial 之類限制商業使用的 license 直接刷掉。這條最便宜、最早做、最少人記得做。

目標語言的 call graph 支援：README 寫「full support」要實測。tree-sitter wrapper 通常只到「結構抽得到」、沒到「call edge 抽得到」。同樣是「有 CALLS edge」、有 type-inferred dispatch 的 syntactic 工具跟有完整 LSP 的差距可能 2-3x callsite 數。

MCP tool 數量不等於能力：14 個 tool 不一定贏過 10 個。看 caller / impact / find_referencing_symbols 這類核心功能有沒有、品質好不好、勝過 tool 多寡。

是否會自動改 ~/.claude/ 設定：大多會。先看 install script 動了哪些檔案、能不能還原、uninstall 是否徹底（cbm uninstall 不清 hook 是踩過的坑）。

是否有 CLI 模式：有的話本 session 就能實測、不必等 Claude Code 重啟載入 MCP。CLI mode 對「驗證 baseline」特別重要——拿 CLI 結果當 ground truth、再對 MCP 結果做差異比對。

Auto-sync 機制：file watcher / git polling / 純手動 reindex 差異很大。「邊改邊問」工作流對 sync 延遲很敏感、選錯會踩到 stale graph 的事故。

結論

對 Dart 主力專案：三刀流（cbm + codegraph + serena）是合理 stack。三者擅長的事不重疊、互相補位有明確角色：

• cbm：概念性搜尋入口、跨 service HTTP/RPC 鏈接
• codegraph：日常 80% 的結構查詢、auto-sync 反應最快
• serena：型別精確 reference、symbol-level atomic edit、編譯 diagnostic

對其他語言 stack、cbm 進入 hybrid resolution 名單後組合會收斂、但 serena 的 symbol edit 跟 diagnostic 角色仍不可取代。

評估方法的更普遍結論：README benchmark 只是起點、要在自己的 stack 上跑同樣的基準題才算數。每個工具的 benchmark 都選自己擅長的語言跟 codebase、跨語言遷移結論需要重新驗證。用 5 個查詢做 baseline、把 CLI 數字當 ground truth、再對 MCP 結果做差異對比、是現階段最低成本的工具評估法。