Effect MCP Server 多协议版本支持解析2024-11-05 与 2025-03-26 协议适配器实战指南【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本篇技术指南聚焦于 Effect 包unstable/ai模块中 MCPModel Context Protocol服务器的协议版本支持能力。根据仓库变更说明.changeset/pre/mcp-protocol-versions.mdEffect 的 MCP 服务器现通过版本特定的协议适配器version-specific protocol adapters同时支持 2024-11-05 与 2025-03-26 两个 RPC 协议修订版本。读者读完本文后将理解协议适配器的内部结构、两个版本 Schema 的差异细节、运行时协商机制并能在McpServer的 stdio 与 Streamable HTTP 两种传输形态下正确配置和使用多协议支持。MCP 协议版本演进与 Effect 的支持矩阵Model Context Protocol 的协议规范会随修订版本RPC revision演进。Effect 在unstable/ai模块中将每一个协议修订版本封装为独立的 Schema 与适配器实现允许单个服务器进程在多个协议版本间进行运行时协商。从 McpProtocol.ts 的类型定义可见本仓库实现的协议版本全集为export type ProtocolVersion 2024-11-05 | 2025-03-26 | 2025-06-18 | 2025-11-25 | 2026-07-28其中 2024-11-05 与 2025-03-26 是本次变更说明中明确提及的两个版本二者均属于有状态Stateful运行时——即使用初始化握手与服务器管理的会话session来维护协议生命周期与后续 2026-07-28 这种基于请求级元数据的无状态Stateless运行时形成对照McpProtocol.tsexport type StatefulProtocolVersion ExcludeProtocolVersion, 2026-07-28每个版本都通过McpProtocol.ProtocolAdapter暴露为可独立选用的适配器常量例如McpProtocol.tsexport const v2024_11_05: ProtocolAdapter2024-11-05, StatefulRuntimeDescriptor export const v2025_03_26: ProtocolAdapter2025-03-26, StatefulRuntimeDescriptor版本特定协议适配器的内部结构协议适配器是本次变更的核心抽象。AnyProtocolAdapter接口McpProtocol.ts规定了每个版本适配器必须提供的操作面protocolVersion该适配器对应的版本字符串runtime运行时描述符StatefulRuntimeDescriptor或StatelessRuntimeDescriptor其中TransportPolicyMcpProtocol.ts声明了jsonRpc.acceptsBatches是否接受 JSON-RPC 批量请求与http.requiresVersionHeader等传输行为clientRpcs/clientNotificationRpcs客户端侧请求与通知的 RPC 组serverRequestRpcs/serverNotificationRpcs服务器侧请求与通知的 RPC 组payloadCodecs针对单个 RPC 的载荷编解码器其签名McpProtocol.ts为decode/encode两个返回Effect的函数编码失败统一归为Schema.SchemaErrorinstallHandlers将协议请求安装到目标处理器makeReverseClient构造反向客户端用于采样、roots 列表等服务器发起的调用projectNotification/normalizeCancellation通知投影与取消归一化。该接口的设计意图是核心运行时只处理规范化的 MCP 域模型而每个版本的差异字段名、能力集合、内容块类型全部收敛在适配器内部完成投影与反投影。内部实现位于 internal/mcpProtocol/v2024_11_05.ts 与 internal/mcpProtocol/v2025_03_26.ts对应的版本 Schema 则分别维护在 internal/mcpSchema/v2024_11_05.ts 与 internal/mcpSchema/v2025_03_26.ts。2024-11-05 与 2025-03-26 的 Schema 差异两个版本的 Schema 以前版本为基、后版本增量扩展的方式组织v2025_03_26.ts通过Previous.*引用 2024-11-05 的定义并叠加新增字段。从源码可以确认以下差异服务器能力ServerCapabilities2025-03-26 在继承 2024-11-05 全部能力字段的基础上新增completions能力v2025_03_26.tsexport const ServerCapabilities Schema.Struct({ ...Previous.ServerCapabilities.fields, completions: optional(Schema.Struct({})) })内容块ContentBlock2025-03-26 新增AudioContent含type: audio、data、mimeType、可选annotations并扩展了PromptOrToolContent联合体v2025_03_26.ts。相应地2024-11-05 适配器在投影内容时会将audio与resource_link类型明确判为UnsupportedByProtocolinternal/mcpProtocol/v2024_11_05.ts这是旧协议不识别新内容类型的直接体现。工具注解ToolAnnotations2025-03-26 为Tool增加了可选的annotations字段包含title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint五个布尔/字符串提示v2025_03_26.ts。新增 RPC 与通知2025-03-26 的客户端请求组新增prompts/getGetPrompt、sampling/createMessageCreateMessage含modelPreferences、systemPrompt、includeContext、temperature、maxTokens等采样参数、notifications/progressProgressNotification等操作v2025_03_26.ts服务器侧请求组也相应引入CreateMessage、ListRootsv2025_03_26.ts。initializeRPC 的载荷在两个版本中都包含protocolVersion、capabilities、clientInfo字段v2025_03_26.ts这是协商机制的数据基础。协议版本协商与回退机制MCP 服务器不会同时用多个协议响应同一客户端而是在运行时根据客户端声明选择最合适的适配器。协商的核心逻辑位于 internal/mcpRuntime.tsexport const selectStatefulProtocol (protocols, offeredVersion) protocols.find((p) p.runtime._tag Stateful p.protocolVersion offeredVersion) ?? protocols.find((p) p.runtime._tag Stateful)即优先精确匹配客户端在initialize中提供的版本字符串若无精确匹配则回退到协议列表中第一个有状态协议作为兼容默认值。在 stdio 传输下序列化层会解析每条入站 JSON-RPC 帧遇到initialize消息时提取其protocolVersion并调用上述选择函数McpServer.ts。除版本协商外运行时还统一处理跨版本差异例如 2024-11-05 时期遗留的资源不存在错误码-32002被定义为兼容常量internal/mcpProtocol.ts反向操作sampling、roots在客户端未声明对应能力时会返回McpReverseOperationUnsupported错误并附上原因说明internal/mcpProtocol/v2024_11_05.ts。在 McpServer 中启用多协议支持所有 MCP 服务器入口run、layerStdio、layerHttp都要求通过protocols参数显式传入一个非空协议适配器数组McpServer.ts。以 stdio 形态为例McpServer.tsimport { McpServer, McpProtocol } from effect/unstable/ai McpServer.layerStdio({ name: my-server, version: 1.0.0, protocols: [ McpProtocol.v2024_11_05, McpProtocol.v2025_03_26 ] })传入多个适配器后服务器会在请求到达时按上文协商规则自动选择版本。在 stdio 序列化层McpServer.ts中JSON-RPC 批量请求batch是否被接受取决于当前已协商适配器的transport.jsonRpc.acceptsBatches声明若适配器不接受批量或批量帧包含initialize服务器会返回INVALID_REQUEST错误错误码为McpSchema.INVALID_REQUEST_ERROR_CODE。对于 HTTP 形态layerHttpMcpServer.ts始终实现单端点 Streamable HTTP 拓扑POST 提供 JSON-RPC 服务仅通知类请求返回202。需要特别留意的是文档注释明确说明在layerHttp中使用v2024_11_05是一种自定义兼容传输——它只提供该版本 Schema 的单端点 Streamable HTTP 兼容实现并不实现历史上 2024-11-05 规范中的双端点 HTTPSSE 传输、GET SSE 事件流、事件恢复、会话过期或客户端会话终止等行为McpServer.ts。因此若目标是现代 MCP 客户端且需要 2025 版协议能力completions、音频内容、工具注解、sampling 等应优先使用v2025_03_26若必须兼容基于 2024-11-05 的旧客户端可将其加入protocols数组以便协商回退但对 Streamable HTTP 的历史双端点语义需保持预期管理。传输行为与客户端兼容要点stdio采用 NDJSON 帧与application/json-rpc内容类型McpServer.ts服务器可通过layerStdio或run挂载批量请求的支持随协商出的适配器而变。HTTPlayerHttp依赖已有的HttpRouter仅注册单个路径端点allowedOrigins参数用于校验Origin头——携带Origin的请求必须精确命中白名单无 Origin 的非浏览器客户端保持有效不支持的 HTTP 方法返回405未知现代 RPC 方法返回404McpServer.ts。错误码约定请求元数据缺失、MCP-Protocol-Version头缺失或不匹配等情况无状态路径会以400返回 JSON-RPC 错误internal/mcpRuntime.ts错误码使用INVALID_PARAMS_ERROR_CODE。小结本次变更说明.changeset/pre/mcp-protocol-versions.md所描述的版本特定协议适配器机制在 Effect 源码中体现为一套完整的多版本隔离架构每个协议修订版拥有独立的 Schemainternal/mcpSchema/与适配器实现internal/mcpProtocol/核心运行时只维护规范化域模型版本差异通过适配器投影收敛最终由McpServer的protocols参数以运行时协商的方式对客户端透明地提供服务。掌握该机制后开发者可以在同一 MCP 服务器上平滑承接 2024-11-05 与 2025-03-26 两代客户端并据其能力差异合理选择默认协议与回退策略。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Effect MCP Server 多协议版本支持解析：2024-11-05 与 2025-03-26 协议适配器实战指南
Effect MCP Server 多协议版本支持解析2024-11-05 与 2025-03-26 协议适配器实战指南【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本篇技术指南聚焦于 Effect 包unstable/ai模块中 MCPModel Context Protocol服务器的协议版本支持能力。根据仓库变更说明.changeset/pre/mcp-protocol-versions.mdEffect 的 MCP 服务器现通过版本特定的协议适配器version-specific protocol adapters同时支持 2024-11-05 与 2025-03-26 两个 RPC 协议修订版本。读者读完本文后将理解协议适配器的内部结构、两个版本 Schema 的差异细节、运行时协商机制并能在McpServer的 stdio 与 Streamable HTTP 两种传输形态下正确配置和使用多协议支持。MCP 协议版本演进与 Effect 的支持矩阵Model Context Protocol 的协议规范会随修订版本RPC revision演进。Effect 在unstable/ai模块中将每一个协议修订版本封装为独立的 Schema 与适配器实现允许单个服务器进程在多个协议版本间进行运行时协商。从 McpProtocol.ts 的类型定义可见本仓库实现的协议版本全集为export type ProtocolVersion 2024-11-05 | 2025-03-26 | 2025-06-18 | 2025-11-25 | 2026-07-28其中 2024-11-05 与 2025-03-26 是本次变更说明中明确提及的两个版本二者均属于有状态Stateful运行时——即使用初始化握手与服务器管理的会话session来维护协议生命周期与后续 2026-07-28 这种基于请求级元数据的无状态Stateless运行时形成对照McpProtocol.tsexport type StatefulProtocolVersion ExcludeProtocolVersion, 2026-07-28每个版本都通过McpProtocol.ProtocolAdapter暴露为可独立选用的适配器常量例如McpProtocol.tsexport const v2024_11_05: ProtocolAdapter2024-11-05, StatefulRuntimeDescriptor export const v2025_03_26: ProtocolAdapter2025-03-26, StatefulRuntimeDescriptor版本特定协议适配器的内部结构协议适配器是本次变更的核心抽象。AnyProtocolAdapter接口McpProtocol.ts规定了每个版本适配器必须提供的操作面protocolVersion该适配器对应的版本字符串runtime运行时描述符StatefulRuntimeDescriptor或StatelessRuntimeDescriptor其中TransportPolicyMcpProtocol.ts声明了jsonRpc.acceptsBatches是否接受 JSON-RPC 批量请求与http.requiresVersionHeader等传输行为clientRpcs/clientNotificationRpcs客户端侧请求与通知的 RPC 组serverRequestRpcs/serverNotificationRpcs服务器侧请求与通知的 RPC 组payloadCodecs针对单个 RPC 的载荷编解码器其签名McpProtocol.ts为decode/encode两个返回Effect的函数编码失败统一归为Schema.SchemaErrorinstallHandlers将协议请求安装到目标处理器makeReverseClient构造反向客户端用于采样、roots 列表等服务器发起的调用projectNotification/normalizeCancellation通知投影与取消归一化。该接口的设计意图是核心运行时只处理规范化的 MCP 域模型而每个版本的差异字段名、能力集合、内容块类型全部收敛在适配器内部完成投影与反投影。内部实现位于 internal/mcpProtocol/v2024_11_05.ts 与 internal/mcpProtocol/v2025_03_26.ts对应的版本 Schema 则分别维护在 internal/mcpSchema/v2024_11_05.ts 与 internal/mcpSchema/v2025_03_26.ts。2024-11-05 与 2025-03-26 的 Schema 差异两个版本的 Schema 以前版本为基、后版本增量扩展的方式组织v2025_03_26.ts通过Previous.*引用 2024-11-05 的定义并叠加新增字段。从源码可以确认以下差异服务器能力ServerCapabilities2025-03-26 在继承 2024-11-05 全部能力字段的基础上新增completions能力v2025_03_26.tsexport const ServerCapabilities Schema.Struct({ ...Previous.ServerCapabilities.fields, completions: optional(Schema.Struct({})) })内容块ContentBlock2025-03-26 新增AudioContent含type: audio、data、mimeType、可选annotations并扩展了PromptOrToolContent联合体v2025_03_26.ts。相应地2024-11-05 适配器在投影内容时会将audio与resource_link类型明确判为UnsupportedByProtocolinternal/mcpProtocol/v2024_11_05.ts这是旧协议不识别新内容类型的直接体现。工具注解ToolAnnotations2025-03-26 为Tool增加了可选的annotations字段包含title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint五个布尔/字符串提示v2025_03_26.ts。新增 RPC 与通知2025-03-26 的客户端请求组新增prompts/getGetPrompt、sampling/createMessageCreateMessage含modelPreferences、systemPrompt、includeContext、temperature、maxTokens等采样参数、notifications/progressProgressNotification等操作v2025_03_26.ts服务器侧请求组也相应引入CreateMessage、ListRootsv2025_03_26.ts。initializeRPC 的载荷在两个版本中都包含protocolVersion、capabilities、clientInfo字段v2025_03_26.ts这是协商机制的数据基础。协议版本协商与回退机制MCP 服务器不会同时用多个协议响应同一客户端而是在运行时根据客户端声明选择最合适的适配器。协商的核心逻辑位于 internal/mcpRuntime.tsexport const selectStatefulProtocol (protocols, offeredVersion) protocols.find((p) p.runtime._tag Stateful p.protocolVersion offeredVersion) ?? protocols.find((p) p.runtime._tag Stateful)即优先精确匹配客户端在initialize中提供的版本字符串若无精确匹配则回退到协议列表中第一个有状态协议作为兼容默认值。在 stdio 传输下序列化层会解析每条入站 JSON-RPC 帧遇到initialize消息时提取其protocolVersion并调用上述选择函数McpServer.ts。除版本协商外运行时还统一处理跨版本差异例如 2024-11-05 时期遗留的资源不存在错误码-32002被定义为兼容常量internal/mcpProtocol.ts反向操作sampling、roots在客户端未声明对应能力时会返回McpReverseOperationUnsupported错误并附上原因说明internal/mcpProtocol/v2024_11_05.ts。在 McpServer 中启用多协议支持所有 MCP 服务器入口run、layerStdio、layerHttp都要求通过protocols参数显式传入一个非空协议适配器数组McpServer.ts。以 stdio 形态为例McpServer.tsimport { McpServer, McpProtocol } from effect/unstable/ai McpServer.layerStdio({ name: my-server, version: 1.0.0, protocols: [ McpProtocol.v2024_11_05, McpProtocol.v2025_03_26 ] })传入多个适配器后服务器会在请求到达时按上文协商规则自动选择版本。在 stdio 序列化层McpServer.ts中JSON-RPC 批量请求batch是否被接受取决于当前已协商适配器的transport.jsonRpc.acceptsBatches声明若适配器不接受批量或批量帧包含initialize服务器会返回INVALID_REQUEST错误错误码为McpSchema.INVALID_REQUEST_ERROR_CODE。对于 HTTP 形态layerHttpMcpServer.ts始终实现单端点 Streamable HTTP 拓扑POST 提供 JSON-RPC 服务仅通知类请求返回202。需要特别留意的是文档注释明确说明在layerHttp中使用v2024_11_05是一种自定义兼容传输——它只提供该版本 Schema 的单端点 Streamable HTTP 兼容实现并不实现历史上 2024-11-05 规范中的双端点 HTTPSSE 传输、GET SSE 事件流、事件恢复、会话过期或客户端会话终止等行为McpServer.ts。因此若目标是现代 MCP 客户端且需要 2025 版协议能力completions、音频内容、工具注解、sampling 等应优先使用v2025_03_26若必须兼容基于 2024-11-05 的旧客户端可将其加入protocols数组以便协商回退但对 Streamable HTTP 的历史双端点语义需保持预期管理。传输行为与客户端兼容要点stdio采用 NDJSON 帧与application/json-rpc内容类型McpServer.ts服务器可通过layerStdio或run挂载批量请求的支持随协商出的适配器而变。HTTPlayerHttp依赖已有的HttpRouter仅注册单个路径端点allowedOrigins参数用于校验Origin头——携带Origin的请求必须精确命中白名单无 Origin 的非浏览器客户端保持有效不支持的 HTTP 方法返回405未知现代 RPC 方法返回404McpServer.ts。错误码约定请求元数据缺失、MCP-Protocol-Version头缺失或不匹配等情况无状态路径会以400返回 JSON-RPC 错误internal/mcpRuntime.ts错误码使用INVALID_PARAMS_ERROR_CODE。小结本次变更说明.changeset/pre/mcp-protocol-versions.md所描述的版本特定协议适配器机制在 Effect 源码中体现为一套完整的多版本隔离架构每个协议修订版拥有独立的 Schemainternal/mcpSchema/与适配器实现internal/mcpProtocol/核心运行时只维护规范化域模型版本差异通过适配器投影收敛最终由McpServer的protocols参数以运行时协商的方式对客户端透明地提供服务。掌握该机制后开发者可以在同一 MCP 服务器上平滑承接 2024-11-05 与 2025-03-26 两代客户端并据其能力差异合理选择默认协议与回退策略。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
