顶层设计

本文定义 MCP 2026-07-28 的结构和核心抽象。同一个仓颉库提供 Client、Server、stdio 与 Streamable HTTP;Spire 专用适配留在库外扩展。协议要求以开发约定所列资料为准。

逐类型的本版覆盖状态和 C# 旧版类型排除项见协议模型核查。

项目结构

仓颉包依赖不能成环,因此只设置三个业务包。protocol 按公开类型拆分文件;后续文件可随能力实现增加,包名和依赖方向不变。

model_context_protocol/
├── cjpm.toml                 # static 库
├── src/
│   ├── protocol/             # package model_context_protocol.protocol
│   │   ├── mcp_protocol_versions.cj # 固定协议版本及元数据键
│   │   ├── request_id.cj
│   │   ├── json_rpc_message.cj
│   │   ├── json_rpc_message_with_id.cj
│   │   ├── json_rpc_request.cj
│   │   ├── json_rpc_notification.cj
│   │   ├── json_rpc_response.cj
│   │   ├── json_rpc_error.cj
│   │   ├── json_rpc_error_detail.cj
│   │   ├── json_rpc_message_context.cj
│   │   ├── message_reader.cj
│   │   ├── transport.cj   # 已建立连接的共同收发契约
│   │   └── ...               # 后续逐项实现 MCP 功能模型
│   ├── client/               # package model_context_protocol.client
│   │   ├── client_transport.cj # 建立连接并返回 Transport
│   │   ├── client.cj         # 用户入口与请求 API
│   │   ├── pending.cj        # 请求 ID 分配、响应关联、取消
│   │   ├── subscription.cj   # 订阅通知关联
│   │   ├── middleware.cj     # Client 消息与请求调用管道
│   │   └── stream_client_session_transport.cj # 客户端流收发
│   └── server/               # package model_context_protocol.server
│       ├── mcp_server.cj     # 用户入口与服务生命周期
│       ├── dispatch.cj       # 版本/能力校验与方法分发
│       ├── handlers.cj       # Tools/Resources/Prompts 等处理器契约
│       ├── middleware.cj     # 消息与请求处理管道
│       ├── context.cj        # 每次请求的上下文
│       ├── stream_server_transport.cj # 服务端流收发
│       └── stdio_server_transport.cj # 绑定标准输入输出
├── docs/
└── examples/                 # 将来的独立消费示例,不作为协议核心包

protocol 不导入 client 或 server;client 和 server 只导入 protocol,彼此不导入。三个包可以在同一个 cjpm 静态库模块内发布。共同收发接口 Transport 放在 protocol,具体流传输分别放在 client 和 server;客户端连接工厂 ClientTransport 放在 client。

flowchart BT
    Client[client] --> Protocol[protocol]
    Server[server] --> Protocol
    Spire[将来的 Spire 适配包] --> Client
    Spire --> Server

将来的 HTTP 传输实现同一个 Transport 契约,并复用 protocol 的消息模型与编解码。消息上的非序列化上下文保留 HTTP 单次请求及响应流的关联信息。

核心抽象

以下是职责契约,不是未经编译验证的仓颉函数签名。公开名称及参数类型在 API 设计时确定。

