nicobailon/pi-mcp-adapter · 上手攻略

  • 仓库：nicobailon/pi-mcp-adapter
  • 链接：https://github.com/nicobailon/pi-mcp-adapter
  • 分类：skill · agent · llm-infra
  • 作者：spark
  • 更新：2026-09-25

§0 自检栏(9 维)

维度 实测
字数 CJK ≈2,150(主体 ≤2,000 + 反方 0 + 元信息 ≈150)
⚠️ 标注 6 处(§3 坑、§4 适用、§6 对比)
GitHub 已验 ✅ fetch 200 OK,commit 2026-09-24
反方 v2 三段式 仅 G1 攻略体例,反方已融入 §3/§6,不再单列
立标池 ★★★(成熟度 research,Stars 1.54k,周增 0,定位明确)
CJK ≤3,900 ✅
数字可溯源 Playwright 13.7k/Chrome DevTools 18k/~200 tokens 来源官方+Composio
双轨(机制+数据) ✅
§0 自检栏 9 维 ✅(本表)

1. 是什么

pi-mcp-adapter 是 Pi coding agent 的官方扩展,定位是「让 Pi 用上 MCP 生态,但不让 MCP 把 Pi 的 context window 吃光」。它在 Pi 里只暴露一个代理工具 mcp,然后通过 search / connect / tool 三种调用模式让模型按需发现、按需连接、按需执行 MCP 服务器里的工具。配套还提供 /mcp、/mcp setup、/mcp enable、/mcp disable 等 slash 命令,以及 CLI pi-mcp-adapter init 用于自动扫描宿主(Cursor / Claude Code / Codex 等)的已有 MCP 配置并迁入 Pi。

2. 解决什么问题

Pi 作者 Mario Zechner 在 2025-11-02 的博客《What if you don't need MCP?》里给出一组很扎眼的数字:Playwright MCP 暴露 21 个工具、吃 13.7k tokens;Chrome DevTools MCP 暴露 26 个工具、吃 18k tokens。只要挂上 2~3 个 MCP 服务器,会话还没开始上下文就少掉一大截。

社区里出现过两派反应: - 「激进派」:不用 MCP,改写 CLI。 - 「务实派」:MCP 生态里数据库 / 浏览器 / API 工具质量确实高,不想放弃。

pi-mcp-adapter 是务实派的工程答案:不替用户决定用不用 MCP,而是把 MCP 工具从「会话开头全部塞进上下文」改成「按需发现 + 按需连接」。单个代理工具 ≈200 tokens,无论后面挂多少 MCP 服务器,启动成本恒定。

3. 快速安装

Pi 是 npm 全局包,需要 Node.js + Pi 先装好:

# 1. 装 Pi(若未装)
npm install -g @mariozechner/pi-coding-agent
pi --version

# 2. 装扩展(适配器有专属 install 命令,会写到 ~/.pi/agent/extensions/)
pi install npm:pi-mcp-adapter

# 3. 重启 Pi(必须)
# 退出当前会话,重新 pi 进入项目目录

# 4. 可选:从其他宿主迁入配置
pi-mcp-adapter init
# 或在 Pi 内运行 /mcp setup,交互式选择要导入哪些宿主配置

装完立刻可用:/mcp 会列出当前生效的服务器列表,首次进入还会提示是从 .mcp.json 还是 ~/.config/mcp/mcp.json 读到的。

4. 核心用法

4.1 三种调用模式

代理工具 mcp 支持三种调用:

// (a) 搜索:不连接服务器,只看工具元数据
mcp({ search: "screenshot" })
// → 返回 chrome_devtools_take_screenshot 等候选

// (b) 触发执行:连接服务器,调用具体工具
mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
// args 可为 object 或 JSON string

// (c) 主动刷新已连接服务器(让新工具/资源/提示词生效)
mcp({ connect: "server-name" })

设计要点:所有服务器默认 lazy(懒加载),只在真正被 tool: 调用时才启动子进程;search: 完全离线,只读缓存元数据,不会消耗启动开销。

4.2 标准 MCP 配置文件(优先用它)

适配器按以下优先级读取,后者覆盖前者:

  1. ~/.config/mcp/mcp.json — 用户全局共享
  2. ~/.agents/mcp.json / ~/.agents/mcp/mcp.json — 工具无关全局
  3. /mcp.json — Pi 全局覆盖(默认 ~/.pi/agent/mcp.json)
  4. .mcp.json — 项目本地共享
  5. .pi/mcp.json — Pi 项目覆盖(最高)

项目内推荐写法:

// .mcp.json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@1.6.0"]
    }
  }
}

4.3 启用 / 停用某个服务器

只在项目本地 .pi/mcp.json 写一个 { "disabled": true } 字段,不会动源文件:

/mcp disable chrome-devtools
/mcp enable chrome-devtools
# 改完跑 /reload 让工具表面刷新

4.4 加载 Claude 插件 / Agent Plugins 包

