Pi MCP 上下文适配器
让 Pi 按需使用 MCP 服务器，避免工具定义占满上下文。
这个 Agent 能做什么，适合哪些场景？
Pi MCP Adapter 是面向 Pi coding agent 的 MCP 扩展包，通过单个 mcp 代理工具访问多个 MCP 服务器。它默认延迟连接服务器，并将工具、资源、提示词和说明的元数据缓存到 Pi agent 目录，使搜索和查看信息通常不必先建立连接。服务器可采用 stdio、HTTP 或 rmcp-mux Unix socket 传输，并支持 lazy、eager、keep-alive 与 lazy-keep-alive 生命周期。它也可把指定 MCP 工具注册为 Pi 的 direct tools，或通过 mcpScript 在工作线程中编排多次 MCP 调用。配置主要来自共享 MCP 文件和 Pi 专属覆盖文件，OAuth 凭据存入操作系统凭据存储。
扩展读取 .mcp.json、~/.config/mcp/mcp.json、~/.agents/mcp.json、~/.agents/mcp/mcp.json 及 Pi 覆盖文件，并按文档所列优先级合并服务器配置。模型可调用 mcp({ search }) 搜索缓存的 Pi 与 MCP 工具、用 mcp({ describe }) 获取参数说明，再以 mcp({ tool, args }) 调用目标工具；mcp({ connect }) 会连接或刷新指定服务器。它在首次实际调用时启动 lazy 服务器、缓存其元数据，并在空闲超时后断开连接；HTTP 服务可配置 bearer 或 OAuth 认证。/mcp 面板、/mcp setup、/mcp reconnect、/mcp disable 和 /mcp-auth 提供交互式配置与状态操作；mcpScript 则提供 tools.search、tools.describe 和 tools.call 等 JavaScript API。对于过大的文本结果，默认 Output Guard 会截断内联输出并将完整文本写入权限为 0600 的临时文件。
- 已在项目中使用 .mcp.json 的 Pi 开发者，希望按需调用 Chrome DevTools 等 MCP 服务，而不是在会话开始时加载全部工具定义。
- 同时配置多个数据库、浏览器或 API MCP 服务的工程师，希望通过 mcp({ search }) 先发现工具，再只连接实际需要的服务器。
- 需要把少量高频 MCP 操作直接放入 Pi 工具列表、但不想把大型服务器的全部工具暴露给模型的团队。
- 在远程或无头 Pi 会话中使用 OAuth MCP 服务的用户，需要通过 auth-start 和 auth-complete 完成浏览器授权。
- 希望复用 Cursor、Claude Code、Codex 等宿主配置的 Pi 用户，可通过 /mcp setup 或 pi-mcp-adapter init 显式导入兼容配置。
这个 Agent 有哪些优点和局限？
- 以约 200 token 的单一代理工具替代大量直接工具定义，并通过按需发现降低初始上下文占用。
- 延迟连接与磁盘元数据缓存结合，使搜索、列表和描述在多数情况下无需先启动 MCP 服务器。
- 同时支持 stdio、HTTP/SSE 回退和显式 rmcp-mux socket，并提供四种连接生命周期策略。
- 可按服务器或工具选择 directTools、includeTools、excludeTools 与 approveTools，在可发现性和提示词体积之间调整。
- 默认 Output Guard 限制大型文本 MCP 输出，并对 OAuth 凭据使用操作系统凭据存储而非持久化明文。
- 核心运行环境是 Pi coding agent；文档只说明对其他宿主配置的兼容导入，未说明可作为独立通用代理部署。
- 首次使用 lazy 服务器仍需连接和启动，direct tools 的初始缓存尚未生成时会先以代理模式工作。
- 跨 Pi 会话共享服务器尚未实现；普通配置下每个 Pi 会话运行自己的服务器进程。
- OAuth 在无头环境仍依赖可用且已解锁的操作系统凭据存储；不可用时会拒绝回退到明文凭据。
- MCP sampling 仅支持文本；上下文注入、工具、停止序列、音频和图像内容会被明确拒绝。
如何安装或部署这个 Agent？
先安装 Pi coding agent 与 npm。执行 pi install npm:pi-mcp-adapter，然后重启 Pi。若已有项目配置，在项目根目录创建或保留 .mcp.json，例如：{"mcpServers":{"chrome-devtools":{"command":"npx","args":["-y","[email protected]"]}}}。没有标准 MCP 配置时，可在安装后运行 /mcp setup，或执行 pi-mcp-adapter init 扫描宿主配置并添加兼容导入。HTTP OAuth 服务还需要服务端对应的 OAuth 配置和可用的操作系统凭据存储。
如何使用这个 Agent？
启动 Pi 后，先调用 mcp({ search: "screenshot" }) 查找工具；再用 mcp({ describe: "chrome_devtools_take_screenshot" }) 查看参数；最后调用 mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })。使用 /mcp 查看服务器状态并切换 direct/proxy 工具，使用 /mcp reconnect <server> 刷新某台服务器。多步工作可调用默认启用的 mcpScript，在其中使用 await tools.search(...)、await tools.describe(...) 与 await tools.call(...)。如需远程 OAuth，先执行 mcp({ action: "auth-start", server: "linear-server" })，在浏览器授权后将回调 URL 通过 mcp({ action: "auth-complete", server: "linear-server", args: { redirectUrl: "..." } }) 交回同一 Pi 会话。