Integrating Model Context Protocol (MCP) Tools with Semantic Kernel: A Step-by-Step Guide

将模型上下文协议（MCP）工具与 Semantic Kernel 集成：分步指南

本仓库演示了如何将模型上下文协议（MCP）工具与 Microsoft Semantic Kernel 集成，从而让 AI 模型与外部数据源或工具无缝交互。按照本指南，你将学习如何连接 MCP 服务、将 MCP 工具转换为 Semantic Kernel 函数，并利用大语言模型（LLM）调用函数——这一切都基于可复用且可扩展的框架。

快速入门 - 运行演示

先决条件

• .NET SDK（版本 9.0 或更高版本 - 使用预览版功能）
• Node.js 和 npm（可选 - 仅外部 MCP 服务（如 GitHub 和 Everything）需要）
• OpenAI API 密钥（可选 - 仅 Semantic Kernel 集成需要）
• ModelContextProtocol NuGet 包（版本 0.1.0-preview.8 - 自动包含）
• 基本了解 C# 和 Semantic Kernel 概念

注意：只有外部 MCP 服务（GitHub、Everything）需要 Node.js，因为它们以 Node.js 包的形式发布。演示仅使用本地 .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 密钥，以集成 Semantic Kernel（此步骤为可选）：

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

重要说明：

• 工具名称区分大小写（使用 "Add"，而不是 "add"）
• 参数必须采用有效的 JSON 格式
• 使用工具定义中的确切参数名称（例如，Add 工具的 "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 可使用的工具，从而支持 AI 驱动的工作流，应用于自动化、数据检索或系统集成等实际场景。

为什么将 Semantic Kernel 与 MCP 搭配使用？

Microsoft Semantic Kernel 是一款功能强大的 SDK，可简化 AI Agent 的构建和复杂工作流的编排。通过集成 MCP 工具，你可以：

• 通过 MCP 服务为 Semantic Kernel 扩展外部能力。
• 让 LLM 根据用户提示词动态调用函数。
• 促进 AI 模型与非 Semantic Kernel 应用之间的互操作性。
• 使用标准化协议简化工具集成开发。

本仓库提供了结合这些技术的实用示例，并附有示例代码，帮助你快速入门。

项目结构

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 工具与 Semantic Kernel 集成，这也是本仓库中的实现方式。

步骤 1：设置项目

1. 克隆此仓库：

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

2. 还原依赖项：

   dotnet restore
   

3. 配置 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 服务

项目包含使用 ModelContextProtocol 包连接 MCP 服务的代码。MCP 客户端会从服务中获取可用工具，供 Semantic Kernel 使用。

概念示例（实际实现位于 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.json、特定环境的文件、用户机密
• 验证：全面验证并提供明确的错误消息
• 日志记录配置：使用 Serilog 进行结构化日志记录，输出到文件和控制台
• 重试逻辑：可配置的连接超时和重试次数

MCP 通信的传输选项

MCP 支持多种客户端与服务端通信的传输机制。了解这些选项有助于你根据使用场景选择合适的配置。

可用的传输类型

1. Stdio（标准输入/输出）

本地 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. WebSocket（本演示中未实现）

实时双向通信。

使用场景：

• 从服务向客户端实时推送更新
• 长时间运行的连接
• 推送通知

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

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

使用场景：

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

选择合适的传输方式

场景	推荐的传输方式	原因
本地开发	Stdio	简单，无需配置
生产服务器	HTTP/HTTPS	可扩展，采用标准基础设施
实时功能	WebSocket	双向通信
Windows 服务	命名管道	Windows 原生 IPC

当前实现

本演示的所有服务器均使用 Stdio 传输方式：

• 本地服务器：通过 dotnet run 作为子进程启动
• GitHub 服务器：通过 npx 命令启动
• Everything 服务器：通过 npx 命令启动

选择 Stdio 传输方式是为了简化实现并确保安全，因为它不会暴露任何网络端点，并且在各个平台上都能保持一致的运行效果。

---

链接

• MCP 服务器
• 模型上下文协议规范
• Microsoft Semantic Kernel