pi-mcp-adapter

用按需激活和结果裁剪接入外部 MCP 服务,避免工具定义撑爆上下文。

安装命令
pi install npm:pi-mcp-adapter
临时试用 / 替代安装命令
pi -e npm:pi-mcp-adapter
挂接事件钩子与注册入口
session_startbefore_agent_startmcp_servers_changeresources_discovertool_calltool_resulttool_execution_endagent_endsession_treesession_shutdown
pi.setActiveTools()pi.registerCommand("mcp-auth")pi.registerFlag()pi.registerShortcut()pi.sendUserMessage()ctx.ui.confirm / select / editor

1. 是什么

pi-mcp-adapter 是 nicobailon 开发的 Pi MCP 协议适配扩展。

它同时提供 Pi 扩展入口(./index.ts)和独立的 CLI 入口(pi-mcp-adapter),用于管理多台外部 MCP Server 的连接、鉴权与工具调用。

2. 解决什么问题

单个 MCP Server 往往暴露数十个工具,完整 JSON Schema 动辄占用上万 token。如果把三四个 MCP Server 直接注入系统提示词,还没开始写代码,上下文窗口就已经损失一大半。

此外,部分长耗时 MCP 工具会阻塞单轮对话,超长返回结果也会直接把上下文淹没。7.0 版本针对这两个问题加入了 MCP Tasks 后台执行与 extract 字段提取能力。

3. 作用原理(事件钩子与工具注册层)

通过代理入口与动态激活机制延迟加载 MCP 工具 Schema,并在生命周期钩子中裁剪返回内容。

  • 启动阶段(session_start / resources_discover)读取配置中的 MCP Server 清单并建立或延迟建立连接,同时监听 mcp_servers_change 应对热更新。
  • 在对话前避免把全部 MCP 工具平铺进上下文,改为提供按语义检索工具的机制,匹配到相关工具后再通过 pi.setActiveTools() 动态把对应 schema 激活到后续请求。
  • 对于支持 MCP Tasks(protocolVersion: “auto”)的服务,慢速工具转入后台异步执行,主会话继续推进并在完成后由 agent_end / sendUserMessage 回传。
  • 工具执行后通过 tool_result 钩子与 extract 机制,从长响应中只抽取模型所需的字段送回上下文,其余细节不占用 token。

4. 怎么装与基本配置

  • 执行 pi install npm:pi-mcp-adapter 后,在项目或全局 MCP 配置文件中填入需要挂载的 stdio / HTTP MCP Server。
  • 对于需要 OAuth 登录的远程 MCP 服务,可在 Pi 内执行 /mcp-auth 完成浏览器授权流程。
  • 若上游 MCP Server 支持异步任务协议,在配置中添加 “protocolVersion”: “auto” 即可启用后台 Task 执行。

5. 和同类怎么选

同方向中,pi-mcp-adapter 侧重“省 token 的按需装配与大规模 MCP 调度”,pi-mcp-extension 侧重“轻量化直连标准传输协议”。

与同类方案的选型对照

聚焦机制差异与适用边界,结合自身运行环境判断是否引入或保留同类替代包。

对比对象 机制差异 怎么选
pi-mcp-extension 聚焦标准 stdio / SSE / Streamable HTTP 与 OAuth 2.1(PKCE+DCR),依赖更少、结构更直白。 只接 1 到 3 个常用 MCP 服务、希望配置透明可控时选它。
pi-web-access 专注联网搜索、页面抽取和音视频解析,不负责通用第三方 SaaS 的 MCP 桥接。 只需要查网页、读 PDF 和解析视频时直接装 pi-web-access,无需自配搜索 MCP。

同方向对比包与顺序阅读

@onkernel/browser-loop

Kernel 官方浏览器工具框架与 Pi 扩展,按模型能力编译 GUI 动作并在云端浏览器执行。

阅读该包机制详评

pi-web-access

零配置起步的 Pi 联网套件:多引擎搜索回退、页面结构化抽取、PDF 与视频理解。

阅读该包机制详评

01 接外部世界

回到该演进方向总论,查看完整痛点拆解、通用安装注意事项与全部收录清单。

返回方向总论页

看完「pi-mcp-adapter」后的下一步

可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)

从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频

已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)

出口 1(配置单与实机演示制作中)

Coding Agent 实战交付课:如何可控地把想法做成线上产品

由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。

出口 2(实战交付课筹备中)