抽象 所属包 责任与边界
协议版本与能力模型 protocol 只接受 2026-07-28;表示每请求 _meta、服务端能力及扩展声明。
JSON-RPC 消息 protocol JsonRpcMessage 为共同基类,JsonRpcMessageWithId 承载必有 ID 的类型;具体类型为 JsonRpcRequest、JsonRpcNotification、JsonRpcResponse、JsonRpcError。RequestId 保留字符串/整数两种形态,通知没有 ID,错误响应允许缺省 ID。公开数据以只读属性呈现。
消息序列化 protocol 所有协议模型(以 Icon 为模板)使用类型化字段、类型化构造器和只读属性,同时实现 JsonSerializable 与 JsonDeserializable<自身类型>;直接用 JsonReader/JsonWriter 逐字段读写。读写辅助以 JsonReader/JsonWriter 扩展方法提供,JsonObject 字段校验以 JsonObject 扩展方法提供;模型与 JSON 值的整体转换由 McpJsonUtilities 收敛;仅 _meta、扩展对象、JSON Schema、arguments 与 structuredContent 等动态字段使用 JSON 值模型。不通过整条消息的字符串中转,不保留 JsonObject 作为模型存储。
Transport protocol 表示已建立连接的消息通道;通过 messageReader 提供入站消息,发送 JsonRpcMessage,并继承 Resource 管理生命周期。Client 与 Server 都持有此接口。
ChannelReader / ChannelWriter protocol 有界阻塞通道的独立读写端;read() 等待下一条消息,结束且已交付消息读完后返回 None。容量只约束数据值,关闭与失败不占容量、不阻塞;另提供 tryRead、tryWrite、waitClosed 和 isCompleted。
ClientTransport client 客户端连接工厂;负责建立 stdio 等连接并返回 Transport。对应 C# 的 IClientTransport,不承担消息收发。
JsonRpcMessageContext protocol 消息上的非序列化运行时上下文;可关联用于响应的传输,不代表协议会话。
stdio 流传输 client、server 两侧流传输各自处理逐行 JSON 消息、并发发送串行化和消息方向。服务端 StdioServerTransport 绑定标准流,客户端 StdioClientTransport 启动子进程。
MCP Client client 发起请求、关联响应、处理通知/订阅和取消;对用户提供按功能组织的 API。
MCP Server server 校验版本和能力、分发方法、管理并发请求和取消、产生规范结果与错误。
处理器 server 用户实现业务逻辑;不直接接触 stdio 和 JSON-RPC 封包。
服务端中间件 server 围绕消息收发或具体方法调用处理通用逻辑;与 stdio、HTTP 和 Spire 解耦。

协议对象与业务 API 分层:线格式保留 params、result、_meta 和扩展字段的真实结构;用户 API 不要求调用方自行拼 JSON-RPC 信封。Client 的方法级入参和返回值使用类型化模型,仅保留与 C# SendRequestAsync(JsonRpcRequest) 对应的低层线格式入口。动态 JSON 子树必须先由 JSON 解析器验证,不能把任意字符串直接插入输出。未在 schema 中定义的对象字段在解析时丢弃;可扩展内容通过 _meta、experimental、extensions 或 JSON Schema 子树表达。

传输契约

传输是可替换边界。Client 通过 ClientTransport.connect() 取得 Transport;Server 直接使用 Transport。这与 C# Core 的 IClientTransport 和 ITransport 分工一致;没有单独的 ServerTransport 接口。具体 stdio 进程选项和标准流选项属于各自实现。传输负责消息交付与关闭;版本校验、方法语义、能力判断、请求取消处理及 JSON-RPC 错误构造属于 Client/Server 与协议模型。

契约 必需操作 事件或结果
ClientTransport 提供名称、建立连接并返回 Transport stdio 实现负责启动子进程;连接建立后由返回的 Transport 管理收发和关闭。
Transport 提供 messageReader、发送 JsonRpcMessage、通过 Resource 释放 双侧共用;收到的消息可携带非序列化的 JsonRpcMessageContext。
ChannelReader 阻塞读取下一条消息;非阻塞 tryRead 传输结束后先交付已排队消息,再返回 None;传输故障在排空后显式报错。关闭/失败立即生效,不会被队列背压阻塞。
JsonRpcMessageContext 由传输附着在消息上,仅在本次消息处理期间使用 为 HTTP 单次请求或长时运行的 subscriptions/listen 关联响应通道;不能跨连接复用。

两侧都要区分正常关闭、请求取消、协议错误和传输故障;关闭后不能继续发送。Server 发送最终响应后,请求上下文结束;订阅在结束前可持续发送通知。传输实现须保证并发发送安全,不能让两个 JSON-RPC 消息的字节交错。

