Microsoft MCP 工具开发规范：从基础到实践的全面指南

2026-03-15 04:17:38作者：齐添朝

引言

Microsoft MCP（Microsoft Cloud Platform）工具集是一套面向云平台管理的开发工具框架，旨在提供一致、高效的云服务管理体验。本指南将系统介绍MCP工具开发的技术规范，帮助开发人员构建符合标准的高质量工具。无论你是刚开始接触MCP开发的新手，还是希望规范现有项目的资深开发者，本指南都将为你提供清晰的指导和实用的建议。

一、基础规范

1.1 命名约定

命名是代码可读性的基础，良好的命名能够直观反映组件的功能和用途。MCP项目采用以下命名规范：

项目与命名空间

PascalCase命名法（每个单词首字母大写的命名方式）：用于项目名称、命名空间和类名
- ✅ 正确示例：Azure.Mcp.Tools.Aks（Azure Kubernetes服务工具）
- ❌ 错误示例：azure_mcp_tools_aks 或 AzureMcpToolsAks

文件与目录

C#源代码文件使用PascalCase：AppConfigSetup.cs
配置文件使用kebab-case（全小写字母，单词间用连字符连接）：appsettings.Development.json
测试项目目录以.Tests结尾：Azure.Mcp.Core.UnitTests

变量与方法

私有字段使用camelCase（首个单词小写，后续单词首字母大写）并加下划线前缀：_connectionString
公共属性和方法使用PascalCase：public void ConfigureServices(IServiceCollection services)
常量使用全大写SNAKE_CASE（单词间用下划线连接）：public const int MAX_RETRY_COUNT = 3;

⚠️ 重要提示：命名应遵循"自文档化"原则，即名称本身应清晰表达其功能或用途，避免使用模糊的缩写或无意义的命名。

常见问题

Q1: 如何处理包含多个技术术语的长名称？
A1: 保持名称简洁但不牺牲清晰度，可适当使用行业标准缩写，如Aks代表Azure Kubernetes Service，但避免自创缩写。

Q2: 测试类和测试方法如何命名？
A2: 测试类应与被测试类对应，如AppConfigServiceTests；测试方法使用"方法名_场景_预期结果"格式，如GetConfig_WhenKeyExists_ReturnsValue。

Q3: 工具项目的命名有特殊要求吗？
A3: 工具项目应遵循{Platform}.Mcp.Tools.{ServiceName}格式，如Azure.Mcp.Tools.KeyVault表示Azure Key Vault工具。

1.2 代码风格

统一的代码风格有助于提高团队协作效率和代码可维护性。MCP项目采用以下代码风格规范：

格式规范

