深入解析 Agents 仓库的 MCP SDK v2 Conformance Fixtureeverything-server-v2.ts 的 workerd 移植与一致性验证【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents在 Cloudflare Agents 生态中MCPModel Context Protocol是一致性与互操作性的核心基石。本文围绕 packages/agents/conformance/vendor/README.md 展开详细剖析该仓库如何将官方 MCP TypeScript SDK v2 的一致性测试固件conformance fixture移植到 workerd 运行时并以此为基准对 Agents 的 MCP 客户端与服务器实现进行端到端验证。读完本文你将掌握该 fixture 的上游来源与精确校验方法、本地适配的取舍边界、更新 SDK 版本时遵循的验证流程以及整套 conformance 套件在仓库中的运行方式。一、什么是 MCP SDK v2 Conformance Fixture在 vendor/README.md 的界定下everything-server-v2.ts是对 MCP TypeScript SDK v2 一致性测试固件everything server即覆盖 MCP 协议几乎所有能力的综合测试服务器的 workerd 适配版本。其上游来源被精确记录上游仓库https://github.com/modelcontextprotocol/typescript-sdk发布标签modelcontextprotocol/server2.0.0固定 commitcc4b41617ce3601b1290d67216ea0b194a3cd9ac上游源文件test/conformance/src/everythingServer.ts源文件 SHA-2563a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852这一固件被用作无状态服务器stateless server一致性测试的服务器端被测对象。之所以需要本地移植原因在 conformance/README.md 中有明确说明The SDK does not publish the fixture as an importable module, and its upstream entrypoint depends on Node and Express, so the local adaptation is required to exercise the server inside workerd.即官方 SDK 并未将该固件作为可导入模块发布且其上游入口依赖 Node.js 与 Express因此必须在仓库内做本地适配才能在 workerd 中运行服务器。二、本地适配的取舍边界保留了什么去掉了什么everything-server-v2.ts 文件顶部注释即声明了它的性质Workerd adaptation of the MCP TypeScript SDK v2 conformance fixture. Exact provenance and update instructions live in ./README.md.按照 vendor/README.md 的说明本地固件遵循如下边界完整保留上游的全部工具tool注册包括测试文本、图片、音频、内嵌资源、多内容类型、错误处理、采样sampling、elicitation、进度通知、日志、SSE 重连等各类协议特性的测试端点与协议一致性相关的行为细节如 SEP-2243 的x-mcp-header注解、SEP-2575 的诊断型工具、SEP-1034 的 elicitation 默认值等。移除/替换Node/Express 入口点Node 传输层transports会话注册表session registryNode 事件存储event store。新增导出一个工厂函数供 Agents 的 workerd conformance worker 使用使用Web Crypto保证请求状态requestState的完整性。该文件末尾整体只导出一个工厂函数createEverythingServerV2见 everything-server-v2.ts签名如下export interface EverythingServerV2Options { notify: { toolsChanged(): void; promptsChanged(): void; }; } export function createEverythingServerV2(options: EverythingServerV2Options) { // ... }这一设计使得 conformance worker 可以在每个无状态请求到来时创建全新服务器实例完全契合stateless2026-07-28协议路径。三、如何被消费conformance worker 中的接入点适配后的固件在 conformance/worker.ts 中被直接导入使用import { createEverythingServer } from ./everything-server.ts; import { createEverythingServerV2 } from ./vendor/everything-server-v2.ts;该 worker 同时托管了三代服务器实现注释说明见 worker.ts端点实现说明/mcp-handlerSDK v2 无状态createMcpHandler使用createEverythingServerV2固件/mcp-handler-legacy显式createLegacyMcpHandlerWorkerTransport旧版兼容有独立固件/mcp-agent保留的 SDK v1McpAgent旧版会话式实现其中/mcp-handler既是 2026-07-28 stateless 服务器 lane 的被测对象也是 legacy-compat lane 的兼容被测对象这正是 vendored fixture 存在的核心价值——让服务器实现以与线上完全一致的方式真实 Durable Object 存储、真实路由、真实传输在 workerd 内被测。四、关键实现细节requestState 完整性保护SEP-2322在 everything-server-v2.ts 中有一处精心设计的实现值得关注多轮往返MRTR请求状态完整性。核心背景代码注释原文含义requestState会往返经过客户端并作为攻击者可控的输入返回。SDK 将其视为不透明字符串且自身不提供保护因此任何让请求状态影响行为的服务器在签发时必须做完整性保护并在验证失败时拒绝。该固件使用 SDK 提供的createRequestStateCodec辅助函数mint用进程内随机密钥crypto.getRandomValues(new Uint8Array(32))对载荷做 HMAC 密封并带 TTLverify作为ServerOptions.requestState.verify挂入服务端接缝在被篡改或过期的状态到达时以-32602拒绝——这正是input-required-result-tampered-state一致性场景所断言的。代码中的一处 workerd 适配细节也值得记录workerd 禁止在模块作用域随机生成密钥因此密钥生成被推迟到请求处理器内的工厂函数中通过惰性单例sharedRequestStateCodec ?? ...实现整个 isolate 一把签名密钥见 everything-server-v2.ts。五、固件中的工具注册全景everything-server-v2.ts 中共 1530 行注册了大量测试工具覆盖 MCP 协议各能力面。核心工具清单与作用工具名验证的能力关键行为test_simple_text文本内容响应返回纯文本test_image_content图片内容响应返回 base64 的 1x1 红色 PNG 像素test_audio_content音频内容响应返回 base64 的最小 WAV 文件test_embedded_resource内嵌资源内容返回test://URI 的内嵌资源test_multiple_content_types多内容类型响应同时返回 text/image/resourcetest_error_handling错误响应处理主动抛出错误test_sampling服务器发起采样通过sampling/createMessage请求客户端 LLM 补全test_elicitation服务器发起 elicitation通过elicitation/create请求用户输入test_elicitation_sep1034_defaultsSEP-1034 默认值为 string/integer/number/enum/boolean 提供默认值test_tool_with_logging工具内日志执行期间发送多条notifications/messagetest_tool_with_progress进度通知仅在客户端提供progressToken时发送notifications/progress0/50/100test_reconnectionSSE 重连SEP-1699中断 SSE 流验证客户端重连test_x_mcp_headerSEP-2243 请求头校验手写 JSON Schema 保留x-mcp-header注解test_missing_capabilitySEP-2575 能力声明检查未声明sampling能力时驱动-32021拒绝test_streaming_elicitationSEP-2575 流式响应响应流不携带独立顶层 JSON-RPC 请求test_logging_toolSEP-2575 日志门控仅在请求携带_meta.logLevel时通过ctx.mcpReq.log输出日志此外服务器能力声明中还特意保留了已废弃的logging能力协议版本 2026-07-28 起按 SEP-2577 弃用目的是让 2025 时代的logging/setLevel一致性分支仍能协商该能力2026-07-28 路径则走每次请求的 envelope 并忽略此字段见 everything-server-v2.ts。六、更新 SDK Pin 的验证流程vendor/README.md 对更新上游 SDK 版本给出明确的操作流程获取固定 commit 处的源文件在记录的上游 commit 处拉取test/conformance/src/everythingServer.ts校验 SHA-256必须与记录的3a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852一致确保拿到的是未被篡改的精确上游内容检查无索引 diff与本地文件做 no-index diff即diff而非git diff审视差异仅移植 workerd 固件所需的注册变更只把与注册tool/prompt/resource 注册相关的必要变更同步进本地固件继续保持 Node/Express、Node 传输、会话注册表、Node 事件存储的移除边界。这一流程保证了本地固件与上游的可追溯性provenance与可审计性。七、将固件放进更大的测试框架中运行vendored fixture 并非孤立文件它处于仓库完整的 MCP conformance 测试体系之中详见 conformance/README.md。测试基准固定 pin 的官方评审器refereemodelcontextprotocol/conformance0.2.0-alpha.10在 package.json 中以npm:modelcontextprotocol/conformance-v20.2.0-alpha.10别名引入在wrangler dev中针对 Agents 实现运行。服务器 lane 矩阵conformance/run.sh中定义命令协议/生命周期端点当前结果test:conformance:server:handlerstateless2026-07-28/mcp-handler40 项全 cleantest:conformance:server:handler:legacy-compatlegacy 兼容、stateless/mcp-handler26 clean / 6 项预期失败test:conformance:server:handler:legacylegacy、sessionful/mcp-handler-legacy29 clean / 3 项预期失败test:conformance:server:mcp-agentlegacy、sessionful/mcp-agent29 clean / 3 项预期失败预期失败均有专用、非空的 baseline 文件如 baseline-server-handler.yml、baseline-client-2026-07-28.yml每条预期失败旁都有注释说明其实际影响及归属Agents / SDK v1 / alpha 评审器 fixture。stateless handler 无任何预期失败。本地运行方式cd packages/agents # 全部串行 pnpm run test:conformance # 服务器生命周期矩阵 pnpm run test:conformance:server:handler pnpm run test:conformance:server:handler:legacy-compat pnpm run test:conformance:server:handler:legacy pnpm run test:conformance:server:mcp-agent # 聚焦单个场景 bash conformance/run.sh server-handler --scenario server-statelessrun 脚本run.sh会占用端口前检查 Worker 端口默认 8788可用CONFORMANCE_WORKER_PORT覆盖与 inspector 端口默认端口10000是否已被占用拒绝在陈旧 worker 上测试并在退出时清理完整的 Wrangler/workerd 进程树。失败判定策略run-suite.mjs与 alpha 评审器在 suite 模式下不可靠的部分形成互补限定客户端并发client 6、server 1对衍生的 driver 与 mock server 做进程组清理客户端非零退出即使 wire 断言通过也计为失败服务器 WARNING 计为失败除非该场景在 baseline 中唯一的例外是client-sse-retry-timing的 reconnected slightly late 时序警告评审器自身判定可接受避免在 CI 加载抖动下产生 flake每个预期失败条目必须属于所选日期 lanestale baseline已通过却仍留在 baseline同样使 CI 失败。八、总结packages/agents/conformance/vendor/目录下的 vendored fixture 是整个 MCP 一致性体系的地基它以固定 commit SHA-256精确定格了官方 SDK v2 conformance 固件通过最小化适配剥离 Node/Express 依赖而保留全部注册行为导出单个工厂函数供 workerd conformance worker 复用并用Web Crypto落实 requestState 完整性SEP-2322。对开发者而言它既是理解 MCP 协议各能力面采样、elicitation、SSE 重连、能力声明校验等的浓缩范本也是一份如何在 workerd 中移植 Node 依赖型测试固件的可复现操作手册——更新 SDK pin 时严格按文档流程校验来源、审阅 diff、只移植注册变更即可保持整个一致性矩阵的可信与可维护。如需深入源码建议从 vendor/everything-server-v2.ts 的工具注册段入手对照 conformance/README.md 的 lane 矩阵与 run-suite.mjs 的判定逻辑即可完整还原该 fixture 从上游测试固件到workerd 内被测对象的整条链路。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 23:05:01 · 阅读 1.2k 深入解析 Agents 仓库的 MCP SDK v2 Conformance Fixture：everything-server-v2.ts 的 workerd 移植与一致性验证
深入解析 Agents 仓库的 MCP SDK v2 Conformance Fixtureeverything-server-v2.ts 的 workerd 移植与一致性验证【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents在 Cloudflare Agents 生态中MCPModel Context Protocol是一致性与互操作性的核心基石。本文围绕 packages/agents/conformance/vendor/README.md 展开详细剖析该仓库如何将官方 MCP TypeScript SDK v2 的一致性测试固件conformance fixture移植到 workerd 运行时并以此为基准对 Agents 的 MCP 客户端与服务器实现进行端到端验证。读完本文你将掌握该 fixture 的上游来源与精确校验方法、本地适配的取舍边界、更新 SDK 版本时遵循的验证流程以及整套 conformance 套件在仓库中的运行方式。一、什么是 MCP SDK v2 Conformance Fixture在 vendor/README.md 的界定下everything-server-v2.ts是对 MCP TypeScript SDK v2 一致性测试固件everything server即覆盖 MCP 协议几乎所有能力的综合测试服务器的 workerd 适配版本。其上游来源被精确记录上游仓库https://github.com/modelcontextprotocol/typescript-sdk发布标签modelcontextprotocol/server2.0.0固定 commitcc4b41617ce3601b1290d67216ea0b194a3cd9ac上游源文件test/conformance/src/everythingServer.ts源文件 SHA-2563a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852这一固件被用作无状态服务器stateless server一致性测试的服务器端被测对象。之所以需要本地移植原因在 conformance/README.md 中有明确说明The SDK does not publish the fixture as an importable module, and its upstream entrypoint depends on Node and Express, so the local adaptation is required to exercise the server inside workerd.即官方 SDK 并未将该固件作为可导入模块发布且其上游入口依赖 Node.js 与 Express因此必须在仓库内做本地适配才能在 workerd 中运行服务器。二、本地适配的取舍边界保留了什么去掉了什么everything-server-v2.ts 文件顶部注释即声明了它的性质Workerd adaptation of the MCP TypeScript SDK v2 conformance fixture. Exact provenance and update instructions live in ./README.md.按照 vendor/README.md 的说明本地固件遵循如下边界完整保留上游的全部工具tool注册包括测试文本、图片、音频、内嵌资源、多内容类型、错误处理、采样sampling、elicitation、进度通知、日志、SSE 重连等各类协议特性的测试端点与协议一致性相关的行为细节如 SEP-2243 的x-mcp-header注解、SEP-2575 的诊断型工具、SEP-1034 的 elicitation 默认值等。移除/替换Node/Express 入口点Node 传输层transports会话注册表session registryNode 事件存储event store。新增导出一个工厂函数供 Agents 的 workerd conformance worker 使用使用Web Crypto保证请求状态requestState的完整性。该文件末尾整体只导出一个工厂函数createEverythingServerV2见 everything-server-v2.ts签名如下export interface EverythingServerV2Options { notify: { toolsChanged(): void; promptsChanged(): void; }; } export function createEverythingServerV2(options: EverythingServerV2Options) { // ... }这一设计使得 conformance worker 可以在每个无状态请求到来时创建全新服务器实例完全契合stateless2026-07-28协议路径。三、如何被消费conformance worker 中的接入点适配后的固件在 conformance/worker.ts 中被直接导入使用import { createEverythingServer } from ./everything-server.ts; import { createEverythingServerV2 } from ./vendor/everything-server-v2.ts;该 worker 同时托管了三代服务器实现注释说明见 worker.ts端点实现说明/mcp-handlerSDK v2 无状态createMcpHandler使用createEverythingServerV2固件/mcp-handler-legacy显式createLegacyMcpHandlerWorkerTransport旧版兼容有独立固件/mcp-agent保留的 SDK v1McpAgent旧版会话式实现其中/mcp-handler既是 2026-07-28 stateless 服务器 lane 的被测对象也是 legacy-compat lane 的兼容被测对象这正是 vendored fixture 存在的核心价值——让服务器实现以与线上完全一致的方式真实 Durable Object 存储、真实路由、真实传输在 workerd 内被测。四、关键实现细节requestState 完整性保护SEP-2322在 everything-server-v2.ts 中有一处精心设计的实现值得关注多轮往返MRTR请求状态完整性。核心背景代码注释原文含义requestState会往返经过客户端并作为攻击者可控的输入返回。SDK 将其视为不透明字符串且自身不提供保护因此任何让请求状态影响行为的服务器在签发时必须做完整性保护并在验证失败时拒绝。该固件使用 SDK 提供的createRequestStateCodec辅助函数mint用进程内随机密钥crypto.getRandomValues(new Uint8Array(32))对载荷做 HMAC 密封并带 TTLverify作为ServerOptions.requestState.verify挂入服务端接缝在被篡改或过期的状态到达时以-32602拒绝——这正是input-required-result-tampered-state一致性场景所断言的。代码中的一处 workerd 适配细节也值得记录workerd 禁止在模块作用域随机生成密钥因此密钥生成被推迟到请求处理器内的工厂函数中通过惰性单例sharedRequestStateCodec ?? ...实现整个 isolate 一把签名密钥见 everything-server-v2.ts。五、固件中的工具注册全景everything-server-v2.ts 中共 1530 行注册了大量测试工具覆盖 MCP 协议各能力面。核心工具清单与作用工具名验证的能力关键行为test_simple_text文本内容响应返回纯文本test_image_content图片内容响应返回 base64 的 1x1 红色 PNG 像素test_audio_content音频内容响应返回 base64 的最小 WAV 文件test_embedded_resource内嵌资源内容返回test://URI 的内嵌资源test_multiple_content_types多内容类型响应同时返回 text/image/resourcetest_error_handling错误响应处理主动抛出错误test_sampling服务器发起采样通过sampling/createMessage请求客户端 LLM 补全test_elicitation服务器发起 elicitation通过elicitation/create请求用户输入test_elicitation_sep1034_defaultsSEP-1034 默认值为 string/integer/number/enum/boolean 提供默认值test_tool_with_logging工具内日志执行期间发送多条notifications/messagetest_tool_with_progress进度通知仅在客户端提供progressToken时发送notifications/progress0/50/100test_reconnectionSSE 重连SEP-1699中断 SSE 流验证客户端重连test_x_mcp_headerSEP-2243 请求头校验手写 JSON Schema 保留x-mcp-header注解test_missing_capabilitySEP-2575 能力声明检查未声明sampling能力时驱动-32021拒绝test_streaming_elicitationSEP-2575 流式响应响应流不携带独立顶层 JSON-RPC 请求test_logging_toolSEP-2575 日志门控仅在请求携带_meta.logLevel时通过ctx.mcpReq.log输出日志此外服务器能力声明中还特意保留了已废弃的logging能力协议版本 2026-07-28 起按 SEP-2577 弃用目的是让 2025 时代的logging/setLevel一致性分支仍能协商该能力2026-07-28 路径则走每次请求的 envelope 并忽略此字段见 everything-server-v2.ts。六、更新 SDK Pin 的验证流程vendor/README.md 对更新上游 SDK 版本给出明确的操作流程获取固定 commit 处的源文件在记录的上游 commit 处拉取test/conformance/src/everythingServer.ts校验 SHA-256必须与记录的3a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852一致确保拿到的是未被篡改的精确上游内容检查无索引 diff与本地文件做 no-index diff即diff而非git diff审视差异仅移植 workerd 固件所需的注册变更只把与注册tool/prompt/resource 注册相关的必要变更同步进本地固件继续保持 Node/Express、Node 传输、会话注册表、Node 事件存储的移除边界。这一流程保证了本地固件与上游的可追溯性provenance与可审计性。七、将固件放进更大的测试框架中运行vendored fixture 并非孤立文件它处于仓库完整的 MCP conformance 测试体系之中详见 conformance/README.md。测试基准固定 pin 的官方评审器refereemodelcontextprotocol/conformance0.2.0-alpha.10在 package.json 中以npm:modelcontextprotocol/conformance-v20.2.0-alpha.10别名引入在wrangler dev中针对 Agents 实现运行。服务器 lane 矩阵conformance/run.sh中定义命令协议/生命周期端点当前结果test:conformance:server:handlerstateless2026-07-28/mcp-handler40 项全 cleantest:conformance:server:handler:legacy-compatlegacy 兼容、stateless/mcp-handler26 clean / 6 项预期失败test:conformance:server:handler:legacylegacy、sessionful/mcp-handler-legacy29 clean / 3 项预期失败test:conformance:server:mcp-agentlegacy、sessionful/mcp-agent29 clean / 3 项预期失败预期失败均有专用、非空的 baseline 文件如 baseline-server-handler.yml、baseline-client-2026-07-28.yml每条预期失败旁都有注释说明其实际影响及归属Agents / SDK v1 / alpha 评审器 fixture。stateless handler 无任何预期失败。本地运行方式cd packages/agents # 全部串行 pnpm run test:conformance # 服务器生命周期矩阵 pnpm run test:conformance:server:handler pnpm run test:conformance:server:handler:legacy-compat pnpm run test:conformance:server:handler:legacy pnpm run test:conformance:server:mcp-agent # 聚焦单个场景 bash conformance/run.sh server-handler --scenario server-statelessrun 脚本run.sh会占用端口前检查 Worker 端口默认 8788可用CONFORMANCE_WORKER_PORT覆盖与 inspector 端口默认端口10000是否已被占用拒绝在陈旧 worker 上测试并在退出时清理完整的 Wrangler/workerd 进程树。失败判定策略run-suite.mjs与 alpha 评审器在 suite 模式下不可靠的部分形成互补限定客户端并发client 6、server 1对衍生的 driver 与 mock server 做进程组清理客户端非零退出即使 wire 断言通过也计为失败服务器 WARNING 计为失败除非该场景在 baseline 中唯一的例外是client-sse-retry-timing的 reconnected slightly late 时序警告评审器自身判定可接受避免在 CI 加载抖动下产生 flake每个预期失败条目必须属于所选日期 lanestale baseline已通过却仍留在 baseline同样使 CI 失败。八、总结packages/agents/conformance/vendor/目录下的 vendored fixture 是整个 MCP 一致性体系的地基它以固定 commit SHA-256精确定格了官方 SDK v2 conformance 固件通过最小化适配剥离 Node/Express 依赖而保留全部注册行为导出单个工厂函数供 workerd conformance worker 复用并用Web Crypto落实 requestState 完整性SEP-2322。对开发者而言它既是理解 MCP 协议各能力面采样、elicitation、SSE 重连、能力声明校验等的浓缩范本也是一份如何在 workerd 中移植 Node 依赖型测试固件的可复现操作手册——更新 SDK pin 时严格按文档流程校验来源、审阅 diff、只移植注册变更即可保持整个一致性矩阵的可信与可维护。如需深入源码建议从 vendor/everything-server-v2.ts 的工具注册段入手对照 conformance/README.md 的 lane 矩阵与 run-suite.mjs 的判定逻辑即可完整还原该 fixture 从上游测试固件到workerd 内被测对象的整条链路。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考