.NET MCP 文档
MCP 概述
MCP(Model Context Protocol)是由 Anthropic 推出的一种开放协议,类似 AI 的 USB-C 扩展坞,用于在大模型和数据源之间建立安全的通信(授权),让 AI 应用能够安全地访问和操作本地或远程数据,例如操作本地文件、浏览器和 Web 服务。
为了更好地理解 MCP,我们可以用一个简单的类比:如果把 AI 比作电脑主机,那么 MCP 就相当于 USB 协议,而 MCP Server 则类似于各种 USB 设备(如摄像头、麦克风等)。通过实现 MCP Server,我们可以让 AI 轻松连接到各种数据源,大大扩展其功能范围。
MCP 协议的核心价值在于标准化了 AI 模型与外部工具和数据源的交互方式,使开发者能够创建可被多种 AI 应用程序使用的工具和服务。这种标准化的接口极大地简化了 AI 应用的开发过程,并提高了工具和服务的可重用性。
MCP 的主要特点
- 标准化的工具调用接口
- 安全的双向通信
- 支持多种传输方式(stdio、SSE、WebSocket 等)
- 丰富的数据类型支持
- 与主流 LLM 的无缝集成
- 跨平台和跨语言支持
MCP 服务器
MCP 服务器是实现 MCP 协议的服务端,负责注册和提供工具,处理客户端的工具调用请求,并返回结果。服务器可以使用多种传输方式与客户端通信,如标准输入输出、SSE 或 WebSocket。
MCP 客户端
MCP 客户端是实现 MCP 协议的客户端,负责连接到 MCP 服务器,获取可用工具列表,调用工具,并处理返回结果。客户端通常与 LLM 集成,使 LLM 能够使用 MCP 工具。
.NET MCP 实现项目对比
在 .NET 生态系统中,目前有几个主要的 MCP 实现项目,它们各有特点。以下是这些项目的对比分析:
官方 C# SDK:csharp-sdk
这是 Model Context Protocol(MCP)官方提供的 C# SDK,为 MCP 服务器和客户端提供简单易用的接口,主要由微软维护。该项目已经成为 MCP 社区的官方 SDK 项目,最近发布了 0.1.0-preview 版本。
GitHub 仓库: https://github.com/modelcontextprotocol/csharp-sdk
MCPSharp
MCPSharp 是一个 .NET 库,旨在帮助开发者构建 Model Context Protocol(MCP)服务器和客户端。它提供了创建 MCP 合规的工具和函数、连接现有 MCP 服务器、将 .NET 方法暴露为 MCP 端点、处理 MCP 协议细节和 JSON-RPC 通信等功能。
特点:
- 与 Microsoft.Extensions.AI 集成
- Semantic Kernel 支持
- 动态工具注册
- 工具变更通知
- 复杂对象参数支持
- 错误处理
- 易用的基于属性的 API
- 内置 JSON-RPC 支持
- 自动参数验证和类型转换
GitHub 仓库: https://github.com/afrise/MCPSharp
mcpdotnet
mcpdotnet 是一个 .NET 实现的模型上下文协议(MCP),使 .NET 应用程序能够与 MCP 客户端和服务器进行交互。该项目已经进入归档状态,相关的开发工作都集中到了官方的 csharp-sdk。
特点:
- 支持多种 MCP 功能
- 遵循规范的实现
- 提供全面的日志支持
- 兼容 .NET 8.0 及以上版本
GitHub 仓库: https://github.com/PederHP/mcpdotnet
ModelContextProtocol.NET
ModelContextProtocol.NET 是一个 C# SDK,实现了模型上下文协议(MCP)。
特点:
- 标准输入输出通信
- 工具集成框架
- 原生 AOT 兼容
- 计算器演示实现
- 开发中功能:WebSocket 支持、资源管理和提示系统
GitHub 仓库: https://github.com/salty-flower/ModelContextProtocol.NET
服务器端实现
基本结构
使用官方的 C# SDK (csharp-sdk) 实现 MCP 服务器的基本结构如下:
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;
var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
// 配置所有日志输出到标准错误
consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});
builder.Services
.AddMcpServer()
.WithStdioServerTransport()
.WithToolsFromAssembly();
await builder.Build().RunAsync();
这段代码展示了如何创建一个基本的 MCP 服务器,它使用标准输入输出(stdio)作为传输方式,并自动注册当前程序集中的所有工具。
关键组件说明:
AddMcpServer()
- 向依赖注入容器添加 MCP 服务器服务WithStdioServerTransport()
- 配置服务器使用标准输入输出作为传输方式WithToolsFromAssembly()
- 自动注册当前程序集中的所有 MCP 工具
工具注册与实现
在 MCP 服务器中,工具是通过特性(Attribute)来注册的。下面是一个简单的工具实现示例:
[McpServerToolType]
public static class EchoTool
{
[McpServerTool, Description("Echoes the message back to the client.")]
public static string Echo(string message) => $"hello {message}";
}
更复杂的工具可以使用依赖注入和服务器交互:
[McpServerTool(Name = "SummarizeContentFromUrl"), Description("Summarizes content downloaded from a specific URI")]
public static async Task SummarizeDownloadedContent(
IMcpServer thisServer,
HttpClient httpClient,
[Description("The url from which to download the content to summarize")] string url,
CancellationToken cancellationToken)
{
// 实现内容
}
在 QuickstartWeatherServer 示例中,我们可以看到更实际的工具实现:
[McpServerToolType]
public static class WeatherTools
{
[McpServerTool, Description("Get weather alerts for a US state.")]
public static async Task GetAlerts(
HttpClient client,
[Description("The US state to get alerts for.")] string state)
{
var jsonElement = await client.GetFromJsonAsync($"/alerts/active/area/{state}");
var alerts = jsonElement.GetProperty("features").EnumerateArray();
if (!alerts.Any())
{
return "No active alerts for this state.";
}
return string.Join("\n-\n", alerts.Select(alert =>
{
JsonElement properties = alert.GetProperty("properties");
return $"""
Event: {properties.GetProperty("event").GetString()}
""";
}));
}
}
工具注册特性说明:
[McpServerToolType]
- 标记一个类包含 MCP 工具[McpServerTool]
- 标记一个方法作为 MCP 工具[Description]
- 提供工具和参数的描述信息
服务配置
MCP 服务器的配置主要通过 .NET 的依赖注入系统完成。以下是一个配置 HttpClient 的示例:
builder.Services.AddSingleton(_ =>
{
var client = new HttpClient() { BaseAddress = new Uri("https://api.weather.gov") };
client.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue("weather-tool", "1.0"));
return client;
});
高级配置选项:
- 自定义传输方式:除了标准的 stdio 传输方式,还可以配置 SSE 或 WebSocket 传输
- 工具过滤:可以选择性地注册特定的工具,而不是注册所有工具
- 中间件:可以添加自定义中间件来处理请求和响应
- 错误处理:可以配置全局错误处理策略
- 日志记录:可以配置详细的日志记录选项
客户端实现
连接到 MCP 服务器
使用官方的 C# SDK 连接到 MCP 服务器的基本代码如下:
var mcpClient = await McpClientFactory.CreateAsync(new()
{
Id = "demo-server",
Name = "Demo Server",
TransportType = TransportTypes.StdIo,
TransportOptions = new()
{
["command"] = command,
["arguments"] = arguments,
}
});
这段代码创建了一个 MCP 客户端,并连接到指定的服务器。TransportType
指定了通信方式(这里是标准输入输出),TransportOptions
提供了额外的配置选项。
支持的传输类型:
TransportTypes.StdIo
- 使用标准输入输出进行通信TransportTypes.Sse
- 使用服务器发送事件 (SSE) 进行通信TransportTypes.WebSocket
- 使用 WebSocket 进行通信
工具调用
连接到服务器后,客户端可以列出可用的工具并调用它们:
var tools = await mcpClient.ListToolsAsync();
foreach (var tool in tools)
{
Console.WriteLine($"Connected to server with tools: {tool.Name}");
}
// 调用工具示例
var result = await mcpClient.CallToolAsync(
"echo",
new Dictionary() { ["message"] = "Hello MCP!" },
CancellationToken.None);
// 输出结果
Console.WriteLine(result.Content.First(c => c.Type == "text").Text);
工具调用参数说明:
toolName
- 要调用的工具名称parameters
- 工具参数字典,键为参数名,值为参数值cancellationToken
- 取消令牌,用于取消操作
结果处理:
工具调用结果包含一个 Content
集合,每个内容项都有一个 Type
和一个 Text
。常见的内容类型包括:
text
- 纯文本内容application/json
- JSON 格式的内容image/*
- 图像内容(如 image/png、image/jpeg 等)
与 Claude 模型集成
MCP 客户端可以与 Claude 等 AI 模型集成,使模型能够使用 MCP 工具:
var anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
.Messages
.AsBuilder()
.UseFunctionInvocation()
.Build();
var options = new ChatOptions
{
MaxOutputTokens = 1000,
ModelId = "claude-3-5-sonnet-20240229",
Tools = [.. tools]
};
// 使用 Claude 模型处理用户查询
await foreach (var message in anthropicClient.GetStreamingResponseAsync(query, options))
{
Console.Write(message);
}
集成步骤说明:
- 创建 Anthropic 客户端并配置 API 密钥
- 启用函数调用功能
- 创建聊天选项,包括模型 ID、最大输出令牌数和工具列表
- 使用流式响应 API 处理用户查询
- 处理模型返回的消息,包括工具调用和文本响应
Cursor 配置与集成
MCP Server 添加步骤
在 Cursor 中配置 MCP Server 的步骤如下:
- 导航至
Cursor Settings
>Features
>MCP
- 点击
+ Add New MCP Server
按钮 - 在配置窗口中:
- 选择传输类型
- 配置服务器信息
- 完成添加后,服务器将显示在 MCP 服务器列表中
- 如需更新工具列表,可能需要手动点击刷新按钮
Cursor MCP 服务器配置界面示例
Cursor MCP 服务器配置界面(示意图)
传输类型配置
Cursor 支持两种主要的传输类型:
stdio
用于标准输入输出通信,适用于本地运行的 MCP 服务器。
配置方式:输入可执行命令
示例:npx -y @smithery/cli@latest run @mzxrai/mcp-webresearch --config "{}"
sse
用于服务器发送事件通信,适用于远程 MCP 服务器。
配置方式:输入服务器 URL
示例:https://example.com/mcp
工具使用方法
在 Cursor 的 Composer 中使用 MCP 工具时,你可以:
- 让 Composer Agent 自动选择合适的工具
- 明确指定使用特定工具
- 查看工具调用的详细信息
- 对工具调用进行管理:
- 检查调用参数
- 决定是否批准调用
- 查看调用结果
工具使用示例:
用户: 搜索关键词 cursor mcp server,列出 Top 5 热度的关键词
Claude: 我将使用 Web Search 工具来搜索这些关键词。
工具调用:Web Search
参数:{"query": "cursor mcp server"}
Claude: 根据搜索结果,关于 "cursor mcp server" 的 Top 5 热度关键词是:
- Model Context Protocol (MCP) Integration
- Custom MCP Server Development
- MCP Server Templates
- Database Integration
- Desktop Application Integration
最佳实践与示例
服务器端最佳实践
- 使用依赖注入:利用 .NET 的依赖注入系统管理服务和工具的依赖关系。
- 适当的错误处理:确保工具实现中包含适当的错误处理逻辑。
- 详细的工具描述:使用
Description
特性为工具和参数提供清晰的描述。 - 模块化设计:将不同功能的工具分组到不同的类中。
客户端最佳实践
- 异步操作:使用异步方法处理 MCP 客户端的所有操作。
- 资源管理:确保适当释放客户端资源。
- 错误处理:实现适当的错误处理逻辑,处理服务器连接和工具调用中可能出现的问题。
- 用户体验:提供清晰的用户反馈,特别是在工具调用过程中。
集成示例
以下是一个将 MCP 客户端与 Claude 模型集成的完整示例:
using Anthropic.SDK;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;
using System.ComponentModel;
var builder = Host.CreateApplicationBuilder(args);
builder.Configuration
.AddEnvironmentVariables()
.AddUserSecrets();
var (command, arguments) = GetCommandAndArguments(args);
await using var mcpClient = await McpClientFactory.CreateAsync(new()
{
Id = "demo-server",
Name = "Demo Server",
TransportType = TransportTypes.StdIo,
TransportOptions = new()
{
["command"] = command,
["arguments"] = arguments,
}
});
var tools = await mcpClient.ListToolsAsync();
foreach (var tool in tools)
{
Console.WriteLine($"Connected to server with tools: {tool.Name}");
}
var anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
.Messages
.AsBuilder()
.UseFunctionInvocation()
.Build();
var options = new ChatOptions
{
MaxOutputTokens = 1000,
ModelId = "claude-3-5-sonnet-20240229",
Tools = [.. tools]
};
Console.ForegroundColor = ConsoleColor.Green;
Console.WriteLine("MCP Client Started!");
Console.ResetColor();
PromptForInput();
while(Console.ReadLine() is string query && !("exit".Equals(query, StringComparison.OrdinalIgnoreCase)))
{
if (string.IsNullOrWhiteSpace(query))
{
PromptForInput();
continue;
}
await foreach (var message in anthropicClient.GetStreamingResponseAsync(query, options))
{
Console.Write(message);
}
Console.WriteLine();
PromptForInput();
}
static void PromptForInput()
{
// 提示用户输入
}
static (string, string) GetCommandAndArguments(string[] args)
{
// 解析命令行参数
}
这个示例展示了如何创建 MCP 客户端,连接到服务器,获取可用工具,并将这些工具与 Claude 模型集成,使模型能够使用这些工具来响应用户查询。
结论
本文档详细介绍了 .NET 使用 MCP 的相关内容,包括服务器端实现、客户端实现以及 Cursor 集成配置等方面。通过使用 MCP,开发者可以创建强大的工具和服务,使 AI 模型能够安全地访问和操作各种数据源。
随着 MCP 生态系统的不断发展,我们可以期待更多的功能和改进。官方的 C# SDK 提供了一个稳定的基础,使 .NET 开发者能够轻松地实现 MCP 服务器和客户端。
我们鼓励开发者探索 MCP 的各种可能性,创建创新的工具和服务,并为 MCP 社区做出贡献。