MCP Server Example

MCP 服务示例

本项目演示了如何使用 .NET 实现基本的 MCP（Model Context Protocol）服务。它提供了用于与 MCP 客户端交互的端点，并包含 MCP Inspector 等测试和调试工具。此示例还展示了如何使用用户机密配置与 GitLab 等外部服务集成。

中间件

UserAgentLoggingMiddleware

记录每个传入请求的 HTTP User-Agent 标头，包括 HTTP 方法和路径。它在 MapMcp() 之前注册，因此会覆盖所有 MCP 流量。输出示例：

Incoming request POST /mcp — User-Agent: claude-ai/1.0 mcp-client/0.4

工具

AzureTool

• GetAzureSubscriptionsAsync：获取 Azure 订阅及其 ID 的列表。
• GetListOfResourceGroupsAsync：获取指定订阅中的 Azure 资源组列表。
• GetVirtualMachinesMatchTagKeyAsync：获取订阅中所有带有与指定标记键匹配的标记的虚拟机名称及其标记。
• GetResourcesInResourceGroupAsync：获取指定资源组中的所有资源。
• GetResourcePropertiesAsync：根据资源 ID，获取特定 Azure 资源的属性和元数据字典。

说明

提示词：

• 获取 Azure 订阅及其 ID 的列表
• 获取 ??? 中的资源组列表
• 获取资源组 ??? 中的所有资源 ID 和类型
• 获取 Azure 资源 ??? 的所有属性和元数据

---

实际提示词： 获取 developmentsub 订阅中的所有资源组。对于每个资源组，获取所有资源。将这些资源类型与可和 Azure Key Vault 集成的类型进行交叉核对。最后，生成一个 Markdown 表格，包含资源组、资源 ID、资源名称和资源类型。

WhoIsTool

• WhoIs：提供指定域名的注册和所有权信息。

ElicitationTools

• GuessTheNumber：一个简单的互动游戏，演示引导式信息收集功能，用户需要猜测 1 到 10 之间的数字。此工具展示了如何使用 MCP 服务的 ElicitAsync 方法，通过结构化输入向用户请求信息，包括布尔值回答、枚举选项、带验证条件（最大长度）的字符串输入，以及采用特定格式的日期输入。
• BrowseAzureResourcesAsync：一个分步引导工具，先引导用户选择 Azure 订阅（单选），再选择资源组（多选）和资源类型筛选条件（下拉菜单 — All resource types 或特定的已部署类型），然后以结构化 JSON 的形式返回这些资源组中所有符合条件的资源。每个资源都以 ResourceType/Name 为键，以避免冲突。

说明

此工具演示了 MCP 的引导式信息收集功能，该功能允许服务通过结构化架构向用户请求更多信息。示例展示了：

• 用于是/否问题的布尔架构
• 用于多选选项（接受/拒绝）的枚举架构
• 带长度限制和说明的字符串架构
• 带格式验证（DD/MM/YYYY）的日期架构

SensitiveDataExampleTool

• SetASecretForDemoPurposes：演示如何处理敏感数据：为用户名设置机密，并在响应中自动将其屏蔽（仅显示前 4 个字符）。
• AAAEcho：一个简单的回显工具，返回提供的文本（默认为 "Hello, World!"）。
• SetAnApiKeyForDemoPurposes：演示如何处理 API 密钥：将密钥与 URL 关联，并在响应中自动将密钥屏蔽（仅显示前 4 个字符）。

说明

此工具演示了在 MCP 工具中处理敏感信息的最佳实践。ToPartialMask() 扩展方法可确保响应中不会完整暴露机密和 API 密钥，仅显示前 4 个字符，后接星号。

GitLabTools

• SearchGroupsAsync：根据搜索模式返回 GitLab 组列表。
• GetProjectsInGroupAsync：返回指定 GitLab 组中的项目列表。
• GetVariablesInProjectAsync：返回 GitLab 项目中的变量列表；如果变量值设为掩码，则对其进行掩码处理（保留最后 4 个字符可见）。
• AddAzureConsumptionBudgetAsync：检查 GitLab 项目是否已设置 Azure 消耗预算；如果没有，则通过合并请求添加

说明

提示词：

• 从 ??? 组中获取 GitLab 项目列表
• 获取指定 GitLab 组中的项目列表。
• 获取指定 GitLab 项目中的变量列表
• 使用 ??? GitLab 项目，检查 ??? 分支中是否有 Azure 消耗预算；如果没有，则添加

---

实际提示词：

