MCPSharp

https://github.com/afrise/MCPSharp/actions/workflows/build.yml/badge.svg)](https://github.com/afrise/MCPSharp/actions/workflows/build.yml) [](https://www.nuget.org/packages/MCPSharp) [](https://www.nuget.org/packages/MCPSharp) # MCPSharp MCPSharp 是一个 .NET 库，帮助您构建符合模型上下文协议（MCP）的服务器和客户端 - 这是人工智能助手和模型使用的标准化 API 协议。使用 MCPSharp，您可以： - 创建 MCP 兼容的工具和函数，AI 模型可以发现并使用它们 - 使用易于使用的客户端直接从 C# 代码连接到现有的 MCP 服务器 - 使用简单的属性将 .NET 方法公开为 MCP 端点 - 无缝处理 MCP 协议细节和 JSON-RPC 通信 ## 🚀 MCPSharp 新增功能 - **Microsoft.Extensions.AI 集成**：MCPSharp 现已与 Microsoft.Extensions.AI 集成，允许工具作为 AIFunctions 暴露 - **语义内核支持**：使用语义内核的 KernelFunctionAttribute 添加工具 - **动态工具注册**：使用自定义实现逻辑动态注册工具 - **工具变更通知**：服务器现在在工具添加、更新或删除时通知客户端 - **复杂对象参数支持**：更好地处理工具参数中的复杂对象 - **更好的错误处理**：改进的错误处理，提供详细的堆栈跟踪信息 ## 何时使用 MCPSharp 在以下情况下使用 MCPSharp： - 创建像 Anthropic's Claude Desktop 这样的人工智能助手可以使用的工具 - 在不处理协议细节的情况下构建 MCP 兼容的 API - 将现有的 .NET 代码公开为 MCP 端点 - 通过标准化接口为应用程序添加 AI 功能 - 在不锁定单个供应商的情况下与 Microsoft.Extensions.AI 和/或语义内核集成 ## 功能 - 易于使用的基于属性的 API（`[McpTool]`，`[McpResource]`） - 内置 JSON-RPC 支持，自动请求/响应处理 - 自动参数验证和类型转换 - 通过 XML 注释支持丰富的文档 - 基本使用时几乎不需要配置 ## 先决条件 - 支持 [.NET 标准 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2.0#tabpanel_1_net-standard-2-0) 的任何 .NET 版本 ## 安装 ```bash dotnet add package MCPSharp ``` ## 快速入门 ### 1. 定义工具 创建一个类，并使用 `[McpTool]` 属性标记您的方法： ```csharp using MCPSharp; public class Calculator { [McpTool("add", "添加两个数字")] // 注意：[McpFunction] 已弃用，请改用 [McpTool] public static int Add([McpParameter(true)] int a, [McpParameter(true)] int b) { return a + b; } } ``` ### 2. 启动服务器 ```csharp await MCPServer.StartAsync("CalculatorServer", "1.0.0"); ``` `StartAsync()` 方法将自动查找基类程序集中标记为 `McpTool` 属性的方法。为了添加引用库中的任何方法，您可以通过调用 `MCPServer.Register<T>()` 手动注册它们，其中 `T` 是包含所需方法的类。如果您的方法标记为语义内核属性，这也将起作用。如果客户端支持列表更改通知，则将在注册其他工具时通知它。 ## 高级用法 ### 动态工具注册 实现动态注册工具： ```csharp MCPServer.AddToolHandler(new Tool() { Name = "dynamicTool", Description = "一个动态工具", InputSchema = new InputSchema { Type = "object", Required = new[] { "input" }, Properties = new Dictionary<string, ParameterSchema>{ {"input", new ParameterSchema{Type="string", Description="输入值"}} } } }, (string input) => { return $"您提供了：{input}"; }); ``` ### 与 Microsoft.Extensions.AI 结合使用 ```csharp // 客户端集成 MCPClient client = new("AIClient", "1.0", "path/to/mcp/server"); IList<AIFunction> functions = await client.GetFunctionsAsync(); ``` 此列表可以插入 [ChatOptions.Tools](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.chatoptions?view=net-9.0-pp) 属性中，用于 [IChatClient](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.ichatclient?view=net-9.0-pp)，允许 MCP 服务器与任何 IChatClient 实现无缝使用。 ### 语义内核集成 ```csharp using Microsoft.SemanticKernel; public class MySkillClass { [KernelFunction("MyFunction")] [Description("我的函数描述")] public string MyFunction(string input) => $"处理：{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 注释中提取文档： ```csharp /// <summary> /// 提供数学运算 /// </summary> public class Calculator { /// <summary> /// 将两个数字相加 /// </summary> /// <param name="a">要添加的第一个数字</param> /// <param name="b">要添加的第二个数字</param> /// <returns>两个数字之和</returns> [McpTool] static int Add( [McpParameter(true)] int a, [McpParameter(true)] int b) { return a + b; } } ``` 在项目文件中启用 XML 文档： ```xml <PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup> ``` 这允许您在不重新编译的情况下快速更改 MCP 工具的名称和描述。例如，如果您发现模型难以理解如何正确使用它。 ## 迁移说明 - `[McpFunction]` 已弃用，取而代之的是 `[McpTool]`，以更好地与 MCP 标准保持一致 - 使用 `MCPServer.Register<T>()` 代替 `MCPServer.RegisterTool<T>()` 以保持一致性（旧方法仍然有效，但已弃用） ## 贡献 我们欢迎贡献！请随时