ModelContextProtocol C SDK 中工具调用问题的分析与解决

问题背景

在使用 ModelContextProtocol C# SDK 开发 MCP 服务器程序时，开发者可能会遇到工具方法无法被正确调用的常见问题。具体表现为当通过 Stdio 传输层发送 JSON-RPC 请求时，服务器返回"方法不存在或不可用"的错误。

典型错误场景

开发者通常会尝试直接构造类似以下的 JSON-RPC 请求：

{
  "jsonrpc": "2.0",
  "method": "GetProject",
  "params": {
    "id": 22
  },
  "id": 1
}

或者在工具类中定义了如下代码：

[McpServerToolType]
public class EchoTool
{
    [McpServerTool(Name = "echoMessage")]
    public string Echo(string message) => $"Echo 123: {message}";
}

然后尝试直接调用 echoMessage 方法，但都会收到方法不存在的错误响应。

问题根源分析

这个问题的根本原因在于对 MCP 协议调用机制的理解偏差。ModelContextProtocol 采用了一种特殊的工具调用机制，而不是直接暴露方法作为 JSON-RPC 端点。正确的调用方式应该是通过 tools/call 这个特殊的 JSON-RPC 方法来间接调用工具。

正确调用方式

在 MCP 协议中，工具调用的正确 JSON-RPC 请求格式应该是：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "工具名称",
    "arguments": {
      "参数名": "参数值"
    }
  }
}

解决方案

1. 使用官方客户端 SDK：建议开发者使用 ModelContextProtocol 提供的客户端 SDK 来构建客户端程序，而不是手动构造 JSON-RPC 请求。

2. 服务端工具注册：确保服务端正确注册了工具类：

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithTools<EchoTool>();

3. 工具类定义：正确使用特性标注工具类和方法：

[McpServerToolType]
public class EchoTool
{
    [McpServerTool(Name = "echoMessage")]
    public string Echo(string message) => $"Echo 123: {message}";
}

4. HTTP 服务端实现：如果需要实现 HTTP 服务端，应该配置 HTTP 传输层：

builder.Services
    .AddMcpServer()
    .WithHttpServerTransport(options => 
    {
        options.ListenAnyIP(5000);
    });

最佳实践建议

1. 始终通过 tools/call 方法来间接调用工具
2. 使用强类型的客户端 SDK 而不是手动构造请求
3. 确保服务端和客户端使用相同版本的协议
4. 在生产环境中考虑使用 HTTP 或 WebSocket 传输层
5. 为工具方法添加详细的 Description 特性以提供文档

总结

ModelContextProtocol 采用了一种特殊的工具调用机制，开发者需要理解这种间接调用模式才能正确使用。通过遵循官方推荐的客户端实现方式，可以避免手动构造请求带来的各种问题，确保工具调用的可靠性和一致性。