ModelContextProtocol C SDK工具使用问题解析与最佳实践

问题背景

在使用ModelContextProtocol C# SDK开发MCP(Microsoft Copilot Protocol)服务时，开发者可能会遇到工具(Tools)使用不成功的问题。具体表现为服务初始化时返回空的工具列表，导致客户端调用时出现"Handler not found"错误。

核心问题分析

工具使用机制

ModelContextProtocol SDK提供了两种主要的工具使用方式：

1. 基于类型的调用：通过WithTools<T>()方法调用特定类型中的所有工具方法
2. 基于程序集的调用：通过WithToolsFromAssembly()方法扫描整个程序集中的工具类

常见错误原因

1. 工具类未正确标记：工具类需要使用[McpServerToolType]特性标记
2. 工具方法未正确标记：工具方法需要使用[McpServerTool]特性标记
3. 依赖注入配置不当：工具方法中使用的服务未在DI容器中注册
4. 泛型语法问题：在代码中泛型参数可能被错误处理

解决方案

正确的工具类实现

[McpServerToolType]
public sealed class KustoTools
{
    [McpServerTool(Name = "execute_query"), Description("Execute a Kusto query")]
    public static async Task<object> ExecuteQuery(
        [Description("The Kusto query to execute")] string query,
        QueryExecutor executor)
    {
        // 查询执行逻辑
    }
}

正确的服务配置

var builder = Host.CreateApplicationBuilder(args);

// 配置MCP服务器
builder.Services.AddMcpServer()
    .WithStdioServerTransport()
    .WithTools<KustoTools>();  // 注意泛型语法

// 注册依赖项
builder.Services.AddSingleton<QueryExecutor>();
builder.Services.AddSingleton<AuthenticationHelper>();

var host = builder.Build();

深入理解MCP协议

初始化响应解析

服务初始化时返回的"tools":{}并不表示工具列表为空，而是表示服务器支持工具功能。这是MCP协议的设计：

• "tools":{}：表示服务器支持工具功能
• 缺少"tools"字段：表示服务器不支持工具功能

工具生命周期

1. 调用阶段：服务启动时扫描并调用所有工具方法
2. 发现阶段：客户端通过特定请求获取可用工具列表
3. 执行阶段：客户端发起工具执行请求
4. 响应阶段：服务器执行对应工具方法并返回结果

最佳实践建议

1. 明确的工具命名：使用小写和下划线命名工具方法，保持一致性
2. 完善的文档注释：为每个工具方法添加详细的Description特性
3. 参数验证：在工具方法内部实现参数验证逻辑
4. 错误处理：使用统一的错误处理机制
5. 日志记录：记录工具调用的关键信息

调试技巧

1. 检查服务日志：确保工具类和方法被正确加载
2. 验证DI配置：确认所有依赖服务已正确注册
3. 协议分析：使用工具分析MCP协议通信内容
4. 单元测试：为工具方法编写独立的单元测试

通过理解这些核心概念和遵循最佳实践，开发者可以避免常见的工具使用问题，构建稳定可靠的MCP服务。