Pi MCP Adapter

Pi MCP适配器

使用MCP服务器 π 而无需燃烧上下文窗口。

https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a

为什么存在

马里奥写道 为什么你可能不需要MCP问题：工具定义过于冗长。一台MCP服务器可以燃烧10000多个令牌，无论你是否使用这些工具，你都要为此付出代价。连接几台服务器，在对话开始之前，你已经烧毁了一半的上下文窗口。

他的观点是：完全跳过MCP，编写简单的CLI工具。

但MCP生态系统有一些有用的东西——数据库、浏览器、API。此适配器使您可以访问而不会膨胀。一个代理工具（约200个令牌），而不是数百个。代理按需发现它需要什么。服务器只有在您实际使用时才会启动。

安装

pi install npm:pi-mcp-adapter

安装后重新启动Pi。

第一次跑步会发生什么

适配器自动读取标准MCP文件。如果您已经拥有它们，则不需要额外的设置。

如果你喜欢终端，你也可以运行 pi-mcp-adapter init 安装后，扫描特定于主机的配置，并将缺少的兼容性导入添加到Pi代理目录中(~/.pi/agent/mcp.json 默认情况下，或 $PI_CODING_AGENT_DIR/mcp.json 设置时）。

快速开始

首选项目配置： .mcp.json

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

首选用户全局共享配置： ~/.config/mcp/mcp.json

Pi还会读取Pi拥有的覆盖文件，以获取设置和特定于主机的兼容性：

• `

/mcp.json --Pi全局覆盖(~/.pi/agent/mcp.json` 默认情况下）

• .pi/mcp.json --Pi项目覆盖

优先级为：

1. ~/.config/mcp/mcp.json
2. `

/mcp.json`

1. .mcp.json
2. .pi/mcp.json

服务器是 默认情况下懒惰 --在你真正调用他们的工具之前，他们不会连接。适配器缓存工具元数据，以便在没有实时连接的情况下搜索和描述工作。

mcp({ search: "screenshot" })

chrome_devtools_take_screenshot
  Take a screenshot of the page or element.

  Parameters:
    format (enum: "png", "jpeg", "webp") [default: "png"]
    fullPage (boolean) - Full page instead of viewport

mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png"}' })

注： args 是JSON字符串，不是对象。

两个调用而不是26个工具扰乱了上下文。

配置

文件布局

当您希望一个设置跨主机工作时，使用共享的MCP文件，当您需要Pi特定的覆盖或设置时，使用Pi拥有的文件。

当Pi需要持久化仅适配器设置时，Pi特定的文件是导入或共享全局服务器的写入目标，例如 directTools.

服务器选项

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    }
  }
}

生命周期模式

• lazy （默认）--启动时不连接。在第一次工具调用时连接。空闲超时后断开连接。缓存的元数据使搜索/列表在没有连接的情况下正常工作。
• eager --启动时连接，但如果连接断开，则不要自动重新连接。默认情况下没有空闲超时（设置 idleTimeout 明确启用）。
• keep-alive --启动时连接。通过健康检查自动重新连接。无空闲超时。用于您始终需要可用的服务器。

设置

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10
  },
  "mcpServers": { }
}

每台服务器 idleTimeout 覆盖全局设置。

直接工具

默认情况下，所有MCP工具都可以通过单个 mcp 代理工具。这使得上下文保持较小，但意味着LLM必须通过代理搜索来发现MCP工具。如果你想让特定的工具直接显示在代理的工具列表中——旁边 read, bash, edit等等。--添加 directTools 到你的配置。

每台服务器：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": true
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    },
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp@latest"]
    }
  }
}

要为所有服务器设置全局默认值，请执行以下操作：

{
  "settings": {
    "directTools": true
  },
  "mcpServers": {
    "huge-server": {
      "directTools": false
    }
  }
}

每台服务器 directTools 覆盖全局设置。上面的示例为每个服务器注册了直接工具，除了 huge-server.

在使用时排除特定工具 directTools: true，添加 excludeTools 在服务器上：

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "directTools": true,
      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
    }
  }
}

excludeTools 过滤直接工具、代理搜索/列表/描述以及 /mcp 面板视图。

每个直接工具在系统提示（名称+描述+模式）中花费约150-300个令牌。适合5-20个工具的目标集。对于具有75个以上工具的服务器，请坚持使用代理或使用 string[].

