---
name: knowledge-extension-ecosystem-mcp-protocol-runtime
description: >
  覆盖 Session 私有 MCP transport、动态工具与内容目录、Roots、Sampling、Elicitation、
  Completion、Logging、OAuth、异步 Tasks、结果制品和故障恢复。进入条件：新增 MCP
  能力、调试连接或目录变化、处理不可信协议数据、修改 MCP 工具投影或跨端事件。
  不包含：通用工具准入与调度（见 ../../tool-and-automation-platform/）、插件安装和
  来源策略（见 ../plugin-lifecycle-and-marketplace/）。关键词：McpClient、
  McpRegistry、mcp__、tools/list_changed、elicitation、sampling、OAuth、MCP Tasks。
---

## Module Structure

MCP 运行时由每个 `SessionRuntime` 独占：配置先按 source project 合并，Registry 管理
多个 client 的安全投影，动态工具和内容能力再进入该 Session 的 ToolRegistry 与事件流。

### Directory Layout
- `packages/cli/src/mcp/` — client、registry、目录、交互、恢复、日志、任务与结果归一化
- `packages/cli/src/mcp/auth/` — OAuth 策略、回调 provider 与凭据账本
- `packages/cli/src/tools/builtin/mcp/` — Resources、Prompts、Completion 与 Tasks 工具适配
- `packages/cli/src/commands/mcp.ts` — 进程外 MCP 管理命令
- `packages/cli/src/server/routes/mcp.ts` — 当前 Web Session 的 MCP 管理 API
- `packages/cli/src/slash-commands/mcp.ts` — 活动 TUI/ACP Session 的 MCP 命令
- `packages/cli/web/src/components/mcp/` — Web MCP 状态与操作面板

### Key Entry Points
- `resolveWorkspaceMcpConfig()` in `packages/cli/src/mcp/resolveWorkspaceMcpConfig.ts` — 合并并规范化单个 Session 的 MCP 配置
- `McpRegistry.createIsolated()` in `packages/cli/src/mcp/McpRegistry.ts` — 创建 Session 独占 Registry
- `McpClient.connect()` and `McpClient.callTool()` in `packages/cli/src/mcp/McpClient.ts` — 建连、能力协商与工具调用
- `createMcpTool()` in `packages/cli/src/mcp/createMcpTool.ts` — 将协议工具映射为 Blade Tool
- `SessionRuntime.registerMcpTools()` in `packages/cli/src/agent/runtime/SessionRuntime.ts` — 注册动态目录、内容工具和事件监听

## Gotchas
- MCP 配置覆盖顺序是 workspace → plugin →显式 Session → CLI，`strictCliConfig` 会跳过前三类来源；相对 stdio `cwd` 始终按 source project 解析而不是 task worktree(`packages/cli/src/mcp/resolveWorkspaceMcpConfig.ts`)
- `--mcp-config` 的单个非法文件或 JSON 只记录 warning 并跳过，后续参数仍继续覆盖；调用方不能假设解析失败会使 Session 创建失败(`packages/cli/src/mcp/loadMcpConfig.ts`)
- `McpRegistry.registerServer()` 默认吞掉初始连接异常并保留 ERROR server，Session 可继续启动；需要通过状态或显式 reconnect 区分“已注册”与“已连接”(`packages/cli/src/mcp/McpRegistry.ts`)
- 同一 client 同时只允许一个交互式工具调用或 task 创建，因为 Elicitation/Sampling 缺少可靠的父调用关联；并发重叠会在发请求前拒绝(`packages/cli/src/mcp/McpClient.ts`)
- transport 进入恢复前会立即撤销旧 tools、resources、prompts 和 instructions；持有旧 `Tool` 对象或旧 catalog identity 重试会命中死亡 connection generation(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpRegistry.ts`)
- `list_changed` 通知只登记有界合并刷新，完整新目录全部校验成功后才替换；notification 刷新失败保留上一有效目录，而手动刷新会把错误返回调用方(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpToolCatalog.ts`)
- Resource subscription 分为 desired 与 active：异常断连只清 active 并在新目录确认 URI 后恢复，手动 disconnect、unsubscribe 或 Session dispose 才清 desired(`packages/cli/src/mcp/McpClient.ts`)
- MCP Tasks 默认关闭；`taskSupport=required` 的动态工具会自动后台化，`optional` 仍以前台调用为默认，只有显式 `StartMcpTask` 才进入 task 路径(`packages/cli/src/mcp/createMcpTool.ts`, `packages/cli/src/mcp/McpTasks.ts`)
- 模型和用户只能看到 Blade 生成的 `mcp_task_*`，原始 server task ID 必须留在 manager 内部；ownership 同时校验 Session ID 与 canonical execution workspace(`packages/cli/src/mcp/McpTaskManager.ts`, `packages/cli/src/tools/builtin/mcp/mcpTaskTools.ts`)
- 二进制结果绝不能把 base64 直接注入模型；大文本超过 inline budget 后写 Session 私有 artifact，写入失败也只能返回 hash/size/omitted 元数据(`packages/cli/src/mcp/McpToolResult.ts`, `packages/cli/src/mcp/McpToolArtifactStore.ts`)
- MCP 日志是用户诊断事件而非模型输入，server instructions 才会以明确标注“不可信外部文档”的 scoped reminder 进入 provider boundary；二者不能共用注入路径(`packages/cli/src/mcp/McpLogging.ts`, `packages/cli/src/mcp/McpServerInstructions.ts`)

