/ 目录 / 演练场 / 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 工具的 schema 到 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

使用 10+ 个 MCP 服务器运行 Pi,不会撑爆上下文窗口

👤 Pi 编程代理的高级用户 ⏱ ~20 min intermediate

何时使用: 你想要文件系统、git、github、postgres、playwright、fetch、firecrawl——超过 Pi 能贪婪加载的数量。

前置条件
  • Pi 已安装 — 参见 badlogic/pi-mono
步骤
  1. 安装适配器
    运行 pi install npm:pi-mcp-adapter 并重启 Pi。✓ 已复制
    → 适配器列在 Pi 的扩展中
  2. 配置所有 MCP
    以懒加载模式将文件系统、git、github、postgres MCP 添加到 pi-mcp-adapter。✓ 已复制
    → 服务器已注册;没有启动开销
  3. 通过搜索使用
    使用 mcp({search: 'list files'}) 找到合适的工具,然后调用它。✓ 已复制
    → 相关工具出现;然后被调用

结果: Pi 内部可用完整的 MCP 生态系统,上下文占用极少。

注意事项
  • 搜索遗漏工具,因为描述不好 — 将频繁使用的工具提升为'直接工具',这样 Pi 能贪婪地看到它们

将你最常用的 3 个 MCP 工具提升为一级 Pi 工具

👤 日常使用 Pi 的开发者 ⏱ ~10 min beginner

何时使用: 你注意到 Pi 在使用文件系统读取前每次都调用 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 以懒加载模式注册文件系统、git 和 github。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
mcp {search?: str} | {describe?: str} | {tool?: str, args?: JSON-string} 通用代理——Pi 默认看到的唯一工具 ~200 个 token 贪婪 + 按需工具执行
/mcp-auth <server> 服务器名称 手动为特定服务器触发 OAuth 免费

成本与限制

运行它的成本

API 配额
没有自己的配额——代理到底层 MCP
每次调用 Token 数
~200 个 token 贪婪开销 vs N*~500 完整工具列表
费用
免费、开源
提示
从懒加载开始。仅在遥测显示 Pi 每个会话调用工具 ≥5 次时才提升为直接工具。

安全

权限、密钥、影响范围

凭据存储: OAuth token 在 ~/.pi/mcp-adapter/ 中——视为敏感信息
数据出站: 取决于配置的上游 MCP

故障排查

常见错误与修复

mcp({tool: ...}) 显示'工具未找到'

工具名称区分大小写并由服务器命名空间化。首先使用 describe 获取确切名称。

OAuth 循环永不完成

适配器的本地回调端口可能被阻止。检查重定向 URL 是否与提供商注册的内容匹配。

服务器启动但工具调用挂起

上游 MCP 无声地崩溃。临时切换到贪婪模式以查看启动错误。

验证: pi-mcp-adapter logs

替代方案

pi-mcp-adapter 对比其他方案

替代方案何时用它替代权衡
原始 MCP 集成你运行 Pi 只有 1-2 个 MCP 服务器更简单,但当你添加服务器时会消耗上下文
mcp-gateway你需要跨许多 MCP 的安全/个人身份信息编辑(不仅仅是 token 效率)Python 网关;更多关注安全性而不是 token 节省

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills