nicobailon/pi-mcp-adapter
Token-efficient MCP adapter for Pi coding agent
解決的問題
Pi MCP Adapter 防止 LLM 上下文窗口被冗長的工具定義淹沒。在標準的 Model Context Protocol (MCP) 設定中，單個伺服器僅用於描述其可用工具就可能消耗數千個 token，無論這些工具是否實際使用，這都會消耗 token。此適配器將數百個單獨的工具定義替換為單一代理工具，允許代理按需發現並呼叫工具。
工作原理
該適配器不是將每個連接的 MCP 伺服器的每個工具直接註冊到 LLM，而是提供一個單一的 mcp 代理工具。代理使用此代理來搜尋特定工具並執行它們。
關鍵技術特性包括：
- Lazy Loading：在實際呼叫工具之前不會連接伺服器，從而減少啟動開銷。
- Configuration Merging：自動偵測並合併來自多個來源的配置，包括標準的
.mcp.json檔案和特定於主機的配置（例如來自 Cursor 或 Claude Code 的配置）。 - Output Guarding：為了防止海量的工具輸出撐爆上下文窗口，適配器將文本輸出限制在 50 KiB 或 2,000 行，並將過大的結果儲存到暫存檔中供代理選擇性讀取。
- Lifecycle Management：支援包括
lazy、eager、keep-alive和lazy-keep-alive在內的多種連接模式，以優化資源使用。
適用對象
使用 Pi 且希望在不犧牲上下文窗口的情況下整合 MCP 伺服器（資料庫、瀏覽器、API）的開發者。
亮點
- 上下文效率：將工具定義開銷從數千個 token 降低到約 200 個 token。
- 靈活配置：支援專案本地和使用者全域的共享 MCP 配置。
- 安全 OAuth：與作業系統憑證儲存整合以進行安全的 token 管理，並支援遠端/無頭 OAuth 流程。
- 資源管理：包含「Output Guard」，防止過大的工具回應導致工作階段崩潰。
- 按需發現：允許代理透過搜尋而不是將所有工具預載入到提示詞中來尋找工具。