绑定 请求与通知交付 请求关联和取消
stdio 共用一对标准流,逐行读取与串行化写入;Client 管子进程,Server 管 stdin/stdout。 响应按 JSON-RPC ID 关联;订阅按 _meta 中的 subscription ID,进度按 progress token 关联;取消发送 notifications/cancelled。
后续 Streamable HTTP 每条 Client 消息单独 POST;请求响应是单个 JSON 或该请求的 SSE 流。 HTTP 请求/响应流就是传输上下文;关闭响应流表示取消,不发送 stdio 的取消通知。

Transport 表示已建立的消息通道,不表示 MCP 初始化会话,因此本版不暴露 C# 为旧版兼容保留的 SessionId。stdio 与 HTTP 各自承担绑定要求;HTTP 头只是镜像请求体元数据,请求体仍是协议字段的依据。stdio 上无法确定所属请求的通知按原消息交给 Client 处理,不凭到达顺序猜测归属。

Streamable HTTP(客户端已实现,服务端待设计)

当前实现范围:

  • client/http_client_transport.cj、client/http_client_transport_options.cj、client/streamable_http_client_transport.cj:每个 JSON-RPC 消息一次 POST;按 Content-Type 解析单 JSON 或 SSE;subscriptions/listen 的 SSE 响应流就是订阅通道;取消通过关闭该响应流实现,不发送 notifications/cancelled。
  • protocol/mcp_http_headers.cj、mcp_header_encoder.cj、sse_parser.cj(SSE 解码):框架无关的请求头映射、Base64 sentinel 与 SSE 读取。
  • 服务端由抽象 McpServer 与默认 McpServerImpl 驱动;server/streamable_http_server_transport.cj 只收发消息,server/streamable_http_handler.cj 实现 stdx HttpRequestHandler。调用方通过 McpServer.create(transport, options) 创建服务器,并把 Handler 注册到自己的 stdx HttpRequestDistributor。
  • 旧 HTTP+SSE 不提供;SSE 仅作为 Streamable HTTP 单请求的响应模式。

双侧处理管道

参考C# SDK 管道设计核查,Server 在传输接口之上提供消息与请求两级管道,公开入口为 McpServerOptions.filters;Client 当前负责请求关联与通知分发。共享的 JSON-RPC 消息及传输上下文由 protocol 定义,不需要 Spire 容器。

传输接收 → JSON-RPC 解码 → 内置协议校验 → 入站消息中间件
    → 方法分发/参数解析 → 该方法的请求中间件 → 业务处理器
    → 结果或错误构造 → 出站消息中间件 → 最终线格式校验
    → JSON-RPC 编码 → 传输发送
  • 消息中间件可处理所有入站请求/通知和出站响应/通知;请求中间件处理特定 MCP 方法,提供类型化参数与结果。通知不进入请求中间件。
  • 每个请求独立创建处理上下文,包含协议版本、Client 能力、请求 ID、方法、消息运行时上下文和取消状态。中间件可共享该次调用的本地数据,不得从前一次请求推断能力。
  • 第一个注册的中间件处于最外层;进入时先执行,返回时后执行。请求中间件可短路为合规结果或错误,但最终响应必须恰好一次。额外通知通过明确的发送入口产生,不通过重复调用下一处理器来伪造响应。
  • 内置协议校验先于用户中间件,出站线格式校验后于用户中间件。用户逻辑不能绕过版本、方向、ID、resultType 和订阅通知关联规则。
  • stdio/HTTP 的进程、HTTP 头、连接和认证细节留在各自传输适配层;与 MCP 消息或方法有关的日志、追踪、限流等可放在 Server 管道。

Client 内置请求 ID 分配、_meta 注入、响应关联及取消。当前未公开 Client filter API。

两侧管道都支持按注册顺序组合、每次调用独立上下文、异步处理、异常传播与取消。入站协议校验先于用户管道,出站协议校验后于用户管道;同一消息只进入一次发送路径。具体仓颉函数签名随 API 设计确定。

