IronClaw MCP 执行通道（ironclaw_mcp）源码解析：主机中介 HTTP、JSON-RPC 编解码与资源治理

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 是一个以隐私、安全与可扩展性为核心的 Agent OS。ironclaw_mcp是它的 MCPModel Context Protocol执行通道lane负责把清单manifest声明的 MCP 工具适配为宿主能力capability并严格限定在主机中介的 HTTPhost-mediated HTTP上运行。本文以 crates/lanes/ironclaw_mcp/README.md 为骨架结合 src/lib.rs 及其七个私有模块、Cargo.toml 和测试套件逐层拆解其公开 API 面、JSON-RPC 2.0 编解码、tools/list目录准入、主机中介出站计划器与资源预算治理帮助你理解一个“自身没有任何网络栈”的 MCP lane 如何在 IronClaw 内核中安全落地。定位与边界一个只通过注入端口外发的协议通道README 开宗明义ironclaw_mcp是distinct protocol lane独立的协议通道拥有自己的发现机制discovery与 JSON-RPC 表面。它的核心约束是这个 crate完全不持有 HTTP 客户端依赖——每一次出站 JSON-RPC 调用都由注入的 egress 端口egress port规划并执行因此 lane 无法主动发起任何内核未中介mediated的连接。这条规则是“每 lane 单一外部机制”原则的体现WASM lane 里只有 WASM 引擎、sandbox lane 里只有容器机制、而这里没有网络栈。这个不变式只有在“每个 lane 是一个独立 crate”的前提下才可被静态陈述和验证。适用场景与反场景Use this when使用场景一次已获授权的调用already-authorized invocation的目标是某个 MCP 服务器的工具或者 composition 正在把 MCP 运行时与一个具体的主机中介传输host-mediated transport接线。Dont use this when不要用于判断调用是否被允许——那属于内核kernel你需要一个包“是什么”manifest、安装记录——那是ironclaw_extension_contracts词汇表/扩展家族你需要裸 HTTP——那是ironclaw_network位于内核的 egress seam 之后永远不该在这里。依赖面与消费面刻意收窄的依赖图Cargo.toml 展示了极简的依赖策略[dependencies] async-trait 0.1 futures-util 0.3 ironclaw_host_api { path ../../contracts/ironclaw_host_api } ironclaw_extension_contracts { path ../../contracts/ironclaw_extension_contracts, version 0.1.0 } serde_json 1 thiserror 2 tracing 0.1 [dev-dependencies] ironclaw_extension_registry { path ../../extensions/ironclaw_extension_registry } ironclaw_resources { path ../../kernel/ironclaw_resources } tempfile 3 tokio { version 1, features [macros, rt] } tracing-test { version 0.2, features [no-env-filter] }生产依赖只有两个 workspace crateironclaw_host_api宿主 API 契约与ironclaw_extension_contracts扩展域词汇表。ironclaw_extension_registry与ironclaw_resources仅是 dev-dependencieslane 的测试套件通过真实 governor 驱动预算端口budget port而不是用一个 lane 本地的假对象。Cargo.toml 注释明确警告“不要把两者提升为生产依赖”。实测README 记录于 2026-08-05消费方有三个ironclaw_host_runtimelane 执行器、ironclaw_extension_host、ironclaw_composition。公开表面Public surface七个私有模块与单一导入路径ironclaw_mcp的七个模块全部是private的所有公开项通过lib.rs重导出因此ironclaw_mcp::X是唯一导入路径模块改名永远不构成破坏性变更。src/lib.rs的文档注释里有一张权威的模块章程表module charter table模块拥有什么永不允许出现contract调用方命名的词汇配置、invocation/request/output DTO、McpClient与McpExecutortrait、McpError/McpClientError错误分类协议帧、传输或资源核算runtime受资源治理的执行reserve → call → reconcile/release、描述符准入、manifest 凭据上下文JSON-RPC、HTTP 或目录解析clientStreamable-HTTPMcpClient实现握手、逐 invocation 的会话生命周期、tools/list分页循环线上编解码那是jsonrpc或目录准入规则那是discoveryjsonrpcJSON-RPC 2.0 编解码与 MCP 响应卫生encode、plain-JSON 与 SSE 帧、id 匹配、session-id 与协议版本校验、auth-challenge 提取、按方法路由凭据会话状态那是client或工具形状规则那是discoverydiscoverytools/list目录准入宿主上限、逐工具分类、input-schema 边界、描述截断、annotations、工具名语法任何发送/接收请求的东西egress主机中介的 HTTP seamMcpHostHttp端口、运行时 egress 适配器、宿主拥有的 egress plan/planner任何属于协议内容的 URL、header 或 body 决策diagnosticslane 对外暴露的每一个稳定、有界失败 token以及其背后的 cause 枚举失败决策——模块负责分类diagnostics只负责命名关键公开类型速览运行时McpRuntime、McpExecutor、McpRuntimeConfig请求/结果McpInvocation、McpExecutionRequest、McpExecutionResult错误类型McpError客户端 seamMcpClienttrait 及其McpClientRequest/McpClientOutput覆盖 Streamable-HTTP JSON-RPC握手、逐 invocation 会话生命周期、tools/list分页循环EgressMcpHostHttp端口、McpRuntimeHttpAdapter、McpHostHttpClient以及 egress 计划器对McpHostHttpEgressPlanner/StaticMcpHostHttpEgressPlanner诊断lane 对外暴露的所有稳定、有界失败 token收敛在diagnostics一个模块中。McpRuntimeConfig输出字节上限contract.rs定义了宿主拥有的唯一配置项pub struct McpRuntimeConfig { pub max_output_bytes: u64, } impl Default for McpRuntimeConfig { fn default() - Self { Self { max_output_bytes: 1024 * 1024 } // 默认 1 MiB } } impl McpRuntimeConfig { pub fn for_testing() - Self { Self { max_output_bytes: 64 * 1024 } // 测试用 64 KiB } }默认输出上限为1 MiB测试使用 64 KiB。该限制在两条防线生效客户端适配器在读取 MCP 服务器输出、构造结构化 JSONValue之前必须强制McpClientRequest::max_output_bytes运行时在适配器返回后还会对序列化输出做二次检查McpError::OutputLimitExceeded后者是第二道防线而非主要内存边界。资源治理没有预算权力的 lane#7067README 的不变式之一明确写道“No budget authority (#7067)”——lane 只接受ironclaw_host_api::resource::RuntimeResourceBudgetreserve/reconcile/release绝不接受ResourceGovernor。内核通过ironclaw_resources::GovernorRuntimeBudget在该端口上实现真实 governor因此 lane 无法设置限额、读取账户状态或指定账户每次保留reservation要么 reconcile、要么 release且恰好一次。runtime.rs中的执行主流程execute_extension_json严格遵循reserve → call → reconcile/releaseprepare_client_request在capabilities中按capability_id查找描述符校验descriptor.runtime RuntimeKind::Mcp且descriptor.provider extensionDescriptorMismatch从ExtensionRuntime::Mcp { transport, command, args, url }中投影出传输字段。传输准入stdio直接拒绝ExternalStdioTransportUnsupported注释说明“在进程级 egress 控制落地之前不支持”非http/sse拒绝UnsupportedTransporthttp/sse但缺少 manifest url 拒绝InvalidInvocation。若客户端未声明uses_host_mediated_http_egress()而传输需要主机中介 HTTP返回HostHttpEgressRequired。reserve_or_use_existing若已有宿主下发的 reservation校验其 scope 与 estimate 一致后复用不创建次级保留否则调用budget.reserve。调用client.call_tool失败时区分“可核算失败”AuthRequired/AuthChallenge/ProviderRejected携带 usage走budget.reconcile与“不可核算失败”走release_after_failure。成功路径序列化输出并检查max_output_bytes随后budget.reconcile恰好一次再根据provider_rejection决定返回结果或ProviderRejected错误。release_after_failure采用silent-ok策略执行失败本身就是面向调用方的错误不能被一次 release 失败掩盖release 失败只会在 governor 回收前泄漏保留因此用tracing::debug!记录而不上抛注释特别说明不用info!/warn!以免污染 REPL。调用方义务三处独立借用必须来自同一包McpExecutionRequest刻意不接收ExtensionPackage只接收extension、capabilities、runtime三个独立借用这是为了切断runtimes - loops对 registry crate 的依赖即 README 提到的 W7 例外。代价是类型层面不再结构性保证三者出自同一包把扩展 A 的描述符与扩展 B 的 runtime stanza 配对会“以 A 的身份认证、拨号 B”。因此 README 与contract.rs都强调必须在同一个表达式中从同一个ExtensionPackage投影全部三者。唯一的生产调用方ironclaw_host_runtime::services::runtime_adapters正是这么做的——在 runtime_adapters.rs 中一次性构造McpExecutionRequest { extension: request.package.id, capabilities: request.package.capabilities, runtime: request.package.manifest.runtime, ... }。客户端 seamStreamable-HTTP 的握手、会话与tools/list分页client.rs实现了McpHostHttpClientH, P泛型于H: McpHostHttp与P: McpHostHttpEgressPlanner。它拥有的是时序规划请求 → 执行initialize/notifications/initialized握手 → 执行tools/call或tools/list分页循环以及该时序依赖的逐 invocation 会话状态。它自己不帧化任何报文jsonrpc负责、不裁决任何工具形状规则discovery负责、不直接发送任何字节egress负责。会话键与会话隔离会话按scope/provider/url隔离键为McpHostHttpSessionKeystruct McpHostHttpSessionKey { tenant_id: String, user_id: String, agent_id: OptionString, project_id: OptionString, mission_id: OptionString, thread_id: OptionString, invocation_id: String, provider: String, url: String, }invocation_id也参与键因此不同 invocation 的并发调度落在不相交的 map 条目上std::sync::Mutex只保护 O(1) 的 HashMap 操作、绝不跨越.await持锁无真实竞争。会话通过 RAII 的McpHostHttpSessionCleanup在 Drop 时自动移除避免泄漏。会话 id 在复用前必须通过校验见下文jsonrpc的is_safe_mcp_session_id。initialize握手细节initialize_session依次发送initialize携带 id——参数由json_rpc_initialize_params()生成声明协议版本2025-06-18STREAMABLE_HTTP_MCP_PROTOCOL_VERSION、能力roots/sampling以及clientInfoname 固定为ironclawversion 取自env!(CARGO_PKG_VERSION)notifications/initialized无 id——一个 notificationMCP 规范允许 202 响应。握手成功后把(session_id, protocol_version)存入会话表后续每个 JSON-RPC 请求都会带上MCP-Protocol-Version头常量MCP-Protocol-Version与Mcp-Session-Id头。tools/call与工具名规约调用工具时mcp_tool_name会把capability_id中形如nearai.web_search的前缀剥掉得到规范工具名web_searchclient.rs中mcp_tool_name_strips_provider_prefix_for_canonical_tool_name测试锁定了这一行为。tools/call的 JSON-RPC 参数为{name: tool_name, arguments: input}。当响应携带isError: true时call_tool_rejection_message会拼接所有非空text内容块作为ProviderDiagnosticcode 为mcp_tool_rejected空内容则回退到固定文案 “MCP server rejected the tool call”。tools/list分页循环discover_tools遵循“discovery 拥有规则、client 拥有循环”的章程分页上限与运行总量检查从discovery读同一组常量两个强制点不可能漂移MAX_DISCOVERED_MCP_TOOLS 1024跨所有页的工具总数上限MAX_MCP_TOOLS_LIST_PAGES 50单次发现最多跟随 50 页MAX_MCP_TOOLS_CATALOG_BYTES 16 MiB跨页累计序列化字节上限。第一页的 plan 在initialize_session之前构建保证 planner 在握手前就看到tools/list与既有单页发现的时序一致后续页在拿到nextCursor后惰性规划。循环中同时检查工具数discovered page MAX_DISCOVERED_MCP_TOOLS或超过调用方传入的max_tools与累计字节数超出即返回McpClientError::invalid_tool_catalog。认证挑战处理对 401/403 响应is_mcp_auth_response_status命中后从响应头提取认证挑战WWW-Authenticate与protected-resource-metadata中的 OAuth 元数据位置extract_mcp_auth_metadata_locations。若两者都为空则返回裸AuthRequired否则返回AuthChallenge。挑战是头派生且刻意脱敏的——jsonrpc.rs的auth_challenge_redacts_response_body_and_preserves_only_metadata_locations测试证明响应体与 token 绝不出现在挑战中format!({:?}, challenge)不含super-secret、access_token等敏感内容。JSON-RPC 2.0 编解码与响应卫生jsonrpc.rs是线协议层一个请求在这里编码、一个响应在这里解析同时接受客户端宣告的两种帧application/json与text/event-stream。这个模块校验的一切都是不可信的远端输入响应id、Mcp-Session-Id、协商出的协议版本、auth-challenge 头。已知方法集合与凭据路由enum McpJsonRpcMethod { Initialize, // initialize InitializedNotification, // notifications/initialized ToolsList, // tools/list ToolsCall, // tools/call }每个方法的凭据路由行为是宿主拥有的credential_injections检查注入来源RuntimeCredentialSource::SecretStoreLease直接 secret-store 租约在任何 MCP 边界上都被拒绝DeniedCredentialSource包括tools/call与 staging 两种校验入口validate_tools_call_credential_injections/validate_staged_credential_injections。这对应 AGENTS.md 中“staged credentials 必须保持作用域到 invocation 完成”的规则——宿主 MCP 提供商可能要求整个 JSON-RPC 会话包括初始化都带鉴权。响应解析与 id 匹配parse_mcp_response按content-type分流SSE 分支逐行累积data:载荷、跳过空 keepalive、按expected_id匹配事件plain-JSON 分支直接解析并校验idIdMismatch稳定 token 为mcp_jsonrpc_id_mismatch。测试矩阵parse_mcp_response_accepts_both_advertised_framings锁定了双帧一致性同一逻辑响应既可能是application/json也可能是带 keepalive ping 的text/event-stream; charsetutf-8。会话 id 与协议版本的安全校验is_safe_mcp_session_id非空、≤ 1024 字节、全部为可打印 ASCII0x21..0x7e否则mcp_invalid_session_idis_safe_mcp_protocol_version非空、≤ 64 字节、仅字母数字与./-/_否则mcp_invalid_protocol_version。错误对象的边界化JSON-RPCerror对象被收敛为JsonRpcErrorInfo { code, message }message经bound_mcp_reason_detail处理控制字符替换为空格、超过MAX_MCP_REASON_BYTES512 字节时按字符边界截断并追加...。这保证进入私有 cause 通道的内容永远有界。Discoverytools/list目录准入discovery.rs裁决“宿主发布哪些工具”。其分类哲学在源码注释与测试中反复强调形状缺陷shape-only defect与安全/边界违规security/bounds violation分开处理。逐工具分类安全/边界违规整代拒绝不可重试缺失inputSchema或 schema 非对象missing_input_schemaschema 不安全unsafe_input_schema——深度 32、节点数 8192、字符串 16 KiB、含非法控制字符。这些违规优先于外观缺陷求值防止恶意条目搭合法目录的便车测试parse_tools_list_result_fails_whole_catalog_when_unsafe_schema_amid_valid_tools。形状缺陷逐工具跳过其余继续发布工具名不合法invalid_tool_name、描述含非法控制字符或超长invalid_description、annotations 畸形invalid_annotations。跳过时仅记录“工具索引 稳定 cause token”绝不记录提供商原始内容tracing::debug!。一个畸形条目不能毁掉首次安装时原本有效的集成测试parse_tools_list_result_skips_shape_invalid_tools_and_publishes_bounded_remainder。若所有工具都被跳过则本代发现以稳定子原因失败而不是激活在空目录上而空提供商列表无工具、无跳过则保留为空结果由调用方视为“尚未发现工具”。工具名语法被发现的工具名会成为 Reborn capability 后缀因此 discovery跳过而非规范化不支持的名称避免产生潜在冲突的 capability id。is_supported_mcp_tool_name规则非空、≤ 128 字节、不含..、按.分段后每段以小写字母或数字开头、只含小写字母/数字/_/-。边界测试覆盖了Search大写、search._private下划线开头、search..issues连续点等拒绝案例。描述截断描述是展示元数据可以被安全地有界bound_mcp_tool_description对超过 2048 字节的描述做 UTF-8 字符边界安全截断并追加...测试验证了 emoji 描述在 2048 字节内且以...结尾、仍处于字符边界。名称与 schema 保持 fail-closed——截断二者可能改变能力语义。Egress唯一的字节出口egress.rs的模块注释直白“MCP lane 不执行任何自身网络操作”。它把CapabilityHostHttpRequest交给McpHostHttp端口网络策略、凭据句柄、响应限制与超时全部来自宿主拥有的McpHostHttpEgressPlanner——而不是插件输入。计划器契约pub struct McpHostHttpEgressPlan { pub network_policy: NetworkPolicy, pub credential_injections: VecRuntimeCredentialInjection, pub response_body_limit: Optionu64, pub timeout_ms: Optionu32, }plan必须确定且无副作用。具体 HTTP 客户端在 MCP 握手前就为真实的tools/callbody 规划一次、校验其凭据来源再把该 plan 贯穿到稍后的传输发送中。Planner 可见的头是稳定的策略头Content-Type: application/json、Accept: application/json, text/event-stream动态的 MCP 会话头由协议客户端在规划之后添加。响应体限制取“宿主限制与客户端max_output_bytes的较小值”effective_mcp_response_body_limit把内存边界收在宿主侧。McpRuntimeHttpAdapter包裹宿主运行时 egressRuntimeHttpEgress并把请求标记为RuntimeKind::Mcp它用AssertUnwindSafe catch_unwind把 egress future panic 转译为稳定的runtime_http_egress_panickedtoken。适配器的泛型便利McpHostHttp与McpHostHttpEgressPlanner都为ArcT提供了 blanket 实现因此 composition 可以直接传入Arcdyn ...或Arc具体适配器。错误词汇表diagnostics是唯一命名者“没有任何模块自己构造失败字符串”是 crate 章程的承重条款理由只能来自diagnostics的 cause 枚举因此模型可见的 token 集合可以在一个文件里被枚举和有界。三组 cause 枚举McpRequestDeniedCause发送前/规划期失败mcp_request_encode_failed、mcp_missing_url、mcp_unsupported_transport、mcp_denied_credential_source、mcp_session_state_poisoned、mcp_accounting_invariantMcpResponseErrorCause响应侧失败mcp_jsonrpc_error、mcp_parse_failed、mcp_missing_result、mcp_invalid_session_id、mcp_invalid_protocol_version、mcp_jsonrpc_id_mismatch、mcp_no_payload、mcp_invalid_tool_list: subcauseMcpEgressCauseegress 失败runtime_http_egress_panicked、runtime_http_egress_failed。Provider 拒绝走独立的稳定 code 词汇mcp_http_status_status、mcp_jsonrpc_error_code、mcp_tool_rejected。架构测试如何“武装”这条规则reborn_dependency_boundaries.rs 中的reborn_runtime_http_egress_has_single_network_boundary以非空洞断言扫描本 crate 整个src/树连同 WASM、sandbox、host_runtime 的src/禁止reqwest::Client、ToSocketAddrs、.to_socket_addrs(、ssrf_safe_client_builder、validate_and_resolve_http_target、reject_private_ip、is_private_or_loopback_ip等模式——从源码层面杜绝任何绕过主机中介的出站 HTTP。module_charter.rs 则是另一道闸它静态扫描除diagnostics.rs外的所有src/*.rs剔除#[cfg(test)]段断言不存在reason: …/reason: format!(…)字面量唯二的祖父豁免grandfathered carve-out是runtime.rs中McpError::DescriptorMismatch与InvalidInvocation——它们回显 manifest 自身的 id/传输名而非分类失败。该测试同时钉死impl FromString for McpClientError已被删除曾经任何?都可能把任意String静默变成模型可见理由这个隐式旁路已被封死。模块章程测试文档、规则与闸门互相锁定module_charter.rs的第三个测试the_charter_text_names_the_rule_this_gate_enforces把lib.rs与AGENTS.md的空白归一化后断言两者仍包含 “no module builds a failure string of its own” 与 “module_charter.rs” 字样——防止“三处承诺不变式、却无人检查”的文档漂移。这也是为什么 AGENTS.md 会注明“被 gate 钉死”编辑它时手上要握着cargo test -p ironclaw_mcp。测试与验证cargo test -p ironclaw_mcp # 含 tests/module_charter.rs cargo test -p ironclaw_architecture_tests # egress 扫描 层矩阵集成测试 mcp_dispatch_integration.rs 演示了完整的“manifest 传输投影 → 真实 governor 资源核算”链路构造真实ExtensionPackage、把三个输入投影给 lane并通过GovernorRuntimeBudget驱动真实governor而不是 lane 本地的假预算因此测试断言到的拒绝denial是内核真实产出的。其中mcp_lane_executes_manifest_transport_and_reconciles_resources验证HTTP 传输url 为https://mcp.example.test/rpc、无 command/args、reconcile 后ReservationStatus::Reconciled、process_count 0此 lane 不派生进程、usage 正确累计mcp_lane_client_failure_releases_reservation验证失败路径释放保留后 governor 账户归零。运行时适配层测试位于 crates/kernel/ironclaw_host_runtime/src/services/tests/mcp_runtime_adapter.rsAuthRequiredMcpExecutor/FailingMcpExecutor对应适配器的鉴权与失败分发生产装配则在 production_wiring.rs 中以ProductionWiringComponent::McpRuntime声明。设计记录与进一步阅读README 指向的设计记录为 PROPOSAL §6.6.3模块拆分动议契约文档位于docs/internal/reborn/contracts/mcp.md、docs/internal/reborn/contracts/runtime-workflows.md、docs/internal/reborn/contracts/processes.md工作规则见 crates/lanes/ironclaw_mcp/AGENTS.mdcanonical crate guardrails由tests/module_charter.rsgate 钉住家族边界见 crates/lanes/AGENTS.md。小结ironclaw_mcp用“零网络栈 单一注入 egress 端口 窄预算端口 单文件可枚举错误词汇”四个设计支柱把 MCP 执行 lane 的安全边界做成了可被架构测试静态证明的不变式协议编解码在jsonrpc、会话时序在client、目录准入在discovery、字节出口在egress、资源核算在runtime、失败命名在diagnostics——而contract则是这一切的词汇总表。任何新增代码放哪、什么不能漂移进哪个模块都由 lib.rs 的章程表和两道测试闸门共同裁决。对于要在 IronClaw 上集成 MCP 服务器的开发者这条 lane 提供了一条“清单声明 → 主机中介 HTTP → 受治理执行”的完整、可审计路径。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Coder 子代理方向规范有界编码任务的执行协议与源码实现解析IronClaw Coder 子代理方向规范有界编码任务的执行协议与源码实现解析 本技术指南聚焦 IronClaw 开源 Agent OS 中 ironcla人工智能AI 应用交互助手AI AgentIronClaw WASM 执行通道lane深度解析组件模型 ABI、deny-by-default 沙箱与资源计量IronClaw WASM 执行通道lane深度解析组件模型 ABI、deny by default 沙箱与资源计量 IronClaw 的 ironcla人工智能AI 应用交互助手AI Agent时间序列预测训练效率完整指南三个阶段配好早停时间序列预测训练效率完整指南三个阶段配好早停 用 Time Series Library一个支持长短期预测、分类、异常检测、插补的深度学习时序模型库跑预测人工智能AI 应用交互助手AI Agent上一篇魔兽争霸3性能优化终极指南突破60FPS限制实现180FPS流畅体验下一篇Mermaid Live Editor终极指南5分钟免费掌握在线图表编辑创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考