mcp@earendil-works/pi-mcp

要点Key points

• 最大的文件是 client.ts；其次是 transports/streamable-http.ts——HTTP 传输要处理会话、SSE 解析、认证重试和断线续传。The largest file is client.ts, followed by transports/streamable-http.ts — the HTTP transport handles sessions, SSE parsing, auth retries and stream resumption.
• 客户端只依赖 McpTransport 接口：start / send / close 加三个监听（message、error、close）。换传输不用改客户端。The client depends only on the McpTransport interface: start / send / close plus three listeners (message, error, close). Swapping transports never touches the client.
• 认证通过一个很小的 AuthProvider 接口注入：token() 与可选的 onUnauthorized()。OAuth 只是它的一种实现（adaptOAuthProvider）。Auth is injected through a tiny AuthProvider interface: token() and an optional onUnauthorized(). OAuth is just one implementation of it (adaptOAuthProvider).

工作原理How it works

1. 创建 StdioTransport({ command, args }) 或 StreamableHttpTransport({ url, authProvider })。Create a StdioTransport({ command, args }) or a StreamableHttpTransport({ url, authProvider }).
2. new McpClient({ name, version })，再 await client.connect(transport)。new McpClient({ name, version }), then await client.connect(transport).
3. listTools() / callTool() / readResource()；把结果交给 toLlmContent() 变成模型能读的内容。listTools() / callTool() / readResource(); pass results to toLlmContent() to get model-ready content.

要点Key points

• 支持的版本：2025-11-25、2025-06-18、2025-03-26、2024-11-05。服务器选了别的版本时连接直接失败，而不是“尽量兼容”。Supported versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. A server that picks another version fails the connection outright instead of a best-effort fallback.
• 协商出的版本通过 setProtocolVersion() 交给传输：HTTP 传输此后在每个请求上带 MCP-Protocol-Version 头。The negotiated version goes to the transport via setProtocolVersion(): from then on the HTTP transport sends an MCP-Protocol-Version header on every request.
• 配置了 roots 时自动声明 roots 能力，并响应服务器的 roots/list 请求；ping 永远内置。With a roots option the roots capability is declared automatically and the server's roots/list requests are answered; ping is always built in.
• 握手结果保存在 serverInfo、serverCapabilities、instructions 与 protocolVersion 上，供宿主展示或决策。Handshake results are kept on serverInfo, serverCapabilities, instructions and protocolVersion for the host to show or act on.

工作原理How it works

1. 订阅传输的 message / error / close；传输错误只上报，真正让请求失败的是传输关闭。Subscribe to the transport's message / error / close; transport errors are only reported — what fails requests is the transport closing.
2. transport.start() → initialize 请求（不可取消）→ validateInitializeResult() → 版本检查。transport.start() → the initialize request (not cancellable) → validateInitializeResult() → version check.
3. setProtocolVersion?.(v) → notifications/initialized → state = "connected"。setProtocolVersion?.(v) → notifications/initialized → state = "connected".

要点Key points

• 传了 onProgress 时，请求的 _meta.progressToken 就是它的 id；每条 notifications/progress 都会重新计时——持续报进度的长任务不会超时。With onProgress, the request's _meta.progressToken is its id; every notifications/progress re-arms the timeout — long tasks that keep reporting never time out.
• initialize 例外：规范禁止取消它，所以中止或超时只在本地 reject。initialize is the exception: the spec forbids cancelling it, so an abort or timeout only rejects locally.
• 没有处理器的服务器请求得到 -32601 Method not found；处理器抛出 McpError 时原样返回 code 与 data，其他异常变成 -32603。Server requests without a handler get -32601 Method not found; a handler that throws McpError returns its code and data as is, any other exception becomes -32603.
• listTools() 等方法跟着 nextCursor 自动翻页：重复的 cursor 抛错，最多 1,000 页。listTools() and friends follow nextCursor automatically: a repeated cursor throws, and there are at most 1,000 pages.

工作原理How it works

1. request(method, params, { signal, timeoutMs, onProgress }) → requestInternal()。request(method, params, { signal, timeoutMs, onProgress }) → requestInternal().
2. pending.set(id, entry) → armTimeout() → transport.send()；发送失败立即 reject。pending.set(id, entry) → armTimeout() → transport.send(); a failed send rejects at once.
3. handleMessage() 按响应 / 请求 / 通知分派；handleResponse() 删除 pending 并 resolve 或 reject McpError。handleMessage() dispatches responses / requests / notifications; handleResponse() removes the pending entry and resolves or rejects with McpError.

