pi-mcp-adapter：用一個代理工具換掉數百個 MCP 工具定義
Token-efficient MCP adapter for Pi coding agent
秒懂
- 它是什麼？
- 這個 TypeScript 擴充套件把 MCP 伺服器的工具定義壓縮成單一 mcp 代理工具，約 200 token，伺服器預設延後連線。它適合已經在用 Pi、又不想讓 context window 被工具定義吃掉的開發者。
- 適合誰用？
- 如果你已經在用 Pi，而且手上有一到數個 MCP 伺服器（資料庫、瀏覽器、內部 API），這個轉接器值得裝：先跑 pi install npm:pi-mcp-adapter，重啟 Pi，再用 /mcp setup 決定要沿用既有的 .mcp.json 還是另建設定。如果你完全沒碰過 MCP，或你的工具集只有兩三個、定義本來就短，那多一層代理只是多一次呼叫往返，直接寫 CLI 工具更省事。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解決的是工具定義的固定成本
MCP 的痛點不在協定本身，而在工具定義的體積。README 直接點名：單一 MCP 伺服器可以吃掉 10k 以上的 token，而且這筆成本在你用不到那些工具時照樣要付。接上幾個伺服器，對話還沒開始，context window 就先少了一半。
專案的出發點是 Mario Zechner 那篇「你可能不需要 MCP」的文章，該文主張乾脆跳過 MCP、自己寫簡單的 CLI 工具。這個轉接器走的是中間路線：承認 MCP 生態裡有資料庫、瀏覽器、API 這些現成好用的東西，但拒絕把完整工具清單塞進 context。做法是把數百個工具定義換成一個代理工具，README 給的數字是約 200 token，其餘的靠代理在需要時才去查。
目標讀者很明確：已經在用 Pi coding agent、而且已經有一份或好幾份 MCP 設定的人。如果你還沒接任何 MCP 伺服器，這個專案對你沒有意義，因為它省下的是你原本就在付的成本。
兩次呼叫取代 26 個工具：代理工具的實際資料流
機制本身不複雜。代理工具 mcp 接受兩種呼叫形式：搜尋與執行。搜尋時傳入關鍵字，例如 mcp({ search: "screenshot" })，回傳符合的工具名稱與參數結構；執行時傳入工具名稱與參數，例如 mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })。README 的說法是「兩次呼叫，而不是 26 個工具塞在 context 裡」。
關鍵在於伺服器預設是延後的（lazy）。在你真正呼叫某個伺服器的工具之前，它不會建立連線。但搜尋與描述要能用，所以轉接器會快取工具的中繼資料，這表示搜尋結果來自快取而非即時連線。這是一個值得注意的取捨：快取讓搜尋不必等伺服器啟動，代價是工具清單可能與伺服器當下的實際狀態不同步。文件沒有說明快取的失效條件與更新時機，這是實際採用前應該自己確認的地方。
args 可以是 JSON 物件或 JSON 字串。README 建議模型能穩定處理時優先使用物件形式，字串形式保留給需要更簡單 schema 的 provider。這個細節透露了設計者對不同模型能力的務實態度，而不是假設所有 provider 都一樣。
安裝與首次啟動：它會自動讀你現有的設定
安裝只有一行：pi install npm:pi-mcp-adapter，之後需要重啟 Pi。
首次啟動的行為取決於你原本有什麼。若已經有 .mcp.json 或 ~/.config/mcp/mcp.json，Pi 會直接沿用，第一次打開 /mcp 時會看到一段說明，指出偵測到哪個檔案，並強調 Pi 只會把轉接器專屬的覆寫寫進自己的檔案。若你只有特定主機的設定（Cursor、Claude Code、Codex 等）而沒有標準 MCP 檔，要跑 /mcp setup 把它們匯入，流程會顯示找到什麼、讓你挑選、並在寫入前預覽變更。若什麼都沒有，同樣是 /mcp setup，可以選專案層的 .mcp.json 或全域的 ~/.config/mcp/mcp.json，再挑一個精選伺服器或快速加入 RepoPrompt。
偏好終端機的人可以在安裝後跑 pi-mcp-adapter init，掃描主機專屬設定並把相容性匯入加進 Pi agent 目錄（預設 ~/.pi/agent/mcp.json，設了 $PI_CODING_AGENT_DIR 時則為該目錄下的 mcp.json）。
一個最小可用的專案設定長這樣：mcpServers 底下放 chrome-devtools，command 是 npx，args 是 ["-y", "chrome-devtools-mcp@1.6.0"]。這裡值得留意的是版本被釘住，不是浮動的 latest。
六層設定檔的優先順序，以及 disable 只寫哪裡
這個專案對設定來源的處理相當講究，也因此在理解上需要一點耐心。優先順序由低到高是：~/.config/mcp/mcp.json、~/.agents/mcp.json、~/.agents/mcp/mcp.json、<Pi agent dir>/mcp.json、.mcp.json、.pi/mcp.json，後面的覆蓋前面的。
主機專屬設定（Cursor、Claude Code 等）不是正常設定路徑，而是相容性輸入，預設不會自動載入。settings.hostConfigDiscovery 的預設值是 "off"，要明確開啟才能啟用回退探索，也可以跑 pi-mcp-adapter init --discover-host-configs；"prompt" 則提供給想要偵測但不啟用的整合。文件強調探索只會回報來源路徑、出處與同名衝突，不會寫入外部主機檔案，也不會從那些檔案默默啟動指令。這個克制是對的，因為從別人的設定檔自動執行指令是明顯的風險面。
/ mcp disable <server> 與 /mcp enable <server> 只會把 disabled 欄位持久化到專案層的 .pi/mcp.json，也就是優先順序最高的一層。啟用時，若較低層本來是啟用的就移除專案旗標，需要覆蓋較低層的停用狀態時才寫入 false。這裡的行為值得記住：即使生效的伺服器來自共用全域檔、匯入的主機設定或 configPath，來源檔永遠不會被改寫，憑證也不會被複製。改完旗標要跑 /reload，註冊的工具介面才會更新。手動等價做法是在任一正常 MCP 設定裡對該伺服器加上 { "disabled": true }。另外，透過 createMcpAdapter({ config }) 以記憶體傳入的設定是隔離的，不讀也不寫這個專案覆寫，相關指令在該模式下無法使用。
延遲載入與快取中繼資料的代價
把伺服器設成延後連線，好處是啟動快、沒用到的伺服器不佔資源。壞處有兩個層面。
第一是搜尋品質取決於快取。既然搜尋與描述靠的是快取的工具中繼資料，那麼一個剛加入、還沒被連線過的伺服器，其工具能不能被搜到，取決於快取建立的時機。文件沒有交代快取的建立與更新政策，這在實務上意味著你可能遇到「明明設好了卻搜不到」的情況，而排查時手上沒有明確的規則可依。
第二是多了一次往返。原本模型可以直接呼叫工具，現在要先搜尋、再執行。README 自己也承認這是兩次呼叫。對工具數量少的情境，這個交換不划算：如果一個伺服器只提供兩三個工具，直接暴露定義的 token 成本本來就低，代理反而增加了延遲與一次失敗機會。這個專案的價值隨工具總數上升，工具少的時候它是一種負擔。
還有一個不能從文件確認的點：代理工具本身如何處理伺服器啟動失敗。README 沒有描述錯誤路徑，所以不應該假設失敗會被優雅地回報。
Agent Plugins 與 directTools：擴充路徑與寫入目標
除了標準 MCP 檔，轉接器可以從 Agent Plugins 套件載入伺服器，只要在 settings.agentPluginPaths 列出外掛目錄，例如 ["./plugins/acme-tools"]。每個目錄必須包含合法的 Agent Plugins 1.0 plugin.json。這條路徑適合把一組相關伺服器打包成可散佈的單位，而不是每個專案各自複製設定。
Pi 專屬檔案的角色需要分清楚。~/.pi/agent/mcp.json 是 Pi 全域覆寫與相容性匯入的落點，.pi/mcp.json 是專案覆寫。文件說明這些 Pi 專屬檔案是匯入或共用全域伺服器時的寫入目標，用來持久化 directTools 這類轉接器專屬設定。換句話說，共用設定檔保持乾淨、跨主機可用，Pi 自己的偏好則集中在自己的檔案裡。這個分離讓同一份 .mcp.json 可以同時給多個主機使用，代價是你需要知道有兩套檔案在互動。
README 在 Agent Plugins 段落被截斷，plugin.json 的完整欄位與載入失敗行為無法從現有材料確認。
授權、維護成本，以及該不該採用
授權是 MIT，寬鬆，可商用、可修改、可再散布，只要保留著作權與授權聲明。這裡不構成法律意見，實際條文仍應以 repository 內的 LICENSE 檔為準。
維護面有幾個可觀察的訊號。主要語言是 TypeScript，版本節奏相當密集：v2.31.0 在 2026-08-28，v2.32.0 與 v2.32.1 都在 2026-09-01，且 2.32.0 到 2.32.1 之間只隔約四分鐘，看起來是當天修補。最後推送時間是 2026-09-05。這種節奏對採用者的意思是：設定檔的優先順序與旗標行為這類細節，在版本之間有變動的可能，升級時值得看一下 release notes，而不是無腦更新。
替代方案是 README 自己引用的那條路：照 Mario 的建議，不用 MCP，直接寫 CLI 工具。兩者的差異在於誰承擔工具定義的成本。寫 CLI 工具等於你自己維護介面，工具數量由你控制，context 成本可預期，但你要為每個資料庫或 API 各寫一份，而且沒有現成的 MCP 生態可撿。這個轉接器則是接受 MCP 生態、把成本壓到一個代理工具加上快取。選擇的依據是：你需要的工具是少數幾個你自己寫得出來、而且長期穩定的，還是會持續增減、來自多個現成伺服器的。前者寫 CLI，後者用轉接器。
至於 DSH，README 提到可以透過第三方橋接 pi2dsh 在未修改的轉接器上執行，並指向一份 TUI 與 Web MCP 的指南。這是第三方專案，不在這個 repository 的維護範圍內，採用前應自行評估。
編輯結論
如果你已經在用 Pi，而且手上有一到數個 MCP 伺服器（資料庫、瀏覽器、內部 API），這個轉接器值得裝：先跑 pi install npm:pi-mcp-adapter，重啟 Pi，再用 /mcp setup 決定要沿用既有的 .mcp.json 還是另建設定。如果你完全沒碰過 MCP，或你的工具集只有兩三個、定義本來就短，那多一層代理只是多一次呼叫往返，直接寫 CLI 工具更省事。裝之前先確認兩件事：你的伺服器清單是否已經放在標準路徑（.mcp.json 或 ~/.config/mcp/mcp.json），以及你是否需要 directTools 這類 Pi 專屬設定，因為那會決定它要不要寫入 ~/.pi/agent/mcp.json 或 .pi/mcp.json。
社群筆記