Pi MCP 上下文适配器
让 Pi 按需使用 MCP 服务器，避免工具定义占满上下文。
按维度查看评分与理由
证据显示：适配器默认惰性连接，避免不必要的服务器启动；提供审批工具（approveTools）和用户确认机制；数据流透明性通过状态快照和跟踪选项体现；敏感数据处理包括OAuth凭据存储在操作系统凭据库，且失败时关闭而非降级；依赖安全方面，依赖列表包含已知包，但未提供漏洞扫描或锁定文件证据；外部影响方面，适配器不自动启动或停止外部守护进程，但会启动MCP服务器进程；回滚方面，提供禁用/启用命令，但未提供完整回滚机制；来源归属方面，作者身份明确，但发布者未验证。扣分原因：依赖安全缺乏具体证据，回滚机制不完整，来源归属因发布者未验证而受限。
证据显示：文档和配置描述一致，自洽性良好；依赖项在package.json中明确列出，但未验证可用性；失败消息方面，文档描述了错误处理，但未提供具体示例。扣分原因：依赖可用性未验证，失败消息缺乏具体示例。
证据显示：面向Pi编码代理用户，场景包括本地和远程OAuth；能力边界明确，如不支持某些功能；触发精度通过工具前缀和审批模式控制；环境适配包括多种配置文件和平台支持。扣分原因：环境适配未覆盖所有平台，触发精度依赖用户配置。
证据显示：信息架构清晰，README详细；安装说明明确；命名稳定，版本号明确；示例和FAQ存在；已知限制部分列出；许可证为MIT；版本变更日志存在；维护责任由作者承担，但发布者未验证。扣分原因：维护责任因发布者未验证而受限。
证据显示：输出可用性通过工具元数据缓存和状态快照提升；边际价值在于减少上下文窗口消耗；成本效益通过惰性连接和按需启动体现。扣分原因：未提供性能基准或实际使用数据。
证据显示：README中的声明与代码结构一致，但未提供独立验证；跨来源佐证有限，主要依赖单一仓库；事实与推断分离不明确。扣分原因：缺乏独立验证和跨来源佐证。
- 发布者身份未验证，需谨慎评估供应链风险。
- 依赖安全未提供漏洞扫描或锁定文件证据，建议检查依赖版本。
- 回滚机制不完整，仅提供禁用/启用，无完整回滚。
- 远程OAuth流程涉及敏感信息，需确保使用安全环境。
这个 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 会话。
常见问题
它会在 Pi 启动时启动所有 MCP 服务器吗？
是否需要把所有 MCP 工具都放进模型的工具列表？
MCP 服务的密钥和 OAuth 令牌如何处理？
能否使用现有 Claude Code 或 Codex 的 MCP 配置？
/mcp setup 或 pi-mcp-adapter init 显式采用兼容配置；默认不会自动加载宿主专属配置。