nicobailon/pi-mcp-adapter

Token-efficient MCP adapter for Pi coding agent

解决的问题

Pi MCP Adapter 防止 LLM 上下文窗口被冗长的工具定义淹没。在标准的 Model Context Protocol (MCP) 设置中，单个服务器仅用于描述其可用工具就可能消耗数千个 token，无论这些工具是否实际使用，这都会消耗 token。此适配器将数百个单独的工具定义替换为单个代理工具，允许代理按需发现并调用工具。

工作原理

该适配器不是将每个连接的 MCP 服务器的每个工具直接注册到 LLM，而是提供一个单一的 mcp 代理工具。代理使用此代理来搜索特定工具并执行它们。

关键技术特性包括：

  • Lazy Loading：在实际调用工具之前不会连接服务器，从而减少启动开销。
  • Configuration Merging：自动检测并合并来自多个源的配置，包括标准的 .mcp.json 文件和特定于主机的配置（例如来自 Cursor 或 Claude Code 的配置）。
  • Output Guarding：为了防止海量的工具输出撑爆上下文窗口，适配器将文本输出限制在 50 KiB 或 2,000 行，并将过大的结果保存到临时文件中供代理选择性读取。
  • Lifecycle Management：支持包括 lazy、eager、keep-alive 和 lazy-keep-alive 在内的多种连接模式，以优化资源使用。

适用对象

使用 Pi 且希望在不牺牲上下文窗口的情况下集成 MCP 服务器（数据库、浏览器、API）的开发者。

亮点

  • 上下文效率：将工具定义开销从数千个 token 降低到约 200 个 token。
  • 灵活配置：支持项目本地和用户全局的共享 MCP 配置。
  • 安全 OAuth：与操作系统凭据存储集成以进行安全的 token 管理，并支持远程/无头 OAuth 流程。
  • 资源管理：包含“Output Guard”，防止过大的工具响应导致会话崩溃。
  • 按需发现：允许代理通过搜索而不是将所有工具预加载到提示词中来查找工具。