MCP 与 codemode —— 接别人的工具,写自己的脚本
F06 造的工具只在你自己机器上。这一章接别人的:一次 pi mcp add,
就有了社区里几百台服务器的能力。但「接上」和「用上」之间隔着
一个很别扭的事实——MCP 工具默认不声明给模型。
三个问题:
- 默认
codemode暴露下,模型怎么知道有这台服务器? pi mcp add写进哪个文件,-l又写到哪,谁能读到?codemode那段 JS 的沙箱边界到底在哪——哪些能做,哪些一定不行?
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):
{ "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 或脚本里跑:
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .pi mcp listlist 会真的连接每一台启用的服务器,打印状态、工具和错误;
有配置无效或有启用的服务器没连上,退出码是 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 |
三件容易忽略的事:
- 工具调用是真实的。脚本失败前已经执行的调用不会回滚(
codemode.md:18)。 - 结果形状取决于工具。声明了
outputSchema的返回结构化值——bash返回{ output, truncated, exit_code, wall_time_seconds }(codemode.md:43), 因此脚本能直接判断退出码,不用正则解析输出。MCP 工具返回完整的CallToolResult。 - 失败用 reject。失败、被拦、参数非法都会抛出带工具错误文本的
Error, 所以批量调用要用Promise.allSettled保住成功的那些(codemode.md:48)。
6.1 @options 必须是第一行
// @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:先看清默认暴露下模型到底知道什么。
$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/ 而不是随便一个目录。