Pi Agent 源码级教程
F07

MCP 与 codemode —— 接别人的工具,写自己的脚本

2,816 字 · 含 14 行代码 · 约 19 分钟

F06 造的工具只在你自己机器上。这一章接别人的:一次 pi mcp add, 就有了社区里几百台服务器的能力。但「接上」和「用上」之间隔着 一个很别扭的事实——MCP 工具默认不声明给模型。

三个问题:

  1. 默认 codemode 暴露下,模型怎么知道有这台服务器?
  2. pi mcp add 写进哪个文件,-l 又写到哪,谁能读到?
  3. codemode 那段 JS 的沙箱边界到底在哪——哪些能做,哪些一定不行?
text
   mcp.json ──> 连接 ──> 工具注册为 mcp__server__tool                              |                    +---------+---------+                    |         |         |                 direct   codemode  deferred    hidden                    |         |         |             声明给模型   只有脚本能调  tool_search 找到才声明                    |         |         |                    +----> 都走同一条 tool_call 管线 <----+

<sub>五档里的三档在 MCP 这里各有一个名字,hidden 是第四档:注册了谁都够不着。</sub>


一、两台文件,一条信任闸门

loadMcpConfig(src/extensions/mcp/config.ts:146-157)只读两个位置:

位置 何时读 谁改
~/.pi/agent/mcp.json 总是 pi mcp add(默认)、/mcp
<项目>/.pi/mcp.json 项目受信任时(:149) pi mcp add -l、/mcp 的「本项目中启用」

项目条目会整体替换同名全局条目(config.ts:5-7 的注释)。 但有个例外值得记住——项目里只写覆盖键的条目,不算定义,只改三个字段 (ENABLED / EXPOSURE / TOOL_EXPOSURE,config.ts:75):

json
{ "mcpServers": { "internal-tools": { "enabled": false } } }

isOverride(config.ts:78-80)的判断就是「没有 command、url、type」。 于是「这个项目里关掉某台全局服务器」只要一行,不用把 env 和密钥复制过来。 覆盖键之外多写一个字段会直接报错(:114-115),不会被默默忽略。

还有一条安全边界:auth(借用 /login 的 provider 令牌)只允许写在全局文件里 (config.ts:134-137)。理由写在 mcp-servers.ts:156-157:否则一个仓库 就能决定你的凭据发到哪个地址去。


二、mcp.json 的字段

两种传输共用一组基础字段(core/mcp-servers.ts:59-78):

字段 默认 作用
exposure codemode 见第四节
toolExposure — 逐工具覆盖,键支持 * 通配
enabled true 设 false 保留条目但不连接
timeout 60 秒 单次请求超时,服务器的进度通知会重置它
description — 一句话说明,进系统提示词的 mcp_servers 段

description 值得单独说。renderServersSection(mcp/index.ts:195-221) 决定模型能不能看到这台服务器;它取的就是 description 的第一行 (serverSummary,:185-188),没配才退回到连接后拿到的服务器说明首行。 不写这一句,模型对这台服务器的全部认知就是「有个名字」。

stdio 额外收 command / args / env / cwd,HTTP 额外收 url / headers / oauth。 三个校验细节容易踩:

  • command 是一个可执行文件,args 是它自己的参数,不是 shell 字符串(mcp.md:80)。
  • sse 被显式拒绝(mcp-servers.ts:282),只支持 streamable HTTP。
  • env 和 headers 的值支持 ${NAME} 和 !command, 但 !command 必须占满整个值(mcp.md:81),"Bearer $(gh auth token)" 这种拼法不成立。

三、先用 pi mcp list 看病

pi mcp 这组命令不加载扩展,也不开会话(cli.ts:41-42),所以可以在 CI 或脚本里跑:

powershell
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .pi mcp list

list 会真的连接每一台启用的服务器,打印状态、工具和错误; 有配置无效或有启用的服务器没连上,退出码是 1(cli.md:337)。 这一条让它能当健康检查用。

add 的完整开关在 cli.ts:54-71,本章只挑几个用得上的:

