Pi MCP Adapter

在不浪费上下文窗口的前提下，让 Pi 使用 MCP 服务器。

为什么需要它

MCP 的工具定义通常很冗长。单个 MCP 服务器就可能消耗 10k 以上的 token；无论是否真正调用工具，这部分成本都会一直占据上下文。连接多个服务器后，对话甚至还没开始，上下文窗口就可能已经用掉一半。

完全绕开 MCP、为每项能力单独编写 CLI 工具固然轻量，但 MCP 生态中已经存在许多好用的数据库、浏览器和 API 工具。这个适配器用一个约 200 token 的代理工具替代数百个工具定义：智能体按需发现工具，服务器也只在真正使用时启动。

安装

pi install npm:pi-mcp-adapter

安装完成后重启 Pi。

首次运行

适配器会自动读取标准 MCP 配置文件。如果你已经配置过 MCP，通常无需额外设置。

现有配置	Pi 的处理方式
`.mcp.json` 或 `~/.config/mcp/mcp.json`	Pi 立即使用。首次打开 `/mcp` 时会提示检测到的文件，并说明 Pi 只会把适配器专用覆盖项写入自己的文件。
只有 Cursor、Claude Code、Codex 等宿主配置	运行 `/mcp setup`。引导流程会展示检测结果、让你选择导入项，并在写入前预览确切改动。
尚未配置	运行 `/mcp setup` 创建最小化的 `.mcp.json`，添加推荐服务器，或查看本机发现结果。

也可以在终端运行 pi-mcp-adapter init，扫描宿主专用配置，并把缺失的兼容导入添加到 Pi 智能体目录。

快速开始

推荐的项目级配置文件是 .mcp.json：

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

推荐的用户全局共享配置是 ~/.config/mcp/mcp.json。适配器也读取 ~/.agents/mcp.json 与 ~/.agents/mcp/mcp.json。

服务器默认采用懒加载：真正调用某个工具之前不会连接服务器。工具元数据会被缓存，因此搜索和查看说明不依赖实时连接。

配置文件

文件	用途
`~/.config/mcp/mcp.json`	用户全局共享 MCP 配置
`~/.agents/mcp.json`	用户全局、工具无关的 MCP 配置
`.mcp.json`	项目级共享 MCP 配置
`~/.pi/agent/mcp.json`	Pi 全局覆盖与兼容导入
`.pi/mcp.json`	Pi 项目级覆盖，优先级最高

共享 MCP 文件适合跨宿主复用；Pi 自有文件适合保存 directTools 等仅属于适配器的设置。项目配置会覆盖用户全局配置。

使用方式

先搜索需要的工具，再查看或调用它：

mcp({ search: "screenshot" })
mcp({ describe: "chrome_devtools_take_screenshot" })
mcp({
  tool: "chrome_devtools_take_screenshot",
  args: { format: "png" }
})

args 可以是 JSON 对象或 JSON 字符串。通常推荐对象形式；对于需要更简单 schema 的模型，也继续支持字符串形式。

除了工具，适配器还支持 MCP 资源、提示词、服务器说明、OAuth、通知、采样和 MCP Apps。常用工具可以通过 directTools 提升为一等 Pi 工具，让模型直接看到它们。

常用命令

命令	作用
`/mcp`	打开交互面板与首次使用引导
`/mcp setup`	引导创建配置、导入宿主配置或添加推荐服务器
`/mcp tools`	列出所有工具
`/mcp prompts`	列出注册为斜杠命令的 MCP 提示词
`/mcp reconnect [server]`	重新连接全部服务器或指定服务器
`/mcp disable <server>`	通过项目级覆盖禁用服务器
`/mcp enable <server>`	通过项目级覆盖启用服务器
`/mcp-auth <server>`	为指定服务器执行 OAuth 设置

工作原理

上下文中只放一个约 200 token 的 mcp 工具，而不是数百个工具定义。
服务器默认懒加载，第一次调用工具时才连接。
工具元数据缓存在磁盘上，离线状态下仍可搜索、列出和查看说明。
空闲服务器默认 10 分钟后断开，下次使用时自动重连。
基于 npx 的服务器会解析为直接二进制路径，避免额外的 npm 父进程。
参数由 MCP 服务器验证，适配器专注于发现、路由和生命周期管理。

限制

暂未实现跨会话共享服务器；每个 Pi 会话会运行自己的服务器进程。
紧凑结果会摘要文本，但内联图片仍受 Pi 图片显示设置控制。
MCP sampling 目前只支持文本；上下文包含、工具、停止序列、音频和图片内容会被明确拒绝。

本页依据 pi.dev 的包详情与项目 README 翻译整理。

查看英文原页 ↗