消息流与状态

  1. Client 通过 stdio ClientTransport 启动子进程并取得 Transport,推荐先调用 server/discover,确认对端支持 2026-07-28;不执行旧版 initialize 握手或自动降级。
  2. Client 发送请求时写入协议版本与客户端能力等必需 _meta,分配未占用的 ID,并登记待完成请求。服务端按每个请求独立检查版本与能力;不建立协议会话状态。
  3. stdio 实现以换行定界消息,再交给编解码器。两侧 Transport 收发消息;Client 按 ID 关联响应,Server 按方法分发请求。成功结果含 resultType;错误走 JSON-RPC 错误响应。
  4. 需要客户端输入时,Server 返回 input_required,Client 根据请求收集输入后以新 ID 重试原方法;不从 Server 向 Client 发送 JSON-RPC 请求。
  5. 订阅是持续中的 subscriptions/listen 请求。Client 用 io.modelcontextprotocol/subscriptionId 关联确认与后续通知;stdio 取消使用 notifications/cancelled。普通请求的进度通知按 progress token 关联。
  6. 关闭时 Client 先关闭子进程 stdin,等待退出,再按策略终止超时进程。EOF、子进程退出或通道失败应使所有未完成请求显式失败,并释放订阅;自动重启与重试策略由 Client API 另行设计,不隐式重放可能有副作用的调用。

“无会话”描述协议:请求不依赖 initialize 建立的状态。Client 为并发请求维护的待完成表、Server 运行中的处理任务和 stdio 子进程生命周期,是本地运行状态,不是 MCP 协议会话。

首期必需行为

  • server/discover:Server 必须提供,且只列出实际支持的版本和能力;Client 可用它提前验证对端。
  • 版本错误:不支持的版本返回规范定义的 UnsupportedProtocolVersionError 及支持版本列表,不把版本错误误报为未知方法。
  • stdio 方向:Client 只向 Server 发请求和通知;Server 只向 Client 发响应和通知。stdout 仅含协议消息,诊断信息写 stderr。
  • 消息校验:验证 JSON-RPC 2.0 结构、ID、请求元数据、结果类型及方法所需字段;区分解析错误、无效请求、未知方法与业务错误。
  • 并发与生命周期:发送串行化;响应按 ID 关联,不依赖完成顺序;取消、EOF 和异常关闭都有确定的收尾行为。

首期完整目标按开发约定覆盖 stdio 适用的未弃用核心能力:Server 的 Tools、Resources、Prompts;Client 的 Elicitation;以及完成、分页、缓存、进度、取消、订阅和 MRTR 等共用机制。MRTR 保留规范要求的输入请求结构;Roots、Sampling、Logging 已弃用,不提供对应的内置业务能力。Tasks 等官方扩展及 Web/HTTP 留到后续阶段。

这个目标分阶段交付。尚未实现的能力不出现在 server/discover,其方法调用返回合适的协议错误;Client 也不能假定对端一定实现可选能力。每项能力须同时具备类型/编解码、处理逻辑和互操作验证,才能标记完成。阶段交付不豁免已提供行为的 2026-07-28 规范及 schema 必需要求;具体符合性门槛见开发约定。

验证与实施顺序

  1. 将 cjpm.toml 调整为静态库,建立三个包和编译级依赖检查;移除初始化模板的 main。这一步随首次代码实现进行。
  2. 实现 JSON-RPC 消息模型、json.stream 编解码、共同 Transport 契约、客户端连接工厂和 stdio 行定界;用同版本 schema 中的示例与畸形消息验证。
  3. 实现 stdio 的客户端连接工厂和两侧 Transport,以及 Client 的请求关联、版本探测和关闭、Server 的版本校验、server/discover、方法分发与两级中间件管道。
  4. 先完成 Tools,再完成 Resources/Prompts 和 Client Elicitation;补齐完成、分页、缓存、进度、取消、MRTR 与订阅,并验证交错消息和并发场景。
  5. 与 C# SDK 指定为 2026-07-28 的 Client/Server 交叉测试 stdio 双向互操作;再整理公开 API 与示例。

每一步都应能独立构建和测试。具体公开 API 在代码实现前另写设计,不凭本目录草图推断已经支持的能力。

依据