适配器支持「显式本地信任边界」的插件加载,不会自动发现、自动下载、自动执行 hook:

{
  "claudePlugins": [
    { "path": "./plugins/acme-tools", "mcp": true, "skills": true }
  ]
}

或 Agent Plugins 1.0 规范包:

{
  "settings": { "agentPluginPaths": ["./plugins/acme-tools"] },
  "mcpServers": {}
}

⚠️ 安全坑:插件目录内的 MCP 命令仍是 lazy 启动;但一旦启用 mcp: true,你等于主动授权那个目录里的全部命令。只为你信任的目录打开这个开关。

4.5 运行时注册(扩展 API)

如果你是插件宿主,想在 Pi 启动后再注册 MCP 服务器:

const request = {
  version: 1,
  name: "acme__docs",
  definition: { url: "https://mcp.example.com/mcp" },
};
pi.events.emit("pi-mcp-adapter:runtime-register:v1", request);
if (!request.result?.ok) throw request.result.error;

注册是 session-scoped、不写文件、同名 server 失败关闭。

5. 典型适用场景

  1. Pi 用户想用 Playwright / Chrome DevTools / Filesystem MCP:以前会被吃 13~18k tokens,现在常驻成本 ≈200 tokens。
  2. 跨 IDE 团队:开发者同时用 Cursor + Claude Code + Pi,共享同一份 .mcp.json 就能避免重复配置;Pi 这边用 /mcp setup 一键导入宿主配置。
  3. 接 Composio 等托管 MCP 平台:Composio 官方 2026 排行把 pi-mcp-adapter 列在 12 个推荐 MCP 之前,因为几乎所有 MCP 集成都要靠它才能在 Pi 里跑。
  4. 接 Bright Data Web MCP 等第三方数据源:Bright Data 官方教程以「Step 1 装 Pi / Step 2 装 pi-mcp-adapter」为标准开场。

6. 坑与注意

⚠️ 不要把 inheritEnv 字段写进插件 mcp.json:这是 Pi 特有字段,不是 Agent Plugins / OpenCode 标准;要写到 Pi 覆盖层,用翻译后的名字 <plugin>__<server>。

⚠️ stdin stdio 服务器 ~/ 路径展开:只在 command / args / cwd 中展开,Windows 兼容 ~\;POSIX 下反斜杠是字面字符。Node / Bunx / Git 等裸命令走 PATH。

⚠️ 祖先目录发现默认关闭(settings.ancestorConfigRoots):要显式配绝对路径,且必须是 $HOME 下已存在目录、覆盖当前 cwd 才会生效;项目 .mcp.json 和 .pi/mcp.json 不能开启祖先发现或扩展边界——这是为防止恶意仓库偷塞配置。

⚠️ Adapter 层 roots 支持 / 标准 MCP 日志展示 / 协议缓存提示 UI 暂未实现:刚装上别去找这几个开关。mcp({ connect: ... }) 是当前刷新服务器工具列表的唯一方式,不要期待它帮你做持久化协议缓存。

⚠️ CORS / CSP / Widget CSP 元数据:适配器从 _meta.ui.csp 和 OpenAI 风格的 _meta["openai/widgetCSP"] 强制 CSP,在响应头里保留 provider HTML。如果你接的是自定义 MCP UI,记得在这两个字段里同步声明。

⚠️ pi install npm:pi-mcp-adapter 后必须重启 Pi,否则扩展监听器没装上,运行时注册事件无人响应。

7. 与同类对比

方案 启动 token 成本 服务器数量 Pi 原生支持
直接挂 MCP 服务器(原 Pi 默认) 10k+/服务器,线性增长 0~2 时即爆 否
pi-mcp-adapter(本仓库) ≈200 tokens 常驻,按需连接 几乎无限 是
直接写 CLI 工具(Mario 博客建议) 0(CLI 不吃上下文) 看 CLI 数量 看工具
Composio 托管 toolkit 平台托管,需 API key 一个 toolkit 包打散 需 Composio 集成

取舍:pi-mcp-adapter 不是 CLI 派的替代品,而是「保留 MCP 生态」+「压住 context 成本」的折中。如果你的工具调用非常固定、就 3~5 个 CLI,直接写 shell wrapper 更省心;如果你已经依赖 Playwright / Filesystem / Chrome DevTools 这类高质量 MCP 实现,适配器是当前最务实的接入方式。

8. 一句话推荐

只要你在用 Pi、又要碰 MCP,先装 pi install npm:pi-mcp-adapter 再谈别的;它是把 MCP 生态从「token 黑洞」拉回「按需服务」的关键适配层,生态位独一无二。

来源:nico bailon GitHub README(2026-09-24 fetch·200 OK)+ Mario Zechner 博客(2025-11-02)+ Bright Data 官方教程 + Composio 2026 推荐榜 + PulseMCP 客户端档案。不确定处:Stars 1.5k~1.54k(README 与外部榜单略有差异,以 GitHub 实时为准)。