开关 作用
-l / --local 写项目 .pi/mcp.json 而不是全局
--exposure <mode> codemode(默认)/ deferred / direct / hidden
--description <text> 就是上一节那个「一句话」
--bearer-token-env-var NAME 展开成 Authorization: Bearer ${NAME}
--oauth-client-registration auto / cimd / dcr,见第七节

add 不会连接,所以命令成功不代表服务器能用——紧跟一条 pi mcp list。 会话里改了配置要 /reload(mcp.md:28),这是 F01 那条老规矩。


四、codemode 暴露下的三段接力

这是全章最需要想清楚的一段。默认 exposure: "codemode" 时,工具 既不声明给模型,也不列在 codemode 的说明书里(mcp.md:197)。 三个环节各补一块:

第一段:系统提示词的 mcp_servers 段。 MCP_SERVERS_SECTION(mcp/index.ts:156) 只收「有 codemode 或 deferred 工具」的启用服务器(:195-199), 写一行 - mcp__server (codemode): 描述。模型由此知道这台服务器存在。 整段有 4096 字符上限(:163),放不下的服务器被折叠成一行计数(:205-206)。

第二段::206 的开关。 有 codemode 服务器连着时,ensureDiscoveryActive (:501-536)自动激活 codemode 工具;deferred 服务器则激活 tool_search。 不想自动开,在 mcp.json 顶层写 "autoEnableCodemode": false(config.ts:28-29)。 两个都没激活时它会弹一次警告——因为工具确实成了够不着的摆设(:529-535)。

第三段:脚本里的 searchTools()。 模型知道有服务器,但不知道有哪些工具, 所以得让它在脚本里搜:

全局 拿到什么
ALL_TOOLS 所有可调工具,{ name, description } 数组
searchTools(query) BM25 排序,默认 8 条,可带 namespace 过滤
describeTool(name) 单个工具的说明 + TypeScript 声明
describeNamespace(name) 整个命名空间:说明、服务器 instructions、工具名

describeNamespace("mcp__github") 是唯一能读到服务器 instructions 的入口—— 服务器说明书不进任何工具描述(mcp.md:236)。


五、五档暴露在 MCP 里的具体差别

McpExposure(mcp-servers.ts:52)和扩展的 ToolExposure 不是同一套词, toToolExposure(mcp/tools.ts:44-46)做了映射:MCP 的 codemode 落到扩展的 deferred。 理由是两者对模型的可见性相同,只是「谁来激活」不同。

exposure 模型能直接调 走哪条路 什么时候选
codemode 否 脚本里 tools.mcp__x__y() 默认,工具多、要组合调用
deferred 搜到之后能 tool_search 声明给下一轮 工具少但希望模型直接调
direct 是 和内置工具一样 三五个常用工具
hidden 否 谁也够不着 临时封禁,或配合 toolExposure 白名单

getMcpToolExposure(mcp-servers.ts:246-254)的优先级是 精确名 > 模式(先出现者胜)> 服务器默认。于是「hidden 服务器只放出几个工具」 是合法配置:服务器 hidden,toolExposure 里挑几个标成 direct。

另外两条时间线要注意:

  • 首轮提示词只等 direct 服务器,最多 10 秒(mcp/index.ts:93 的 DEFAULT_STARTUP_WAIT_MS)。 其它服务器连上就加,不影响已经发出的提示词。
  • codemode 的说明书不随 MCP 连接变化,这是刻意的:它按 exposure 列工具而非按连接状态, 所以服务器晚到不会让整段描述重发、缓存全崩(codemode/tool.ts:340-341)。

5.1 长结果被截成三段

MCP 结果超过 20 KB 时(mcp/tools.ts:51 的 MCP_OUTPUT_MAX_BYTES), limitMcpContent(:180-201)保留首尾、挖掉中间,中间换成 …N chars truncated…,全文写进临时文件并在结果里给出路径。

但脚本拿到的是完整结果(mcp/tools.ts:8-10)。这就是 codemode 在 MCP 场景下 最实际的用处:一个 GitHub 搜索接口回 200 KB JSON,走 direct 模型只看到首尾, 走 codemode 却能先在脚本里 filter 出五条,再把五条交给模型。


六、脚本里的世界

