MCP With Semantic Kernel

将模型上下文协议（MCP）工具与语义内核集成：分步指南

此存储库演示了如何将模型上下文协议（MCP）工具与Microsoft语义内核集成，实现AI模型与外部数据源或工具之间的无缝交互。通过遵循本指南，您将学习如何连接到MCP服务器，将MCP工具转换为语义内核函数，并利用大型语言模型（LLM）进行函数调用——所有这些都在可重用和可扩展的框架内。

快速入门-运行演示

先决条件

• .NET SDK （9.0或更高版本-使用预览版功能）
• Node.js和npm （可选-仅适用于GitHub和Everything等外部MCP服务器）
• OpenAI API密钥 （可选-仅语义内核集成需要）
• 模型上下文协议 NuGet包（版本0.1.0-preview.8-自动包含）
• 基本熟悉C#和语义内核概念

备注：Node.js只需要作为Node.js包发布的外部MCP服务器（GitHub、Everything）。该演示仅与本地用户完美配合。NET MCP服务器，完全避免依赖Node.js。

1.克隆和构建

git clone https://github.com/LiteObject/mcp-with-semantic-kernel.git
cd mcp-with-semantic-kernel
dotnet restore
dotnet build

2.配置（可选）

为语义内核集成设置OpenAI API密钥（这是可选的）：

dotnet user-secrets set "OpenAI:ApiKey" "your-api-key-here" --project src/Demo.MCP.Client

3.运行MCP客户端演示

dotnet run --project src/Demo.MCP.Client

该应用程序将：

1. 自动连接到已启用的MCP服务器 （在appsettings.json中配置）
2. 列出可用工具 从每个连接的服务器（请参阅本地MCP服务器工具部分）
3. 演示工具执行 带有示例调用（Echo工具测试）
4. 启动交互模式 在那里可以测试命令

4.仅使用本地服务器进行快速测试

对于不需要Node.js的最简单设置，演示预先配置为仅使用本地。NET MCP服务器。只需运行：

# The client (already configured to use local server)
dotnet run --project src/Demo.MCP.Client

本地服务器包括全面的测试工具（请参阅本地MCP服务器工具部分）。

5.交互式命令

客户端运行后，尝试以下命令：

> servers                           # List connected servers  
> list local                        # List tools for local server
> call local Add {"a": 5, "b": 3}   # Test calculator tool (note: case-sensitive "Add")
> call local Echo {"name": "World"} # Test echo tool (note: case-sensitive "Echo")
> call local GetDateTime {}         # Get current time (no parameters needed)
> exit                              # Quit the application

重要提示：

• 工具名称为 能识别大小写字母的 （使用“添加”，而不是“添加”）
• 参数必须是有效的JSON格式
• 使用工具中定义的确切参数名称（例如，“a”和“b”表示添加工具）

6.启用外部服务器（可选）

要使用GitHub和Everything服务器进行测试，请编辑 src/Demo.MCP.Client/appsettings.json 以使他们能够。 重要：仅更改 "Enabled" 财产 true 对于要激活的每台服务器，不要替换整个配置对象。

示例更改（有关完整的服务器设置，请参阅配置部分）：

{
  "McpServers": {
    "github": { 
      "Enabled": true    // Change this from false to true
      // Keep all other properties unchanged
    },
    "everything": { 
      "Enabled": true    // Change this from false to true  
      // Keep all other properties unchanged
    },
    "local": { "Enabled": true }
  }
}

然后重新启动客户端。这需要Node.js和互联网接入。

什么是模型上下文协议（MCP）？

这 模型上下文协议（MCP） 是一种开放标准协议，旨在标准化应用程序如何为AI模型提供上下文。它充当通用连接器，允许LLM以一致的方式与不同的数据源（例如API、数据库或服务）进行交互。将MCP视为增强AI互操作性、灵活性和上下文理解的桥梁。

在这个项目中，我们使用MCP来公开Semantic Kernel可以使用的工具，使人工智能驱动的工作流与自动化、数据检索或系统集成等现实世界的应用程序相结合。

为什么在MCP中使用语义核？

微软语义内核 是一个功能强大的SDK，可以简化构建AI代理和编排复杂的工作流程。通过集成MCP工具，您可以：

• 通过MCP服务器扩展语义内核的外部功能。
• 使LLM能够根据用户提示动态调用函数。
• 促进人工智能模型和非语义内核应用程序之间的互操作性。
• 使用标准化的工具集成协议简化开发。

此存储库提供了一个如何组合这些技术的实际示例，并附有示例代码以帮助您入门。

项目结构

src/
├── Demo.MCP.Client/              # MCP client application  
│   ├── Configuration/            # Robust configuration system with validation
│   │   ├── AppConfig.cs         # Main configuration class with smart loading
│   │   ├── McpServerConfig.cs   # MCP server configuration with transport types
│   │   └── OpenAIConfig.cs      # OpenAI/Semantic Kernel configuration
│   ├── Services/                # Business logic and MCP integration
│   │   ├── LoggingService.cs    # Structured logging with Serilog
│   │   └── McpClientService.cs  # MCP client with retry logic and error handling
│   ├── Program.cs               # Main application with interactive demo
│   └── appsettings.json         # Configuration for servers, logging, and OpenAI
└── Demo.MCP.Server/             # Local MCP server (.NET implementation)
    ├── Tools/                   # 23 example MCP tools organized by category
    │   ├── CalculatorTool.cs    # Math operations (Add, Subtract, Multiply, etc.)
    │   ├── EchoTool.cs          # Simple echo functionality for testing
    │   ├── FileSystemTool.cs    # File operations (FileExists, ListFiles, etc.)
    │   ├── SystemInfoTool.cs    # System information and environment tools  
    │   └── TextProcessingTool.cs # Text manipulation (Base64, regex, etc.)
    └── Program.cs               # MCP server using stdio transport

