ModelContextProtocol C SDK 中的采样功能实现详解

采样功能概述

ModelContextProtocol C# SDK 提供了强大的采样功能，允许客户端与服务器之间进行高效的采样数据交换。采样功能是协议的重要组成部分，它使得客户端能够声明对采样操作的支持，并处理来自服务器的采样请求。

客户端采样能力声明

要在客户端启用采样支持，开发者需要在创建 McpClient 实例时明确声明采样能力。这通过 ClientCapabilities 中的 SamplingCapability 属性实现：

var mcpClient = await McpClientFactory.CreateAsync(
    transport,
    new McpClientOptions { 
        Capabilities = new ClientCapabilities { 
            Sampling = new SamplingCapability() 
        } 
    });

采样处理器的实现

SamplingCapability 类包含一个关键的 SamplingHandler 属性，这是实现采样功能的核心。开发者需要为这个属性提供一个合适的委托来处理采样请求。

如果开发者已经实现了 IChatClient 接口，可以使用 SDK 提供的便捷方法创建采样处理器：

SamplingHandler = samplingClient.CreateSamplingHandler()

这种方法会自动将服务器发送到客户端的请求路由到 IChatClient 实现，并将响应自动编组并转发回服务器。

传输协议注意事项

采样功能支持多种传输协议，包括：

1. SSE (Server-Sent Events)：需要正确配置 SseClientTransport
2. HTTP 流式传输：适用于流式场景
3. 标准输入输出：传统交互方式

在使用 SSE 传输时，开发者需要特别注意确保客户端能力能够正确传播到服务器端。一个常见的错误是在构造函数中注入 IMcpServer 而不是作为参数传递，这可能导致获取到错误的服务器实例（如 stdio 相关的服务器实例）。

最佳实践

1. 明确传输协议选择：根据应用场景选择合适的传输协议，SSE 适合需要服务器推送的场景，HTTP 流式适合大数据量传输。

2. 正确注入服务：确保 IMcpServer 以正确的方式注入，避免获取到不期望的服务器实例。

3. 采样处理器优化：在实现采样处理器时，考虑性能因素，特别是对于高频采样场景。

4. 错误处理：完善采样过程中的错误处理机制，确保系统稳定性。

常见问题解决

1. 客户端能力未传播：检查传输层配置，确保能力声明正确传递。

2. 空引用异常：验证 ClientCapabilities 是否已正确初始化，特别是在使用 SSE 传输时。

3. 采样请求未处理：确认 SamplingHandler 已正确设置并实现了预期的采样逻辑。

通过遵循这些指导原则，开发者可以充分利用 ModelContextProtocol C# SDK 的采样功能，构建高效、可靠的应用程序。