codemode 的输入是裸 JavaScript 源码,不是 JSON、不是 Markdown 代码块 (codemode.md:7)。它作为 async 函数体跑在 QuickJS 沙箱里, 所以顶层 await 和 return 都能用。

沙箱边界(codemode.md:7 + tool.ts:118-120):没有 Node API、没有文件系统、 没有网络、没有定时器。出去只有两个口子——tools 和 models。

全局 作用
tools.<name>(args) 调工具;MCP 的 mcp__dev-radius__search 变成 tools.mcp__dev_radius__search
text(v) / image(v) / console.log 加输出
return v 顶层 return 等价于 text(v)
exit() 正常结束
store(k, v) / load(k) 跨调用存小 JSON,见 §6.2

三件容易忽略的事:

  1. 工具调用是真实的。脚本失败前已经执行的调用不会回滚(codemode.md:18)。
  2. 结果形状取决于工具。声明了 outputSchema 的返回结构化值——bash 返回 { output, truncated, exit_code, wall_time_seconds }(codemode.md:43), 因此脚本能直接判断退出码,不用正则解析输出。MCP 工具返回完整的 CallToolResult。
  3. 失败用 reject。失败、被拦、参数非法都会抛出带工具错误文本的 Error, 所以批量调用要用 Promise.allSettled 保住成功的那些(codemode.md:48)。

6.1 @options 必须是第一行

js
// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}

放在别处会在脚本运行前直接失败(codemode.md:9)。max_output_tokens 默认 10000, 超了保留首尾并把全文写临时文件。timeout_ms 默认不设—— 但生成图片的脚本千万别设短,一次可能要几分钟(:16)。

6.2 store() 跟着分支走

store 的写入只在脚本成功时保留,并且每次成功写入都会往会话里追加一条 codemode-store 自定义条目(tool.ts:41-47、codemode.md:56)。 于是 /tree 分叉之后,每个分支只看到自己路径上的写入。

这和 F06 里 todo.ts 把状态塞进 details 是同一个思想: 状态存在历史里,历史会自动分叉。单值上限 262144 字符、总量 1048576 (packages/codemode/src/runtime/prelude-source.ts:34-35),所以只适合 存游标、ID、摘要这类东西。


七、OAuth:让服务器相信你

远程服务器回 401 时,/mcp 会显示需要登录。三种触发方式: /mcp 里选 Sign in、/mcp login sentry、pi mcp login sentry(mcp.md:127)。 令牌落在 ~/.pi/agent/mcp-auth.json,过期或被拒时自动刷新。

三条实践里最常撞上的坑:

  • clientRegistration 默认 auto:服务器支持 Client ID Metadata Document 就用 文档(client id 是 https://pi.dev/oauth/client.json),否则动态注册。 授权页报「invalid client」时改成 "dcr" 强制动态注册(mcp.md:164-172)。
  • clientName 只影响注册。有些服务器(比如 Figma)只认已知客户端, 填 "Claude Code" 能过(mcp.md:150-160)——这是兼容性手段,不是身份伪造。
  • callbackUrl 只能是回环地址,且不能带 query 和 fragment(mcp-servers.ts:133-137)。

SSH 场景下浏览器在另一台机器上,登录界面接受粘贴回调 URL(mcp.md:127)。


八、MCP 工具和扩展走同一条管线

mcp.md:254 一句话说完了:每次 MCP 调用都过 Pi 的工具管线。 所以 F05 写的 tool_call 拦截、permission-gate 那种权限扩展, 对 MCP 工具一视同仁;脚本里发起的调用带 parentToolCallId,能溯源到是哪段脚本。

想按服务器声明的语义做判断,用 pi.getAllTools() 读注解 (readOnlyHint / destructiveHint / idempotentHint / openWorldHint, mcp/tools.ts:300-310)。只读工具放行、破坏性工具要确认,就是这么写的。

8.1 替换内置 MCP

装了 pi-mcp-adapter 这类扩展并注册了 /mcp 时,内置 MCP 对会话让位 (mcp.md:268)。不想装扩展也能关:pi config 里关掉 Built-in 的 mcp, 或写 "extensions": ["-builtin:mcp"]。临时关一次用 --no-mcp。

但注意 pi mcp 那组 shell 命令永远用内置实现(mcp.md:270), 它看不见扩展注册的服务器。


九、自己动手验证

实验 1:先看清默认暴露下模型到底知道什么。

powershell
$env:PI_OFFLINE="1"; pi --mode json -p "x" > t.jsonl

取 system 消息的 sections,看有没有 mcp_servers 这个键。 没接服务器时它不存在;接上一台 codemode 服务器后才会出现, 内容只有一行 - mcp__xxx (codemode): 描述,看不到任何工具名。

实验 2:同一台服务器换三种暴露,看提示词怎么变。

对同一台服务器分别用 --exposure codemode / deferred / direct 加进去, 每次都跑一遍实验 1:

暴露 sections.mcp_servers sections.tools
codemode 有 无对应工具
deferred 有 无(要 tool_search 才出现)
direct 无 有,形如 mcp__server__tool

这张表比任何文档都直观:direct 是唯一让工具「真的出现」的档。

实验 3:给 codemode 一个任务,看它怎么写脚本。

开 codemode(--tools +codemode),然后让它「用 github 服务器搜最近的 issue, 只要标题和编号」。看它第一步是不是调 searchTools 或 describeNamespace—— 那就是 §四第三段在起作用。

改一处试试

在 mcp.json 里加 "timeout": 10,接一台慢服务器,pi mcp list 看它超时的报错长什么样。 默认 60 秒太长,10 秒能让你在一次咖啡时间内看清「超时」和「连不上」的区别—— 这两类错误在 list 的输出里是不同的字段。


十、工程暗坑

坑一:以为 pi mcp add 失败是配置错了。 多半是命令本身跑不起来(npx 找不到包)。add 不连接,错要到 list 才暴露。

坑二:把 env 的 ${TOKEN} 当成 shell 展开。 Pi 自己展开它,不经过 shell。用 !command 取令牌时必须占满整个值, "Bearer ${X}" 合法而 "Bearer !gh auth token" 非法。

坑三:服务器名里有大写或点。 SERVER_NAME(mcp-servers.ts:164)只允许字母、数字、_、-。 而且 dev-radius 和 dev_radius 会被当成同一台服务器,第二个直接报冲突(config.ts:129-133)。

坑四:工具太多直接把 direct 全开。 每台 direct 服务器都让首轮提示词多等最多 10 秒,工具还全会进 sections.tools。 几十个工具该走 codemode,让脚本去过滤。

坑五:在项目 mcp.json 里写 auth。 项目文件不能指定「用哪个 provider 的凭据」,写了会被报错跳过—— 这不是 bug,是防止仓库偷令牌。

坑六:脚本里用 text() 打印大段 JSON。 输出上限是 16 MiB / 10 万条(prelude-source.ts:42-43), 但真正的问题是大 JSON 进上下文。脚本的价值就在先把大变小,不是把原件搬给模型。


十一、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/mcp-servers.ts 359 配置类型、validateMcpServerConfig、getMcpToolExposure
packages/coding-agent/src/extensions/mcp/config.ts 244 两台文件、覆盖键、loadMcpConfig
packages/coding-agent/src/extensions/mcp/index.ts 1,348 mcp_servers 段、自动激活、启动等待
packages/coding-agent/src/extensions/mcp/tools.ts 392 工具名生成、20 KB 截断、注解
packages/coding-agent/src/extensions/mcp/cli.ts 626 pi mcp add/list/login 全开关
packages/coding-agent/src/extensions/codemode/tool.ts 435 reachesTools、prepareLoadout、model-only
packages/coding-agent/src/extensions/codemode/execute.ts 851 沙箱、worker 配额、256 MB 堆
packages/codemode/src/runtime/prelude-source.ts 523 store 与输出上限
packages/coding-agent/docs/mcp.md 274 服务器配置与暴露全表
packages/coding-agent/docs/codemode.md 230 脚本 API 参考

十二、下一章

MCP 解决「别人造的工具」,codemode 解决「工具太多怎么编排」。 下一章换到分发侧:你写的扩展、主题、AGENTS.md,怎么打包成一个别人能装的包。 F08 讲 package.json 里的 pi 清单、pi install 的三种来源, 以及为什么主题文件要放在 themes/ 而不是随便一个目录。