## Architecture
- 每个 Session 创建独立 `McpRegistry`、client、目录 revision 和 artifact writer，进程级 Store 仅用于启动表面的配置投影，不能作为运行时连接来源(`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/mcp/McpRegistry.ts`, `git:6d712a03`)
- 动态工具身份固定为 `mcp__<server>__<tool>`；不安全或过长片段经 NFKC 与摘要后缀规范化，避免 server 同名工具覆盖彼此或覆盖内置工具(`packages/cli/src/mcp/McpToolCatalog.ts`)
- Agent 发起下一次 provider 请求前等待 catalog barrier，随后把完整 MCP 投影一次替换到基础 registry 和每个 executor，并重新应用 whitelist/blacklist(`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/tools/registry/ToolRegistry.ts`)
- 工具调用同时受父 `AbortSignal`、idle timeout 和 hard total timeout 约束；合法 progress 刷新 idle timeout，但不能延长 hard timeout，也不会写入 durable transcript(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpCallLifecycle.ts`)
- Resources、templates 和 prompts 使用独立 revision 与 delta；资源与模板同批获取后提交，读取和 prompt 解析只接受当前 catalog 已声明的 identity(`packages/cli/src/mcp/McpContentCatalog.ts`, `packages/cli/src/mcp/McpClient.ts`)
- Elicitation 在展示前和回传前分别经过 Hooks，最终响应仍按原始 requested schema 校验；没有交互面、取消、超时或异常统一收敛为 cancel/decline(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpElicitation.ts`)
- Sampling 使用当前 Session 冻结模型，按每次请求重新审批，并拒绝 tools、context 扩展、task sampling 和并发 nested request(`packages/cli/src/mcp/McpSampling.ts`, `packages/cli/src/mcp/McpClient.ts`)
- 异步 Task watcher 在 transport 不可用时进入 `interrupted` 并等待同一 client 恢复；恢复后必须验证原始 task ID 与 `createdAt` 未变化才继续取状态或结果(`packages/cli/src/mcp/McpTaskManager.ts`, `packages/cli/src/mcp/McpTasks.ts`)

## Decisions
- MCP 全协议生命周期在一次集中改造中引入，并将目录、内容、交互、日志、任务和 OAuth 都纳入 Session 隔离，而不是继续扩展进程全局 registry(`packages/cli/src/mcp/McpRegistry.ts`, `packages/cli/src/mcp/McpClient.ts`, `git:7894b6e6`)
- Sampling 和 Tasks 均选择默认关闭、按 server 显式启用，因为二者会分别产生额外模型调用和后台生命周期，不能从普通工具授权隐式继承(`packages/cli/src/mcp/McpSampling.ts`, `packages/cli/src/mcp/McpTasks.ts`)
- Completion 被建模为只读候选数据而非控制消息，必须先绑定当前 catalog 中的 prompt 参数或 URI template variable，再做字符和结果预算归一化(`packages/cli/src/mcp/McpCompletion.ts`)
- tool result 与 MCP content 都采用“文本有界保留、二进制只给 provenance”的策略，避免协议返回绕过模型上下文预算和 Web 事件 allowlist(`packages/cli/src/mcp/McpToolResult.ts`, `packages/cli/src/mcp/McpContentCatalog.ts`)
- MCP artifact 后续迁移到共享的私有 Session 存储实现，新增结果类型应复用该存储而不是另建可见目录(`packages/cli/src/mcp/McpToolArtifactStore.ts`, `git:4553d089`)

