/ 目錄 / 演練場 / pi-mcp-adapter
● 社群 nicobailon ⚡ 即開即用

pi-mcp-adapter

作者 nicobailon · nicobailon/pi-mcp-adapter

將 200 個 MCP 工具掛入 Pi 程式代理,只需約 200 個 token——單一代理工具在實際呼叫時才懶載入伺服器。

pi-mcp-adapter 是 Pi(badlogic/pi-mono)的轉接器,Pi 是一個極簡主義的程式代理。它不會急切地將每個 MCP 工具的結構描述載入 Pi 的上下文,而是暴露一個單一的 mcp 代理工具(約 200 個 token),支援 searchdescribetool 呼叫。伺服器在需要時才啟動,閒置後自動斷線。

為什麼要用

核心特性

即時演示

實際使用效果

pi-mcp-adapter.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "pi-mcp-adapter",
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "pi-mcp-adapter": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "pi-mcp-adapter"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add pi-mcp-adapter -- npx -y pi-mcp-adapter

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: pi-mcp-adapter

在不撐爆上下文視窗的前提下,讓 Pi 運行 10 個以上的 MCP 伺服器

👤 Pi 程式代理的進階使用者 ⏱ ~20 min intermediate

何時使用: 你想要使用 filesystem、git、github、postgres、playwright、fetch、firecrawl 等——多到 Pi 無法急切載入的程度。

前置條件
  • Pi installed — 參閱 badlogic/pi-mono
步驟
  1. 安裝轉接器
    執行 pi install npm:pi-mcp-adapter 並重新啟動 Pi。✓ 已複製
    → 轉接器列於 Pi 的擴充功能中
  2. 設定所有 MCP
    以懶載入模式將 filesystem、git、github、postgres MCP 新增至 pi-mcp-adapter。✓ 已複製
    → 伺服器已註冊;無啟動額外負擔
  3. 透過搜尋使用
    使用 mcp({search: 'list files'}) 找到正確的工具,然後呼叫它。✓ 已複製
    → 相關工具浮現;隨後被呼叫

結果: 在 Pi 內使用完整的 MCP 生態系,且上下文佔用極小。

注意事項
  • 因工具描述不佳導致搜尋漏掉某個工具 — 將常用工具提升為「直接工具」,使 Pi 能急切地看到它們

將你最常用的 3 個 MCP 工具提升為 Pi 的一等工具

👤 每天使用 Pi 的開發者 ⏱ ~10 min beginner

何時使用: 你注意到 Pi 每次使用 filesystem read 之前都會呼叫 mcp({search: ...})——將它新增為直接工具以跳過這個繁瑣步驟。

步驟
  1. 找出常用工具
    在我最近的 Pi 工作階段記錄中,哪些 mcp 工具呼叫出現最頻繁?✓ 已複製
    → 前 N 名清單
  2. 標記為直接工具
    在 pi-mcp-adapter 設定中將這些工具設定為直接工具。✓ 已複製
    → 工具現在以 Pi 一等工具的形式出現

結果: 加快代理迴圈速度,並降低重複工具探索的 token 消耗。

注意事項
  • 直接工具太多反而失去意義 — 直接工具數量保持在 ≤5 個;只在使用頻率高時才提升

在 Pi 中使用受 OAuth 保護的 MCP 伺服器(例如 Linear、Slack)

👤 使用企業 MCP 的 Pi 使用者 ⏱ ~15 min intermediate

何時使用: 你的 MCP 伺服器需要 OAuth 授權,而你不想手動處理 token 更新。

步驟
  1. 啟用 autoAuth
    在 pi-mcp-adapter 設定中,為 linear 伺服器設定 autoAuth: true。✓ 已複製
    → Pi 在第一次使用時開啟瀏覽器
  2. 在瀏覽器中授權
    核准權限請求;token 將被持久化儲存。✓ 已複製
    → 後續呼叫自動使用已更新的 token

結果: 受 OAuth 保護的 MCP 整合在 Pi 中「開箱即用」。

注意事項
  • Token 以未加密形式儲存在磁碟上 — 使用加密的家目錄或作業系統金鑰鏈橋接

組合

與其他 MCP 搭配,撬動十倍槓桿

pi-mcp-adapter + filesystem + git-2 + github

在 Pi 內以懶載入工具完成完整的開發迴圈

以懶載入模式透過 pi-mcp-adapter 註冊 filesystem、git 和 github。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
mcp {search?: str} | {describe?: str} | {tool?: str, args?: JSON-string} 通用代理工具——預設情況下 Pi 唯一看得到的工具 ~200 tokens eager + on-demand tool execution
/mcp-auth <server> server name 手動為特定伺服器觸發 OAuth 流程 free

成本與限制

運行它的成本

API 配額
本身不消耗配額——代理至底層 MCP
每次呼叫 Token 數
急切載入約 200 個 token 額外負擔,相較於完整工具列表的 N×約 500 個 token
費用
免費,開放原始碼
提示
從懶載入開始。只有當遙測顯示 Pi 每個工作階段呼叫某工具 ≥5 次時,才將其提升為直接工具。

安全

權限、密鑰、影響範圍

憑證儲存: OAuth token 儲存於 ~/.pi/mcp-adapter/——請視為敏感資料
資料出站: 取決於所設定的上游 MCP

故障排查

常見錯誤與修復

mcp({tool: ...}) says 'tool not found'

工具名稱區分大小寫,並以伺服器名稱作為命名空間。請先使用 describe 取得確切名稱。

OAuth loop never completes

轉接器的本地回呼連接埠可能被封鎖。請確認重新導向 URL 與提供者已註冊的設定相符。

Server starts but tool calls hang

上游 MCP 已靜默崩潰。暫時切換至急切載入模式以查看啟動錯誤。

驗證: pi-mcp-adapter logs

替代方案

pi-mcp-adapter 對比其他方案

替代方案何時用它替代權衡
Raw MCP integration你的 Pi 只搭配 1-2 個 MCP 伺服器使用較為簡單,但隨著伺服器增加會消耗大量上下文
mcp-gateway你需要跨多個 MCP 進行安全性/個人識別資訊過濾(而非僅追求 token 效率)Python 閘道;目標是安全性,而非節省 token

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills