MCPSharp

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

• 创建符合MCP标准的工具和函数，这些工具和函数可以被AI模型发现并使用。
• 使用易于使用的客户端从C#代码直接连接到现有的MCP服务器。
• 使用简单的属性将您的.NET方法暴露为MCP端点。
• 无缝处理MCP协议细节和JSON-RPC通信。

🚀 MCPSharp 新特性

• Microsoft.Extensions.AI 集成：MCPSharp 现在与 Microsoft.Extensions.AI 集成，允许工具作为AIFunctions暴露。
• 语义内核支持：使用语义内核的KernelFunctionAttribute添加工具。
• 动态工具注册：使用自定义实现逻辑即时注册工具。
• 工具变更通知：服务器现在会在工具添加、更新或移除时通知客户端。
• 复杂对象参数支持：更好地处理工具参数中的复杂对象。
• 更好的错误处理：改进了详细的堆栈跟踪错误处理。

何时使用 MCPSharp

当您想要：

• 创建AI助手如Anthropic的Claude Desktop可以使用的工具。
• 构建符合MCP标准的API而不必处理协议细节。
• 将现有的.NET代码暴露为MCP端点。
• 通过标准化接口为应用程序添加AI能力。
• 与Microsoft.Extensions.AI和/或语义内核集成，而不锁定单一供应商。

特性

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

先决条件

• 支持标准2.0的任何版本的.NET

安装

dotnet add package MCPSharp

快速开始

1. 定义一个工具

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

using MCPSharp;

public class Calculator
{
    [McpTool("add", "Adds two numbers")]  // 注意：[McpFunction] 已废弃，改为使用 [McpTool]
    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 是包含所需方法的类。如果您的方法带有语义内核属性，这同样适用。如果客户端支持列表更改通知，它将在额外的工具被注册时收到通知。

高级用法

动态工具注册

使用自定义实现动态注册工具：

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 结合使用

// 客户端集成
MCPClient client = new("AIClient", "1.0", "path/to/mcp/server");
IList<AIFunction> functions = await client.GetFunctionsAsync();

此列表可以插入到IChatClient的ChatOptions.Tools属性中，使MCP服务器能够无缝地与任何IChatClient实现一起使用。

语义内核集成

using Microsoft.SemanticKernel;

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

// 注册到MCPServer
MCPServer.Register<MySkillClass>();

目前，这是使语义内核方法可注册到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>
/// 提供数学运算
/// </summary>
public class Calculator
{
    /// <summary>
    /// 将两个数字相加
    /// </summary>
    /// <param name="a">要相加的第一个数字</param>
    /// <param name="b">要相加的第二个数字</param>
    /// <returns>两个数字之和</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许可证。