要点Key points

• 用进程组是为了 npx、uvx 这类包装命令：只杀包装进程会留下真正的服务器。Windows 上改用 taskkill /T /F。Process groups exist for wrapper commands such as npx and uvx: killing only the wrapper would leave the real server running. Windows uses taskkill /T /F instead.
• 宿主进程退出时，退出钩子对所有仍存活的进程组发 SIGTERM——即使宿主忘了关闭传输。When the host exits, an exit hook SIGTERMs every live process group — even if the host forgot to close the transport.
• stdout 按 0x0a 切分；单行超过 16 MiB 丢弃并报错；stderr 只保留最后 64 KiB，同时回调 onStderr。stdout is split at 0x0a; a line over 16 MiB is dropped with an error; stderr keeps only its last 64 KiB and also goes to onStderr.
• 默认继承宿主的环境变量再叠加 env；inheritEnv: false 时只用 env。By default the host's environment is inherited and env layered on top; inheritEnv: false uses env alone.

工作原理How it works

1. start()：crossSpawn() → 登记进程组 → 等待 spawn 或 error 事件。start(): crossSpawn() → register the process group → wait for spawn or error.
2. send()：写入 JSON.stringify(message) + "\n"。send(): write JSON.stringify(message) + "\n".
3. close()：stdin.end() → SIGTERM（宽限期后）→ SIGKILL（closeTimeoutMs 后）；子进程 close 后再对进程组补一次 SIGTERM。close(): stdin.end() → SIGTERM (after the grace period) → SIGKILL (after closeTimeoutMs); after the child closes, the group gets one more SIGTERM.

要点Key points

• 会话：服务器在响应头里给出 Mcp-Session-Id，之后每个请求都带上；带着会话 id 收到 404 → McpSessionExpiredError。Sessions: the server returns Mcp-Session-Id in a response header and every later request carries it; a 404 with a session id → McpSessionExpiredError.
• 401（或 403 且 error="insufficient_scope"）先交给 authProvider.onUnauthorized() 一次，然后用新凭据重发；仍失败就抛 McpAuthRequiredError。A 401 (or a 403 with error="insufficient_scope") goes to authProvider.onUnauthorized() once, then the request is retried with the new credentials; if it still fails, McpAuthRequiredError is thrown.
• 重试只针对 408、429、5xx 与网络错误；认证、会话和协议错误不重试。响应流无法续传时，只为那一个请求合成一条 -32603 错误响应。Only 408, 429, 5xx and network errors are retried; auth, session and protocol errors are not. When a response stream cannot resume, a synthetic -32603 error response fails just that one request.
• close() 带会话 id 发 DELETE（1 秒超时，复用最后一个 token，不触发刷新）。close() sends DELETE with the session id (1-second timeout, reusing the last token so no refresh is triggered).

工作原理How it works

1. send()：authorizedFetch("POST") → checkResponse() → captureSession() → 按消息类型和 Content-Type 分支。send(): authorizedFetch("POST") → checkResponse() → captureSession() → branch on message kind and Content-Type.
2. consumeSseStream() 解析 data: / event: / id: / retry:，单个事件同样限制在 16 MiB。consumeSseStream() parses data: / event: / id: / retry:; a single event is capped at 16 MiB too.
3. runGetStream() 循环：openSseStream(lastEventId)（405 = 服务器不提供）→ 读到断开 → reconnectDelay() → 重连。runGetStream() loops: openSseStream(lastEventId) (405 = server offers none) → read until it drops → reconnectDelay() → reconnect.

要点Key points

• adaptOAuthProvider() 把它包装成传输用的 AuthProvider：并发的 401 共用一次授权；如果出错请求用的 token 已经被别人换掉了，就直接重试——轮换的 refresh token 不能用两次。adaptOAuthProvider() wraps it as the transport's AuthProvider: concurrent 401s share one authorization; if the failing request's token was already replaced, it simply retries — a rotating refresh token cannot be used twice.
• 403 insufficient_scope 是 step-up：跳过刷新，请求“已授予 ∪ 挑战要求”的 scope。A 403 insufficient_scope is a step-up: refresh is skipped and the scope requested is “granted ∪ challenged”.
• 出错恢复：invalid_client / unauthorized_client 清空所有凭据重来一次；invalid_grant 只清令牌重来一次。Recovery: invalid_client / unauthorized_client wipe all credentials and rerun once; invalid_grant wipes the tokens only and reruns once.
• 安全检查：授权服务器必须支持 PKCE S256；带 code 回来时校验 iss（RFC 9207）；protected resource 必须与服务器 URL 匹配；状态按精确的 serverUrl 存取。Safety checks: the authorization server must support PKCE S256; iss is checked when a code comes back (RFC 9207); the protected resource must match the server URL; state is stored per exact serverUrl.

