企业官网建设流程全解析

深入解析 Agents 仓库的 MCP SDK v2 Conformance Fixture：everything-server-v2.ts 的 workerd 移植与一致性验证

【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents

在 Cloudflare Agents 生态中，MCP（Model 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/server@2.0.0
• 固定 commit：cc4b41617ce3601b1290d67216ea0b194a3cd9ac
• 上游源文件：test/conformance/src/everythingServer.ts
• 源文件 SHA-256：3a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852

这一固件被用作"无状态服务器"（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 registry）；
• Node 事件存储（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 可以在每个无状态请求到来时创建全新服务器实例，完全契合"stateless（2026-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-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 密封，并带 TTL；
• verify：作为ServerOptions.requestState.verify挂入服务端接缝，在被篡改或过期的状态到达时以-32602拒绝——这正是input-required-result-tampered-state一致性场景所断言的。

代码中的一处 workerd 适配细节也值得记录：workerd 禁止在模块作用域随机生成密钥，因此密钥生成被推迟到请求处理器内的工厂函数中，通过惰性单例sharedRequestStateCodec ??= ...实现"整个 isolate 一把签名密钥"（见 everything-server-v2.ts）。

五、固件中的工具注册全景

everything-server-v2.ts 中共 1530 行，注册了大量测试工具，覆盖 MCP 协议各能力面。核心工具清单与作用：

此外，服务器能力声明中还特意保留了已废弃的logging能力（协议版本 2026-07-28 起按 SEP-2577 弃用），目的是让 2025 时代的logging/setLevel一致性分支仍能协商该能力；2026-07-28 路径则走每次请求的 envelope 并忽略此字段（见 everything-server-v2.ts）。

六、更新 SDK Pin 的验证流程

vendor/README.md 对更新上游 SDK 版本给出明确的操作流程：

1. 获取固定 commit 处的源文件：在记录的上游 commit 处拉取test/conformance/src/everythingServer.ts；
2. 校验 SHA-256：必须与记录的3a94417774fa20b17971e8162f9865b1cefd2650c7d88fdcd17f971d91213852一致，确保拿到的是未被篡改的精确上游内容；
3. 检查无索引 diff：与本地文件做 no-index diff（即diff而非git diff），审视差异；
4. 仅移植 workerd 固件所需的注册变更：只把与注册（tool/prompt/resource 注册）相关的必要变更同步进本地固件，继续保持 Node/Express、Node 传输、会话注册表、Node 事件存储的移除边界。

这一流程保证了本地固件与上游的可追溯性（provenance）与可审计性。

七、将固件放进更大的测试框架中运行

vendored fixture 并非孤立文件，它处于仓库完整的 MCP conformance 测试体系之中（详见 conformance/README.md）。

测试基准：固定 pin 的官方评审器（referee）@modelcontextprotocol/conformance@0.2.0-alpha.10（在 package.json 中以npm:@modelcontextprotocol/conformance-v2@0.2.0-alpha.10别名引入），在wrangler dev中针对 Agents 实现运行。

服务器 lane 矩阵（conformance/run.sh中定义）：

预期失败均有专用、非空的 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-stateless

run 脚本（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）；
• 每个预期失败条目必须属于所选日期 lane，stale 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