MCP Graph API Demo

MCP Graph API 示例

此项目演示如何将模型上下文协议（MCP）与 Azure Graph API 配合使用，以查询 Azure 租户中的应用注册信息。

该应用使用 Blazor WebAssembly 客户端与实现 MCP 协议的 ASP.NET Core 服务进行通信。该服务连接到 Microsoft Graph API，以检索应用注册数据，然后通过 AI 辅助聊天界面处理并呈现这些数据。

架构概览

+---------------------+                 +---------------------+
|     MCP Client      |                 |     MCP Server      |
|                     |                 |                     |
|  +---------------+  |    MCP API      |  +--------------+   |
|  |     LLM       |  |  Requests &     |  |   Graph API  |   |
|  | Integration   |<-+-->Functions     |  |   Functions  |<--+--> Microsoft Graph API
|  | (SK + OpenAI) |  |                 |  |              |   |
|  +---------------+  |                 |  +--------------+   |
|                     |                 |                     |
|  +---------------+  |                 |  +--------------+   |
|  |    UI/UX      |  |                 |  | Azure AD     |   |
|  |  (Blazor WASM)|  |                 |  | Integration  |<--+--> Azure Active Directory
|  +---------------+  |                 |  +--------------+   |
+---------------------+                 +---------------------+

Client handles:                        Server handles:
- User Interface                       - Function Definitions
- Prompt Engineering                   - Graph API Integration
- LLM Integration                      - Azure AD Authentication
- Function Orchestration               - Data Processing

此架构严格遵循 MCP 原则：

1. MCP 客户端处理所有大模型交互和用户体验
2. MCP 服务提供函数定义并处理实际的 Graph API 调用
3. 通过标准化的 MCP 协议进行通信

项目结构

• MCP.Client：与 MCP 服务交互的 Blazor WebAssembly 客户端

  • 处理用户界面和聊天体验
  • 集成 Azure OpenAI 或 OpenAI API
  • 使用 Semantic Kernel 编排大模型交互和函数调用

• MCP.Server：实现 Azure Graph API MCP 协议的 ASP.NET Core 服务

  • 提供 Graph API 操作的函数定义
  • 处理 Azure AD 身份验证
  • 根据客户端请求执行 Graph API 调用
  • 向客户端返回结构化数据

• MCP.Shared：客户端与服务之间共享的模型和接口

  • 定义 MCP 协议结构
  • 包含共享数据模型和接口

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

模型上下文协议（MCP）是一种面向大模型应用的架构模式，用于分离：

1. 大模型集成（客户端侧）：用户界面、提示词工程、大模型调用
2. 工具/函数集成（服务端侧）：大模型可以使用的功能

MCP 实现了清晰的职责分离：

• 客户端处理所有大模型交互和用户体验
• 服务专注于提供函数定义，并在收到调用时执行函数
• 这种分离有助于提升安全性、模块化程度和可扩展性

此项目通过以下方式实现 MCP：

1. 将 Graph API 功能作为函数公开在服务上
2. 允许客户端的大模型发现并调用这些函数
3. 绝不向服务公开大模型密钥，也不向客户端公开函数实现细节

先决条件

• .NET 9.0
• 具有应用注册权限的 Azure 订阅
• Azure OpenAI 资源或 OpenAI API 密钥

配置

运行应用之前，需要使用自己的 Azure 凭据进行配置：

MCP 服务配置

编辑 MCP.Server/appsettings.json 并更新以下设置：

"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "TenantId": "<YOUR_TENANT_ID>",
  "ClientId": "<YOUR_CLIENT_ID>",
  "ClientSecret": "<YOUR_CLIENT_SECRET>",
  "Scopes": ["User.Read", "Application.Read.All"]
}

MCP 客户端配置

编辑 MCP.Client/wwwroot/appsettings.json 并更新以下设置：

"AzureAd": {
  "Authority": "https://login.microsoftonline.com/<YOUR_TENANT_ID>",
  "ClientId": "<YOUR_CLIENT_ID>",
  "ValidateAuthority": true
},
"ApiBaseUrl": "http://localhost:5197",
"AzureOpenAI": {
  "Endpoint": "https://your-resource.openai.azure.com/",
  "ApiKey": "<YOUR_AZURE_OPENAI_API_KEY>",
  "DeploymentName": "gpt-35-turbo"
}

注意：MCP 服务不再需要 OpenAI 配置，因为它不会直接与大模型交互。所有大模型集成都由客户端处理。

设置说明

1. 先决条件：

   • 安装 .NET 9.0 SDK
   • 拥有具有创建应用注册权限的 Azure 订阅
   • 拥有 Azure OpenAI 或 OpenAI API 的访问权限