分步指南

本节将引导您完成将MCP工具与语义内核集成的过程，如本存储库中实现的那样。

步骤1：设置您的项目

1. 克隆此存储库：

   git clone https://github.com/LiteObject/mcp-with-semantic-kernel.git
   cd mcp-with-semantic-kernel

1. 恢复依赖关系：

   dotnet restore

1. 配置OpenAI API密钥（可选-需要时请参阅先决条件）：

   dotnet user-secrets set "OpenAI:ApiKey" "your-api-key" --project src/Demo.MCP.Client
   dotnet user-secrets set "OpenAI:ChatModelId" "gpt-4o" --project src/Demo.MCP.Client

步骤2：连接到MCP服务器

该项目包括使用以下命令连接到MCP服务器的代码 ModelContextProtocol 包裹。MCP客户端从服务器检索可用工具，然后语义内核可以使用这些工具。

概念示例（实际实施 src/Demo.MCP.Client/Services/McpClientService.cs):

using ModelContextProtocol;

var mcpConfig = new McpServerConfig
{
    Id = "everything",
    Name = "Everything",
    TransportType = TransportType.Stdio,
    Command = "npx",
    Arguments = ["-y", "@modelcontextprotocol/server-everything"]
};

var mcpClient = await McpClientFactory.CreateAsync(mcpConfig);
var tools = await mcpClient.ListToolsAsync();

此代码段演示了建立与MCP服务器（例如“Everything”演示服务器）的连接并获取其可用工具的一般模式。实际实现包括额外的错误处理、重试逻辑和配置管理。

配置

该应用程序使用具有验证和智能路径解析功能的复杂配置系统：

自动MCP服务器管理

客户端使用相对路径自动启动和管理本地MCP服务器：

{
  "McpServers": {
    "local": {
      "Id": "local",
      "Name": "Local Demo Server", 
      "TransportType": "Stdio",
      "Command": "dotnet",
      "Arguments": ["run", "--project", "src/Demo.MCP.Server"],
      "ConnectionTimeout": "00:00:30",
      "MaxRetries": 3,
      "Enabled": true
    }
  }
}

可用的MCP服务器

• 本地服务器: .NET MCP服务器，具有全面的内置工具（默认启用）
• GitHub服务器：提供GitHub API访问（默认情况下禁用）
• Everything服务器：带有各种工具的演示服务器（默认禁用）

配置功能

• 分层加载：appsettings、特定于环境的文件、用户机密
• 验证：带有描述性错误消息的全面验证
• 日志记录配置：具有Serilog、文件和控制台输出的结构化日志记录
• 重试逻辑：可配置的连接超时和重试尝试

MCP通信的传输选项

MCP支持客户端-服务器通信的不同传输机制。了解这些选项有助于您为用例选择正确的配置。

可用运输类型

1. 标准输入/输出

本地MCP服务器的默认和最常见的传输方式。

它是如何工作的： 客户端将服务器作为子进程启动，并通过stdin/stdout管道进行通信。

配置示例：

{
  "TransportType": "Stdio",
  "Command": "dotnet",
  "Arguments": ["run", "--project", "src/Demo.MCP.Server"]
}

使用案例：

• 本地开发和测试
• 应用程序中的嵌入式服务器
• 客户端控制服务器生命周期的场景

优势：

• 设置简单，无需网络配置
• 安全（无网络暴露）
• 客户端自动管理服务器生命周期

限制：

• 服务器必须与客户端位于同一台计算机上
• 每个服务器实例一个客户端

2. HTTP/HTTPS （本演示中未实现）

远程MCP服务器的基于网络的传输。

它是如何工作的： 客户端连接到通过HTTP端点公开的服务器。

潜在配置：

{
  "TransportType": "Http",
  "Endpoint": "https://api.example.com/mcp"
}

使用案例：

• 云托管MCP服务器
• 多客户端场景
• 微服务架构

优势：

• 远程服务器访问
• 多个客户端可以连接到一个服务器
• 标准web基础设施（负载均衡器、代理等）

限制：

• 需要网络设置和安全考虑
• 延迟高于本地传输

3. 双向通信 （本演示中未实现）

实时双向通信。

使用案例：

• 从服务器到客户端的实时更新
• 长时间运行的连接
• 提醒推送

4. 命名管道 （本演示中未实现）

同一台机器上的进程间通信。

使用案例：

• 高性能本地通信
• Windows服务集成

选择合适的交通工具

当前实施情况

此演示使用 标准运输 对于所有服务器：

• 本地服务器：通过以下方式作为子流程启动 dotnet run
• GitHub服务器：通过启动 npx 命令
• 一切服务器：通过启动 npx 命令

选择Stdio传输是为了简单和安全，因为它不暴露任何网络端点，并且跨平台工作一致。

______________________________________________________________________

链接

• MCP服务器
• 模型上下文协议规范
• 微软语义内核