工作原理How it works

1. 宿主实现或使用 McpOAuthProvider（可注入持久化的 McpOAuthStateStore）。The host implements or uses McpOAuthProvider (optionally with a persistent McpOAuthStateStore).
2. 传输里用 adaptOAuthProvider(provider)；需要用户登录时请求以 McpOAuthAuthorizationRequiredError 失败。Use adaptOAuthProvider(provider) in the transport; when the user must sign in, requests fail with McpOAuthAuthorizationRequiredError.
3. 登录：OAuthCallbackServer.listen() → authorizeMcp() 返回 "REDIRECT" 并打开浏览器 → 拿到回调 → 带 authorizationCode 再调一次 authorizeMcp()。Sign-in: OAuthCallbackServer.listen() → authorizeMcp() returns "REDIRECT" and opens the browser → receive the callback → call authorizeMcp() again with authorizationCode.

要点Key points

• LlmContent 的形状与 pi-ai 的 TextContent / ImageContent 一致，但 pi-mcp 并不依赖 pi-ai。LlmContent has the same shape as pi-ai's TextContent / ImageContent, yet pi-mcp does not depend on pi-ai.
• 错误按类型区分：超时、中止、连接关闭、HTTP 状态（及其两个子类：需要认证、会话过期）与需要登录。除这两个子类外都直接继承 Error。Errors are told apart by type: timeouts, aborts, closed connections, HTTP statuses (with two subclasses: auth required and session expired) and required sign-in. Apart from those two subclasses, all extend Error directly.
• McpError 携带 JSON-RPC 的 code 与 data，处理器抛出它可以向服务器返回任意错误码。McpError carries the JSON-RPC code and data; a handler that throws it can return any error code to the server.

工作原理How it works

1. callTool() 校验结果形状，缺失的 content 补成 []。callTool() validates the result shape and defaults a missing content to [].
2. toLlmContent(result) 逐块转换；isError 由调用方自行决定如何呈现。toLlmContent(result) converts block by block; how to present isError is up to the caller.
3. 用 instanceof 区分错误：例如 McpSessionExpiredError 时重新连接。Tell errors apart with instanceof: e.g. reconnect on McpSessionExpiredError.

要点Key points

• 四种 exposure：codemode（默认）、deferred（tool_search 加载后才声明）、direct（立即声明）、hidden；toolExposure 可以按工具覆盖。Four exposures: codemode (default), deferred (declared once tool_search loads them), direct (declared right away) and hidden; toolExposure overrides per tool.
• 项目的 mcp.json 不能设置 auth——仓库不能决定凭据发往哪里。只写 enabled / exposure 的项目条目只覆盖全局同名服务器的这几项。A project mcp.json cannot set auth — a repository must not choose where credentials go. A project entry with only enabled / exposure just overrides those fields of the global server of the same name.
• 连接从不自己弹浏览器：只用存下的 token 和 refresh token；需要登录时在 /mcp 中完成，凭据存在 <agent-dir>/mcp-auth.json。Connections never open a browser on their own: they use the stored token and refresh token; sign-in happens in /mcp, and credentials live in <agent-dir>/mcp-auth.json.
• 每次 MCP 调用都走 pi 的工具管线，tool_call / tool_result 钩子和权限扩展照常生效。Every MCP call runs through pi's tool pipeline, so tool_call / tool_result hooks and permission extensions apply as usual.

工作原理How it works

1. loadMcpConfig()：全局 mcp.json → 受信任项目的 .pi/mcp.json → 合并与校验。loadMcpConfig(): global mcp.json → the trusted project's .pi/mcp.json → merge and validate.
2. runtime.ts：有 command → StdioTransport，有 url → StreamableHttpTransport；new McpClient() 并 connect()。runtime.ts: command → StdioTransport, url → StreamableHttpTransport; new McpClient() and connect().
3. createMcpToolName() 生成工具名（超过 64 字符或冲突时加 8 位哈希）；资源通过 list_mcp_resources 等 3 个工具访问。createMcpToolName() builds tool names (an 8-hex hash suffix when longer than 64 characters or clashing); resources go through list_mcp_resources and two other tools.