• 从 upe 组中获取 GitLab 项目列表
• 获取指定 GitLab 项目中的变量列表；如果变量值设为掩码，则对其进行掩码处理（保留最后 4 个字符可见）。
• 使用 subscription-siem GitLab 项目，检查 "feat/kitcheng/init" 分支中是否有 Azure 消耗预算；如果没有，则添加
• 使用搜索模式 upe 获取 GitLab 组列表，并以 Markdown 表格形式展示，包含 name、web_url（显示为“点击这里”）、parent_id，以及表示 has_subgroups 的表情符号。按 parent id 分组。在此基础上创建树形结构，按 parent id 和 group id 嵌套各组。

资源

KitchenApplianceResources

• kitchen://appliances/all：以 JSON 表格形式返回完整的厨房电器目录（10 行）。
• kitchen://appliances/{id}：按数字 ID（1–10）返回单个电器。

每行电器数据包含：id、name、category、powerWatts、priceGbp、brand、hasDigitalControls。

UserResources

此项目通过两个 MCP 资源公开 YAML 格式的用户数据：

• user://{userId}：以 YAML 格式返回特定用户的数据。
• users://all：以 YAML 格式返回所有用户的数据。

提示词

此项目还公开了三个简单的 MCP 提示词（参见 Prompts/TextPrompts.cs）：

• ReverseWord(word)：反转单个单词，并仅返回反转后的单词。
• OneSentenceSummary(text)：用一个简洁的句子概述提供的文本。
• SummaryBenefitsAndReferences(topic)：针对给定主题返回一段简短摘要、一份要点形式的优势列表，以及一份要点形式的参考资料列表。

使用 MCP Inspector 试用：

• 启动此服务（参见下文“如何运行”），并按照本 README 后文所示，通过 Streamable HTTP 连接 Inspector。
• 点击 List Prompts，并选择上述提示词之一。
• 根据提示提供参数值并运行。

如何运行

说明

运行 GitLabTool 工具需要 PAT 和域名。请按照此处的说明操作。

dotnet build
dotnet run

你将看到类似以下的输出：

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5168
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

复制 Http URL，运行 MCP Inspector 时会用到它（参见下一节）。

如何调试/测试

MCP Explorer X 是在 IDE 外部测试和使用此 MCP 服务的推荐方式。它提供基于浏览器的 UI，可用于浏览工具、传入参数调用工具并检查响应，还支持完整的引导式交互。

快速开始（Docker）

选择适用于你操作系统的命令，在终端中运行，然后打开 http://localhost:8091：

macOS

dataRoot="$HOME/Library/Application Support/McpExplorerX-docker"
mkdir -p "${dataRoot}"

docker run --rm -it \
  -p 8091:8080 \
  -v "${dataRoot}:/root/.local/share/McpExplorer" \
  -v ~/.azure:/root/.azure \
  -e AZURE_CONFIG_DIR=/root/.azure \
  -e HOST_AZURE_CONFIG_DIR=${HOME}/.azure \
  -e PREFERENCES__StoragePath=/data/settings.json \
  -e ASPNETCORE_ENVIRONMENT=Production \
  garrardkitchen/mcp-explorer-x:latest

Linux

dataRoot="$HOME/.config/McpExplorerX-docker"
mkdir -p "${dataRoot}"

docker run --rm -it \
  -p 8091:8080 \
  -v "${dataRoot}:/root/.local/share/McpExplorer" \
  -v ~/.azure:/root/.azure \
  -e AZURE_CONFIG_DIR=/root/.azure \
  -e HOST_AZURE_CONFIG_DIR=${HOME}/.azure \
  -e PREFERENCES__StoragePath=/data/settings.json \
  -e ASPNETCORE_ENVIRONMENT=Production \
  garrardkitchen/mcp-explorer-x:latest

Windows（PowerShell）

$dataRoot="$HOME\AppData\Local\McpExplorerX-docker"
New-Item -ItemType Directory -Force -Path $dataRoot | Out-Null

docker run --rm -it `
  -p 8091:8080 `
  -v "${dataRoot}:/root/.local/share/McpExplorer" `
  -v ~/.azure:/root/.azure `
  -e AZURE_CONFIG_DIR=/root/.azure `
  -e HOST_AZURE_CONFIG_DIR=${HOME}/.azure `
  -e PREFERENCES__StoragePath=/data/settings.json `
  -e ASPNETCORE_ENVIRONMENT=Production `
  garrardkitchen/mcp-explorer-x:latest

运行后，使用 http://localhost:5168（Streamable HTTP 传输）将此服务添加为连接，并浏览可用的工具、资源和提示词。

说明

有关完整的设置选项，包括 Docker Compose、环境变量参考和 Azure 凭据挂载，请参阅 MCP Explorer X 快速入门文档。

用户机密

如果项目缺少 <UserSecretsId>，请运行以下命令为此项目设置用户机密：

dotnet user-secrets init

GitLab PAT

dotnet user-secrets set "GitLab:Token" "<your-token-value>"

GitLab 域名

dotnet user-secrets set "GitLab:Domain" "<your-domain-value>"