直接工具从Pi代理目录中的元数据缓存中注册(~/.pi/agent/mcp-cache.json 默认情况下，或 $PI_CODING_AGENT_DIR/mcp-cache.json 设置时），因此启动时不需要服务器连接。添加后的第一个会话 directTools 对于新服务器，缓存还不存在——工具只能回退到代理，缓存在后台填充。要强制执行： /mcp reconnect .

当您更改直接工具时，会切换到 /mcp 或通过编写新配置 /mcp setup，扩展会自动触发Pi的正常重载流。这可以一次性刷新扩展、提示、技能和MCP工具注册，因此新配置的直接工具可以在不手动重新启动的情况下出现。

交互式配置： 跑 /mcp 打开一个交互式面板，显示所有服务器的连接状态、工具和直接/代理切换。您可以从同一覆盖层重新连接服务器并在直接和代理之间切换工具。对于OAuth，在需要身份验证的服务器上按Enter键，或 ctrl+a 在任何OAuth服务器上。

引导式首次运行设置： 跑 /mcp setup 检查检测到的共享MCP文件，采用来自其他主机的兼容性导入，打开发现的配置路径，预览文件写入前后的确切差异，构建一个最小的项目 .mcp.json，或将RepoPrompt快速添加到标准/共享MCP文件中。

子代理集成： 如果您使用子代理扩展，代理可以在其前端请求直接MCP工具 mcp:server-name 语法。有关详细信息，请参阅子代理README。

MCP UI集成

它是如何工作的：

1. 代理调用了一个类似的工具 launch_dashboard
2. 该工具的元数据包括 _meta.ui.resourceUri 指向UI资源
3. pi-mcp适配器获取UI HTML并在iframe中打开它
4. UI可以调用MCP工具并将消息发送回代理

原生渲染： 在macOS上，如果 一瞥 已安装(pi install npm:glimpseui)，UI在本机WKWebView窗口中打开，而不是在浏览器选项卡中打开。设置 MCP_UI_VIEWER=browser 强制浏览器，或 MCP_UI_VIEWER=glimpse 需要本地渲染。

双向沟通： UI进行了回应。当它发送提示或意图时，消息会被存储并 triggerTurn() 唤醒代理人。代理通过以下方式检索消息 mcp({ action: "ui-messages" }) 并做出响应，实现应用程序和代理实时协作的对话式UI。

会话重用： 当代理在其UI已打开的情况下再次调用同一工具时，适配器会将新结果推送到现有窗口，而不是替换它。这启用了实时更新——代理可以优化图表、添加数据或响应用户输入，而不会丢失当前视图。不同的工具仍然像以前一样取代了会话。

来自UI的消息类型：

正在检索UI消息：

mcp({ action: "ui-messages" })

返回UI会话中累积的消息。每条消息包括 type, sessionId, serverName, toolName，以及 timestamp提示信息包括 prompt，意图信息包括 intent 和 params.

浏览器控件：

• Cmd/Ctrl+Enter --完成并关闭
• 逃脱 --取消并关闭
• 完成/取消按钮 --与键盘快捷键相同

技术说明：

• 工具同意检查UI是否可以调用MCP工具（从不/每台服务器一次/始终）
• 适用于stdio和HTTP MCP服务器
• 浏览器使用本地408KB AppBridge捆绑包（MCP SDK+Zod）↔服务器通信

本地示例：交互式可视化工具

一个最小的MCP UI示例 examples/interactive-visualizer 演示图表、双向消息传递和流媒体。从该目录：

npm install
npm run build
npm run install-local

重新启动pi，然后让代理显示一个图表——它调用 show_chart 并在Glimpse（macOS）或浏览器中打开UI。使用 npm run uninstall-local 删除MCP条目。

导入现有配置

共享MCP文件会自动加载。使用 imports 仅适用于尚未涵盖的特定于主机的配置格式 .mcp.json 或 ~/.config/mcp/mcp.json.

{
  "imports": ["cursor", "claude-code", "claude-desktop"],
  "mcpServers": { }
}

支持的兼容性导入： cursor, claude-code, claude-desktop, vscode, windsurf, codex

pi-mcp-adapter init 检测这些特定于主机的配置，并将缺失的导入添加到Pi代理的dir配置中。

项目配置

更喜欢 .mcp.json 用于项目本地共享MCP配置。使用 .pi/mcp.json 仅当您需要特定于Pi的项目覆盖时。项目文件覆盖用户全局共享MCP配置和Pi全局覆盖。

用法

默认情况下，MCP代理和直接工具结果呈现紧凑：长文本显示前三行加上 Ctrl+O to expand 提示，而完整结果在展开时仍然可用，并且仍然原封不动地返回给模型。

搜索包括MCP工具和Pi工具（来自扩展）。Pi工具首先出现在 [pi tool] 前缀。空格分隔的单词是OR’d。

工具名称在连字符和下划线上模糊匹配-- context7_resolve_library_id 发现 context7_resolve-library-id.

命令

如果 settings.autoAuth 是 true, mcp({ connect: ... }), mcp({ tool: ... })，直接工具调用会在需要时自动运行OAuth并重试一次。

在交互式会话中，您还可以通过以下方式进行身份验证 /mcp 随着 ctrl+a 或在需要身份验证的服务器上输入。在非交互式会话中，基于浏览器的OAuth仍然需要 /mcp-auth . /mcp-auth 如果没有服务器，则仅在交互式UI中打开选择器。

运作原理

• 一 mcp 上下文中的工具（约200个令牌），而不是数百个
• 默认情况下，服务器是懒惰的——它们在第一次工具调用时连接，而不是在启动时连接
• 工具元数据已缓存到磁盘，因此在没有实时连接的情况下搜索/列出/描述工作
• 空闲服务器在10分钟后断开连接（可配置），下次使用时自动重新连接
• 基于npx的服务器解析为直接二进制路径，跳过约143 MB的npm父进程
• MCP服务器验证参数，而不是适配器
• 保持活动服务器进行健康检查并自动重新连接
• 可以通过以下方式将特定工具从代理升级为一流的Pi工具 directTools config，因此LLM可以直接看到它们，而不必搜索

局限性

• 跨会话服务器共享尚未实现（每个Pi会话运行自己的服务器进程）
• 紧凑型MCP结果渲染总结了文本，但内联图像仍由Pi的图像显示设置控制，并可能在紧凑型文本摘要下方渲染。
• MCP采样支持仅限于文本；上下文包含、工具、停止序列、音频和图像内容被拒绝，并带有显式错误。