MCP SDK protocol negotiation
MCP SDK 协议协商
MCP servers use different protocol revisions. A tool bridge that implements discovery and execution around an older SDK can omit modern request headers, subscription setup, or protocol validation.
English
Problem
MCP servers use different protocol revisions. A tool bridge that implements discovery and execution around an older SDK can omit modern request headers, subscription setup, or protocol validation.
Decision
dsh-mcp-client uses the official TypeScript client 2.0.0 with automatic protocol negotiation. The SDK owns modern discovery and legacy initialization, transport-specific negotiation, list-change subscriptions, pagination, request headers, cancellation, and output validation. The bridge uses high-level listTools and callTool, passing the complete discovered definition to each call.
The bridge retains server-qualified names, atomic registration, and durable image admission. Servers without a tools capability publish no tools. Discovery failures preserve the last successful registration; duplicate names still reject the new generation. Malformed cursor chains stop at the SDK page limit; the bridge does not add a parallel pagination implementation.
The supervisor owns each transport before the SDK attaches it to its Client. Disposal closes an unattached transport to cancel negotiation, then awaits the attempt so the SDK can reap its probe. A failed probe has no Client close event; after SDK cleanup it uses the normal retry budget. Attached connections retain the close-event barrier that prevents overlapping server processes.
The shared result adapter passes the original ToolExecution to each provider callback, preserving its Agent identity and cancellation. Native Cua Driver results use the SDK's public spec-type validation before canonical projection; the adapter does not accept a separate permissive result format.
The tool bridge note retains the independent naming, scope, and image decisions. This note changes its SDK realization without replacing those decisions.
Alternatives considered
Keep raw requests for compatibility. This preserves permissive malformed-result handling but bypasses SDK-owned modern headers and schema validation. Protocol-valid outputs take priority over legacy toolResult substitutes.
Implement modern protocol behavior in the bridge. This duplicates maintained SDK behavior and creates an additional compatibility implementation.
Consequences
Stdio negotiation starts a disposable probe process and waits for its exit before starting the serving process. The SDK bounds discovery with its page limit, and malformed results fail before projection. Valid text, canonical JSON, image admission, cancellation, and registration ownership remain bridge contracts. Shipped profiles include shared resource access; elicitation, MCP prompts, and task execution remain unsupported.
Real-SDK lifecycle tests verify probe disposal, process ordering, HTTP probe retry budgets, and failed stdio spawns. The connection-supervisor tests retain attached-transport close barriers and bounded failure behavior.
中文
问题
MCP 服务器使用不同协议版本。围绕旧版 SDK 实现发现与执行的工具桥接器可能遗漏现代请求 header、订阅建立或协议校验。
决策
dsh-mcp-client 使用官方 TypeScript client 2.0.0 并自动协商协议。SDK 负责现代发现与旧版初始化、按传输方式协商、列表变化订阅、分页、请求 header、取消与输出校验。桥接器使用高层 listTools 和 callTool，并向每次调用传递完整的发现定义。
桥接器保留服务器限定名称、原子注册和持久图片接纳。未声明 tools 能力的服务器不发布工具。发现失败保留上一次成功注册；重复名称仍拒绝新注册代。格式错误的游标链会在 SDK 页数上限处停止；桥接器不增加并行的分页实现。
监督器在 SDK 将传输绑定到 Client 之前就持有该传输。释放时先关闭未绑定的传输以取消协商，再等待连接尝试结束，让 SDK 回收探测进程。失败的探测不会产生 Client 关闭事件；SDK 清理完成后，它使用正常重试预算。已绑定连接保留关闭事件屏障，防止服务器进程重叠。
共享结果适配函数向每个提供方回调传递原始 ToolExecution，保留其 Agent 身份和取消信号。原生 Cua Driver 的结果会先通过 SDK 公开的规范类型校验，再生成规范值投影；适配函数不接受另一种宽松结果格式。
工具桥接记录 保留独立的命名、作用域与图片决策。本记录调整其 SDK 实现，不替代这些决策。
考虑过的替代方案
为兼容性保留原始请求。 这保留了宽松的错误结果处理，却绕过 SDK 负责的现代 header 与 schema 校验。有效协议输出优先于旧式 toolResult 替代结果。
在桥接器内实现现代协议行为。 这会重复已维护的 SDK 行为，并增加一份兼容性实现。
影响
Stdio 协商启动可释放的探测进程，并等待其退出后才启动实际服务进程。SDK 通过页数上限约束发现，格式错误的结果会在投影前失败。有效文本、规范 JSON、图片接纳、取消与注册归属仍是桥接器的约定。随附 profile 包含共享资源访问；elicitation、MCP 提示模板及任务执行仍不受支持。
真实 SDK 生命周期测试验证探测释放、进程顺序、HTTP 探测重试预算及 stdio 启动失败。连接监督器测试保留已绑定传输的关闭屏障与有界失败行为。