2. 在 Azure AD 中注册应用：

   • 转到 Azure 门户 > Azure Active Directory > 应用注册
   • 创建新的注册
   • 设置客户端密钥
   • 授予以下 API 权限：
     • Microsoft Graph API > Application.Read.All
     • 确保授予管理员同意
   • 有关权限问题的详细排查说明，请参阅 GraphApiPermissionFix.md

3. 配置 Azure OpenAI：

   • 创建 Azure OpenAI 资源，或直接使用 OpenAI
   • 为 GPT 模型创建部署（例如 gpt-35-turbo 或 gpt-4）
   • 获取 API 密钥和终结点

4. 更新配置文件：

   • 按照上方“配置”部分中的说明更新服务端和客户端配置文件

运行应用程序

1. 启动 MCP 服务：

   cd MCP.Server
   dotnet run
   

2. 启动 MCP 客户端（在新终端中）：

   cd MCP.Client
   dotnet run
   

3. 打开浏览器并访问：

   • http://localhost:5268（客户端）
   • http://localhost:5197/swagger（服务端 API 文档）

4. 使用聊天界面询问有关 Azure 应用注册的问题：

   • “列出我租户中的所有应用注册”
   • “获取 ID 为 [app-id] 的应用注册详情”
   • “[app-name] 有哪些权限？”

使用 MCP 进行开发

如需为此应用程序添加新的 Graph API 功能：

1. 在 MCP.Server/Services/McpGraphService.cs 中添加新的函数声明
2. 在同一文件中实现函数逻辑
3. 更新 ExecuteFunctionAsync 方法以处理新函数
4. 客户端的大模型会在适当时自动发现并使用新函数

函数声明示例：

new McpFunctionDeclaration
{
    Name = "get_user_details",
    Description = "Get details for a specific user in the tenant",
    Parameters = new McpFunctionParameters
    {
        Type = "object",
        Properties = new Dictionary<string, McpParameterProperty>
        {
            ["user_id"] = new McpParameterProperty
            {
                Type = "string",
                Description = "The ID of the user"
            }
        },
        Required = new List<string> { "user_id" }
    }
}

GitHub 准备工作

在将此项目推送到公开的 GitHub 仓库之前：

1. 运行附带的清理脚本，对配置文件进行脱敏：

   .\clean-for-github.ps1
   

2. 确认不存在敏感数据：

   • 所有 appsettings.json 文件都应使用占位符（<YOUR_*>）
   • 不应包含实际的 API 密钥或凭据
   • 不应提交任何 .bak 或 .private 文件

3. 查看 GITHUB-CHECKLIST.md 文件，了解完整的发布前检查清单

安全注意事项

• 切勿将真实的 API 密钥或机密提交到 GitHub
• MCP 架构通过仅在客户端保留大模型密钥来增强安全性
• 服务端只需访问 Graph API，无需访问任何大模型服务
• 在生产部署中使用 Azure Key Vault 安全存储 API 密钥
• 查看 CONTRIBUTING.md，了解更多安全最佳实践

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

• 按照配置部分的说明更新设置文件

运行应用程序

1. 启动服务端：

   cd MCP.Server
   dotnet run --launch-profile https
   

2. 启动客户端：

   cd MCP.Client
   dotnet run
   

3. 访问应用程序： 打开浏览器并访问 https://localhost:7030/chat

故障排除

如果遇到权限问题，请检查以下内容：

1. 验证 API 权限：确保应用注册具有所需的 Microsoft Graph 权限，并且已获得管理员同意。

2. 检查身份验证：确保配置文件中的 Azure AD 凭据正确。

3. 运行测试脚本：使用提供的 PowerShell 脚本测试 Graph API 权限：

   ./TestGraphPermissions.ps1
   

功能

• 通过聊天界面查询 Azure 租户信息
• 通过 MCP 访问 Graph API 函数
• 集成 Semantic Kernel 以支持大模型函数

为 GitHub 做准备

在将此项目推送到公开仓库之前，请运行清理脚本以删除敏感信息：

./clean-for-github.ps1

此脚本将：

1. 删除不必要的文件（bin、obj 文件夹）
2. 删除 Azure 存储模拟器文件
3. 将敏感数据替换为占位符，对配置文件进行脱敏
4. 使用 .private.bak 扩展名创建原始文件的备份

贡献

如果您想为此项目做出贡献，请阅读我们的贡献指南，了解行为准则和提交拉取请求的流程。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• Model Context Protocol (MCP) - 感谢其为 AI 模型交互提供框架
• Microsoft Graph API - 用于访问 Azure AD 数据