ModelContextProtocol TypeScript SDK 中StreamableHTTPClientTransport的请求头传递问题解析

问题背景

在使用ModelContextProtocol的TypeScript SDK（版本1.11.2）时，开发者发现通过StreamableHTTPClientTransport构造函数设置的请求头（headers）无法正确传递到服务端。这是一个典型的HTTP客户端配置问题，会影响需要认证或特殊请求头的应用场景。

问题现象

开发者尝试按照以下方式初始化StreamableHTTPClientTransport：

const transport = new StreamableHTTPClientTransport(
    new URL(serverUrl),
    {
        sessionId: sessionId
    },
    {
        requestInit: {
            headers: {
                "Authorization": "Bearer " + token,
            }
        }
    }
);

然而实际请求到达服务端时，预期的Authorization头信息却丢失了。通过包装fetch函数进行调试，确认请求头确实没有被包含在最终的HTTP请求中。

问题根源

经过分析，这个问题实际上是由于构造函数参数传递错误导致的。StreamableHTTPClientTransport的构造函数设计如下：

1. 第一个参数：服务器URL
2. 第二个参数：配置对象（包含sessionId和requestInit等选项）

开发者错误地将配置对象拆分成了两个参数（第二个参数只包含sessionId，第三个参数包含requestInit），导致requestInit配置没有被正确处理。

正确用法

正确的初始化方式应该是将所有配置选项合并到第二个参数中：

const transport = new StreamableHTTPClientTransport(
    new URL(serverUrl),
    {
        sessionId: sessionId,
        requestInit: {
            headers: {
                "Authorization": "Bearer " + token,
            }
        }
    }
);

技术细节

在HTTP客户端实现中，请求头的处理通常遵循以下流程：

1. 构造函数接收配置参数
2. 内部将配置的headers与默认headers合并
3. 在创建实际HTTP请求时应用这些headers

当参数传递错误时，配置的headers会被忽略，只使用默认headers，导致开发者设置的认证头丢失。

最佳实践

1. 参数验证：在使用SDK时，应仔细查阅API文档，确认构造函数的参数结构
2. 调试技巧：可以通过包装fetch方法或使用网络抓包工具验证实际发出的请求
3. 类型检查：TypeScript项目应充分利用类型提示，避免参数传递错误

总结

这个问题虽然看似简单，但反映了SDK使用中的一个常见陷阱。正确的参数传递方式确保了请求头能够按预期工作，对于需要认证的API调用至关重要。开发者在遇到类似问题时，应该首先检查参数结构是否符合API设计预期。