## Patterns
- 所有会跨异步边界返回的协议对象先 `structuredClone` 或重新归一化，事件再附加单调 revision，防止 listener 修改 Registry 内部状态(`packages/cli/src/mcp/McpRegistry.ts`)
- 目录分页统一限制页数、条目数、重复 cursor、identity 和总字节；超限按整个目录失败处理，不提交部分目录(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpToolCatalog.ts`, `packages/cli/src/mcp/McpContentCatalog.ts`)
- 恢复、Completion、Tasks 和 resource subscription 都捕获当前 client/generation，异步结果返回时发现 client 已变化就拒绝，避免旧 transport 的迟到结果污染新连接(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpConnectionRecovery.ts`)

## Dependencies
- MCP transport、schema 和实验性 Tasks 依赖 `@modelcontextprotocol/sdk`；Blade 在 SDK 校验后仍执行自己的目录、结果、Unicode 和生命周期边界(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/package.json`)
- 动态 MCP 工具复用 Blade 的 TypeBox Tool contract、权限确认、进度事件和 `SessionArtifactStore`，因此协议层修改必须同时检查 ToolRegistry 与 SessionRuntime 投影(`packages/cli/src/mcp/createMcpTool.ts`, `packages/cli/src/mcp/McpToolArtifactStore.ts`)

## Security Considerations
- OAuth 只允许 HTTPS，loopback 可用 HTTP；禁止 URL credentials、手写 Authorization header 和旧式 secret/endpoint 字段，网络请求不跟随 redirect(`packages/cli/src/mcp/auth/McpOAuthPolicy.ts`)
- OAuth 凭据身份由 endpoint、client ID 和排序 scopes 哈希生成，账本与锁文件必须是当前用户拥有的普通 `0600` 文件，写入使用进程内 mutex、跨进程排他锁和原子替换(`packages/cli/src/mcp/auth/OAuthTokenStorage.ts`)
- ACP Session 不读取宿主 OAuth 凭据、不暴露本地 roots 或 artifact path，也不向模型投影 server instruction/log 正文(`packages/cli/src/agent/runtime/SessionRuntime.ts`, `docs/reference/mcp-session-isolation.md`)
- Form Elicitation 拒绝原型污染字段、额外属性和不安全数字；URL Elicitation 只接受无凭据的 HTTP(S) URL，敏感数据应留在外部 URL 流程(`packages/cli/src/mcp/McpElicitation.ts`)
- Prompt 与 Completion 参数必须来自当前 catalog 声明，未知参数、缺失 required 参数和 `__proto__`/`constructor`/`prototype` 在协议请求前拒绝(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpCompletion.ts`)
- 连接错误、Task status/error 与工具错误分别执行 URL、Bearer、API key、控制字符和 UTF-8 字节上限清理，不能把 transport 文本直接用作模型指令(`packages/cli/src/mcp/McpConnectionRecovery.ts`, `packages/cli/src/mcp/McpTasks.ts`, `packages/cli/src/mcp/McpToolResult.ts`)

## Error Handling & Recovery
- 自动恢复是 single-flight generation 状态机；手动 disconnect 或 dispose 会提升 generation、取消连接和退避，旧 close/error 回调不能覆盖新状态(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/McpConnectionRecovery.ts`)
- 只有 session-not-found、连续终端 transport 错误和健康检查阈值进入恢复；普通协议校验错误不会触发重连风暴(`packages/cli/src/mcp/McpClient.ts`, `packages/cli/src/mcp/HealthMonitor.ts`)
- Session dispose 先取消当前 Session 的 MCP Tasks，再解除 Registry listener 并断开全部 client，防止终态事件写入已释放的执行器目录(`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/mcp/McpTaskManager.ts`)