MCPSharp

MCPSharp

MCPSharp 是一个 .NET 库，可帮助你构建模型上下文协议（MCP）服务和客户端——这是 AI 助手和模型使用的标准化 API 协议。借助 MCPSharp，你可以：

• 创建符合 MCP 规范的工具和函数，供 AI 模型发现和使用
• 使用易于使用的客户端，通过 C# 代码直接连接到现有 MCP 服务
• 通过简单的特性，将 .NET 方法公开为 MCP 端点
• 轻松处理 MCP 协议细节和 JSON-RPC 通信

🚀 MCPSharp 的新功能

• Microsoft.Extensions.AI 集成：MCPSharp 现在可与 Microsoft.Extensions.AI 集成，让工具能够以 AIFunction 的形式公开
• Semantic Kernel 支持：使用 Semantic Kernel 的 KernelFunctionAttribute 添加工具
• 动态工具注册：通过自定义实现逻辑即时注册工具
• 工具变更通知：添加、更新或移除工具时，服务现在会通知客户端
• 复杂对象参数支持：更好地处理工具参数中的复杂对象
• 更好的错误处理：改进错误处理，并提供详细的堆栈跟踪

何时使用 MCPSharp

在以下情况下使用 MCPSharp：

• 创建 Anthropic 的 Claude Desktop 等 AI 助手可使用的工具
• 构建符合 MCP 规范的 API，而无需处理协议细节
• 将现有 .NET 代码公开为 MCP 端点
• 通过标准化接口为应用程序添加 AI 功能
• 集成 Microsoft.Extensions.AI 和/或 Semantic Kernel，而不受限于单一供应商

功能

• 易于使用、基于特性的 API（[McpTool]、[McpResource]）
• 内置 JSON-RPC 支持，可自动处理请求和响应
• 自动进行参数验证和类型转换
• 通过 XML 注释提供丰富的文档支持
• 基本用法几乎无需配置

先决条件

• 支持 standard 2.0 的任意版本 .NET

安装

dotnet add package MCPSharp

快速入门

1. 定义工具

创建一个类，并使用 [McpTool] 特性标记方法：

using MCPSharp;

public class Calculator
{
    [McpTool("add", "Adds two numbers")]  // Note: [McpFunction] is deprecated, use [McpTool] instead
    public static int Add([McpParameter(true)] int a, [McpParameter(true)] int b)
    {
        return a + b;
    }
}

2. 启动服务

await MCPServer.StartAsync("CalculatorServer", "1.0.0");

StartAsync() 方法会自动查找基程序集内所有标记了 McpTool 特性的方法。若要添加引用库中的方法，可以通过调用 MCPServer.Register<T>(); 手动注册，其中 T 是包含所需方法的类。如果方法标记了 Semantic Kernel 特性，这种方式同样适用。如果客户端支持列表变更通知，那么注册其他工具时客户端会收到通知。

高级用法

动态工具注册

通过自定义实现动态注册工具：

MCPServer.AddToolHandler(new Tool() 
{
    Name = "dynamicTool",
    Description = "A dynamic tool",
    InputSchema = new InputSchema {
        Type = "object",
        Required = ["input"],
        Properties = new Dictionary<string, ParameterSchema>{
            {"input", new ParameterSchema{Type="string", Description="Input value"}}
        }
    }
}, (string input) => { return $"You provided: {input}"; });

与 Microsoft.Extensions.AI 配合使用

// Client-side integration
MCPClient client = new("AIClient", "1.0", "path/to/mcp/server");
IList<AIFunction> functions = await client.GetFunctionsAsync();

此列表可以设置到 IChatClient 的 ChatOptions.Tools 属性中，从而让 MCP 服务能够与任何 IChatClient 实现无缝配合使用。

Semantic Kernel 集成

using Microsoft.SemanticKernel;

public class MySkillClass
{
    [KernelFunction("MyFunction")]
    [Description("Description of my function")]
    public string MyFunction(string input) => $"Processed: {input}";
}

// Register with MCPServer
MCPServer.Register<MySkillClass>();

目前，这是让 Semantic Kernel 方法能够注册到 MCP 服务的唯一方式。如果你的使用场景不在此列，请联系我们！

API 参考

属性

• [McpTool] - 将类或方法标记为 MCP 工具

  • 可选参数：
    • Name - 工具名称（默认：类名/方法名）
    • Description - 工具说明

• [McpParameter] - 为函数参数提供元数据

  • 可选参数：
    • Description - 参数说明
    • Required - 参数是否必需（默认：false）

• [McpResource] - 将属性或方法标记为 MCP 资源

  • 参数：
    • Name - 资源名称
    • Uri - 资源 URI（可以包含模板）
    • MimeType - 资源的 MIME 类型
    • Description - 资源说明

服务端方法

• MCPServer.StartAsync(string serverName, string version) - 启动 MCP 服务
• MCPServer.Register<T>() - 注册包含工具或资源的类
• MCPServer.AddToolHandler(Tool tool, Delegate func) - 注册动态工具

客户端方法

• new MCPClient(string name, string version, string server, string args = null, IDictionary<string, string> env = null) - 创建客户端实例
• client.GetToolsAsync() - 获取可用工具
• client.CallToolAsync(string name, Dictionary<string, object> parameters) - 调用工具
• client.GetResourcesAsync() - 获取可用资源
• client.GetFunctionsAsync() - 将工具作为 AIFunctions 获取

XML 文档支持

MCPSharp 会自动从 XML 注释中提取文档：

/// <summary>
/// Provides mathematical operations
/// </summary>
public class Calculator
{
    /// <summary>
    /// Adds two numbers together
    /// </summary>
    /// <param name="a">The first number to add</param>
    /// <param name="b">The second number to add</param>
    /// <returns>The sum of the two numbers</returns>
    [McpTool]
    public static int Add(
        [McpParameter(true)] int a,
        [McpParameter(true)] int b)
    {
        return a + b;
    }
}

在项目文件中启用 XML 文档：

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

这样一来，无需重新编译即可快速更改 MCP 工具的名称和说明。例如，当你发现模型难以理解如何正确使用该工具时。

迁移说明

• [McpFunction] 已弃用，替换为 [McpTool]，以更好地符合 MCP 标准
• 为保持一致性，请使用 MCPServer.Register<T>() 代替 MCPServer.RegisterTool<T>()（旧方法仍可使用，但已弃用）

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

本项目采用 MIT License。