使用4个空格缩进，不使用Tab
每行代码不超过120个字符
方法之间保留一个空行，逻辑块之间保留一个空行
大括号{应与声明在同一行，如：
```
if (condition) {
    // 代码块
}
```

命名空间与using指令

using指令按以下顺序排列：
1. 系统命名空间（System.*）
2. 第三方库命名空间
3. 项目内部命名空间
避免使用using static指令，除非是非常常用的静态类（如System.Math）

代码组织

类成员顺序：静态成员 → 构造函数 → 属性 → 方法
方法参数不超过4个，超过时使用对象封装
局部变量声明在使用前，避免在代码块中间声明

🔧 工具推荐：使用eng/scripts/Analyze-Code.ps1脚本可自动检查代码风格合规性。

常见问题

Q1: 如何处理长参数列表？
A1: 使用参数对象模式，将相关参数封装为一个类，如public void CreateResource(ResourceOptions options)。

Q2: 是否需要为所有成员添加XML注释？
A2: 是的，所有公共成员（类、方法、属性）都必须添加XML注释，私有成员可视复杂度添加。

Q3: 如何处理复杂的条件逻辑？
A3: 考虑使用策略模式或状态模式重构，将复杂条件逻辑拆分为多个小方法或类。

二、核心架构

2.1 系统架构

MCP工具集采用模块化、分层的架构设计，确保组件间低耦合、高内聚。以下是MCP系统的核心架构示意图：

该架构主要包含以下层次：

核心层（Core）

位于core/目录，提供工具开发的基础组件：

命令系统：定义命令基类和执行流程
服务接口：提供通用服务抽象（如日志、配置）
模型定义：通用数据模型和DTO（数据传输对象）

工具层（Tools）

位于tools/目录，包含各类具体工具实现：

每个工具独立为一个项目，如Azure.Mcp.Tools.Aks
工具间通过核心层接口交互，避免直接依赖

服务器层（Servers）

位于servers/目录，提供工具运行时环境：

负责工具发现、加载和生命周期管理
提供API和UI界面，方便用户交互

2.2 模块交互

MCP工具的典型执行流程如下：

用户通过服务器UI或命令行发起请求
服务器层接收请求并路由到相应工具
工具层执行具体业务逻辑，调用核心层服务
核心层处理跨工具的通用功能（如日志、认证）
结果通过服务器层返回给用户

以下是工具调用的时序图：

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  用户界面  │────▶│ 服务器层  │────▶│  工具层   │────▶│  核心层   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     ▲                 ▲                 ▲                 │
     │                 │                 │                 │
     │                 │                 │                 ▼
     │                 │                 │          ┌──────────┐
     │                 │                 │          │ 外部服务  │
     │                 │                 │◀─────────┘          │
     │                 │                 │                    │
     │                 │                 ▼                    ▼
     │                 │          ┌──────────┐          ┌──────────┐
     │                 │          │ 业务逻辑  │          │  API调用  │
     │                 │          └──────────┘          └──────────┘
     │                 │                 │                    │
     │                 │                 ▼                    ▼
     │                 │          ┌──────────┐
     │                 │◀─────────│ 结果处理  │
     │                 │          └──────────┘
     │                 │                 │
     │                 ▼                 ▼
     │          ┌──────────┐
     └──────────│ 结果返回  │
                └──────────┘

常见问题

Q1: 如何添加新工具到MCP系统？
A1: 1. 创建符合命名规范的工具项目；2. 实现ICommand接口；3. 在工具入口类添加[Tool]特性；4. 服务器会自动发现并加载新工具。

Q2: 核心层与工具层如何通信？
A2: 通过依赖注入（DI）实现，工具通过构造函数接收核心服务接口，如ILogger、IConfiguration等。

Q3: 工具间如何共享数据？
A3: 工具间不直接通信，如需共享数据，可通过核心层的状态管理服务或外部存储（如数据库、缓存）实现。

三、实践指南

3.1 环境搭建

搭建MCP开发环境需要完成以下步骤：

克隆代码仓库

git clone https://gitcode.com/GitHub_Trending/mcp27/mcp
cd mcp

安装开发依赖

# 安装Git Hooks
./eng/scripts/Install-GitHooks.ps1

# 还原NuGet包
dotnet restore

配置开发环境 启动VS Code并安装MCP Server扩展：

环境配置校验清单

检查项	验证方法	参考标准
.NET SDK版本	`dotnet --version`	需5.0以上
Git Hooks安装	检查`.git/hooks`目录	包含pre-commit等文件
扩展安装	VS Code扩展面板	MCP Server已启用
测试环境	`dotnet test`	所有测试通过
代码分析	`./eng/scripts/Analyze-Code.ps1`	无错误输出

3.2 工具开发流程

开发一个新的MCP工具遵循以下步骤：

1. 创建项目结构

使用模板创建工具项目：

# 在tools目录下创建新工具项目
dotnet new mcp-tool -n Azure.Mcp.Tools.MyService

生成的项目结构如下：

Azure.Mcp.Tools.MyService/
├── src/
│   ├── Commands/       # 命令定义
│   ├── Models/         # 数据模型
│   ├── Options/        # 命令行选项
│   ├── Services/       # 业务逻辑
│   └── MyServiceSetup.cs  # 工具入口
└── tests/              # 测试代码

2. 实现命令逻辑

创建命令类并继承CommandBase：

using System.CommandLine;
using Microsoft.Mcp.Core.Commands;

namespace Azure.Mcp.Tools.MyService.Commands;

public class MyCommand : CommandBase
{
    public MyCommand() : base("mycommand", "描述命令功能")
    {
        // 添加命令选项
        AddOption(new Option<string>("--name", "名称参数"));
    }

    protected override async Task<int> ExecuteAsync(CommandContext context)
    {
        // 实现命令逻辑
        var name = context.ParseResult.GetValueForOption<string>("--name");
        context.Logger.LogInformation($"Hello, {name}!");
        return 0;
    }
}

3. 注册工具

在工具入口类注册命令：

using Microsoft.Mcp.Core.Commands;
using Azure.Mcp.Tools.MyService.Commands;

namespace Azure.Mcp.Tools.MyService;

[Tool(Name = "myservice", Description = "我的服务工具")]
public class MyServiceSetup : IToolSetup
{
    public void ConfigureCommands(ICommandBuilder commandBuilder)
    {
        commandBuilder.AddCommand<MyCommand>();
    }
}

4. 编写测试

为命令添加单元测试：

using Xunit;
using Microsoft.Mcp.Core.Testing;

namespace Azure.Mcp.Tools.MyService.UnitTests.Commands;

public class MyCommandTests
{
    [Fact]
    public async Task ExecuteAsync_WithName_ReturnsSuccess()
    {
        // Arrange
        var command = new MyCommand();
        var context = TestCommandContext.Create(command, "--name Test");
        
        // Act
        var result = await command.ExecuteAsync(context);
        
        // Assert
        Assert.Equal(0, result);
        Assert.Contains("Hello, Test!", context.LoggerOutput);
    }
}

常见问题

Q1: 如何调试工具命令？
A1: 在VS Code中，可配置启动配置指向服务器项目，并在命令行参数中指定工具命令，如azmcp myservice mycommand --name Test。

Q2: 工具需要访问Azure资源，如何处理认证？
A2: 使用核心层提供的IAuthenticationService，它会自动处理Azure认证流程，无需手动管理凭证。

Q3: 如何为工具添加配置选项？
A3: 使用IOptions<T>模式，定义配置模型并在appsettings.json中添加相应配置节，核心层会自动注入配置值。

四、质量保障

4.1 测试策略

高质量的MCP工具必须有完善的测试覆盖，包括以下测试类型：

单元测试

测试范围：独立功能单元（方法、类）
框架：xUnit
命名规范：MethodName_Scenario_ExpectedResult
要求：核心业务逻辑覆盖率≥80%

集成测试

测试范围：模块间交互
环境：使用测试资源（通过eng/common/TestResources/脚本部署）
标记：使用[IntegrationTest]特性标记

端到端测试

测试范围：完整用户流程
工具：使用Selenium或Playwright测试UI流程
位置：每个服务器项目的e2e-tests目录

以下是一个单元测试示例：

[Fact]
public void CalculateTotalCost_WithTax_ReturnsCorrectValue()
{
    // Arrange
    var calculator = new CostCalculator();
    var items = new List<Item>
    {
        new Item { Price = 10.00m, Quantity = 2 },
        new Item { Price = 15.50m, Quantity = 1 }
    };
    decimal taxRate = 0.08m;
    
    // Act
    var result = calculator.CalculateTotalCost(items, taxRate);
    
    // Assert
    Assert.Equal(37.74m, result); // (10*2 + 15.50) * 1.08 = 37.74
}

4.2 代码质量保障

除了测试，MCP项目还通过以下措施保障代码质量：

静态代码分析

工具：eng/scripts/Analyze-Code.ps1
检查项：代码风格、安全漏洞、性能问题、最佳实践
要求：分析结果零错误

持续集成

触发条件：提交代码或创建PR时
检查内容：
- 代码编译
- 单元测试通过
- 代码分析无错误
- 测试覆盖率达标

代码审查

要求：至少1名团队成员审查通过
重点关注：
- 架构一致性
- 安全风险
- 性能影响
- 测试覆盖

图：MCP服务器启动日志示例，显示工具发现过程和系统状态

常见问题

Q1: 如何提高测试覆盖率？
A1: 优先测试核心业务逻辑和边界条件；使用参数化测试覆盖多种输入情况；考虑使用工具如Coverlet生成覆盖率报告。

Q2: 静态分析发现的警告需要全部修复吗？
A2: 是的，所有错误（Error）必须修复；警告（Warning）应尽可能修复，无法修复的需添加明确的抑制注释并说明原因。

Q3: 代码审查时重点关注哪些方面？
A3: 接口设计是否合理；是否存在安全漏洞（如注入攻击）；错误处理是否完善；是否遵循项目架构规范。

规范速查表

命名规范

项目/类：PascalCase（如Azure.Mcp.Tools.KeyVault）
文件：PascalCase（如KeyVaultSetup.cs）
配置文件：kebab-case（如appsettings.Development.json）
私有字段：camelCase加下划线（如_clientSecret）
常量：SNAKE_CASE（如MAX_RETRY_COUNT）

项目结构

工具项目/
├── src/
│   ├── Commands/    # 命令定义
│   ├── Models/      # 数据模型
│   ├── Options/     # 命令选项
│   ├── Services/    # 业务逻辑
│   └── *Setup.cs    # 工具入口
└── tests/           # 测试代码