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

一、基础规范：构建一致的开发语言

1.1 命名体系：如何避免90%的命名错误？

核心规则：采用领域驱动命名法，使名称直观反映功能用途。工具项目使用[平台].[产品].[模块].[功能]四级结构，如Azure.Mcp.Tools.Aks清晰标识"Azure平台的MCP工具集之AKS管理工具"。

正反例对比：

• ✅ 正确：Azure.Mcp.Tools.Aks.Models.NodePoolConfig.cs（完整反映层级关系）
• ❌ 错误：AksTool.cs（过于简化，缺乏命名空间层级）
• ❌ 错误：AzureMcpAksTool.cs（PascalCase中混入缩写，降低可读性）

常见误区：使用技术实现命名而非业务功能，如将"数据库连接工具"命名为SqlConnector而非DatabaseConnectionTool，导致业务意图模糊。

1.2 文件组织：如何让新人30分钟理解项目结构？

标准结构：所有工具项目遵循"源代码-测试-资源"三分法：

工具项目/
├── src/            # 生产代码
│   ├── Commands/   # CLI命令定义
│   ├── Models/     # 数据结构
│   ├── Options/    # 命令行参数
│   └── Services/   # 业务逻辑
└── tests/          # 测试代码
    ├── UnitTests/  # 单元测试
    └── LiveTests/  # 集成测试

关键文件：每个工具必须包含[工具名]Setup.cs作为入口点，如AksSetup.cs负责命令注册和依赖注入配置。

常见误区：将测试资源文件散落在测试项目根目录，正确做法是创建test-resources子目录集中管理。

二、架构解析：理解MCP工具的底层设计

2.1 核心模块：工具开发的"乐高积木"

MCP核心框架提供三大支柱组件：

• 命令系统：基于CommandBase抽象类实现的命令处理管道，支持参数解析和结果处理
• 服务容器：通过依赖注入实现的松耦合架构，位于core/Microsoft.Mcp.Core/src/Services/
• 配置管理：统一的配置加载机制，支持环境变量、JSON文件和命令行参数的优先级合并

图：MCP工具架构调用链示意图，展示核心模块间的数据流和依赖关系

2.2 工具生命周期：从启动到执行的完整流程

工具执行遵循四阶段生命周期：

1. 发现阶段：服务器扫描tools/目录加载工具元数据
2. 初始化：执行[ToolName]Setup.ConfigureServices()配置依赖注入
3. 命令解析：将CLI输入映射为强类型Options对象
4. 执行与退出：调用ICommand.ExecuteAsync()并返回结果码

关键机制：通过IServiceCollection实现的依赖注入系统，确保工具间服务复用和测试可模拟性。

三、开发实践：从零构建你的第一个工具

3.1 环境搭建：5分钟启动开发环境

命令行初始化流程：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/mcp27/mcp
cd mcp

# 安装开发依赖
./eng/scripts/Install-GitHooks.ps1

# 构建基础框架
dotnet build core/Microsoft.Mcp.Core

参数说明：Install-GitHooks.ps1会配置pre-commit钩子，自动检查代码规范和格式。如需跳过钩子，可使用--no-verify参数。

常见误区：直接使用dotnet run启动项目而非dotnet build，导致依赖项未正确解析。

3.2 命令开发：实现你的第一个功能

创建"列出AKS集群"命令的核心步骤：

1. 定义选项类：继承CommandOptionsBase添加--resource-group参数
2. 创建命令类：实现ICommand<ClusterListOptions>接口
3. 注册服务：在AksSetup.cs中添加services.AddScoped<ICommand, ClusterListCommand>()

代码示例：

public class ClusterListCommand : ICommand<ClusterListOptions>
{
    private readonly IAksService _aksService;
    
    public ClusterListCommand(IAksService aksService)
    {
        _aksService = aksService;
    }
    
    public async Task<int> ExecuteAsync(ClusterListOptions options, CancellationToken cancellationToken)
    {
        var clusters = await _aksService.ListClustersAsync(options.ResourceGroup);
        // 输出处理逻辑
        return 0;
    }
}

四、质量保障：构建可靠的企业级工具

4.1 测试策略：从单元到集成的全链路验证

测试金字塔实践：

• 单元测试：覆盖独立功能，使用Moq模拟依赖，位于*UnitTests项目
• 集成测试：验证服务间交互，使用test-resources.bicep部署测试环境
• 冒烟测试：通过Invoke-PackageSmokeTests.ps1验证部署包完整性

图：MCP服务器启动日志，显示工具发现和初始化过程的状态追踪

4.2 代码质量：自动化保障体系

质量门禁：

• 静态分析：运行./eng/scripts/Analyze-Code.ps1检测代码异味
• 覆盖率要求：单元测试覆盖率最低80%，通过dotnet test --collect:"XPlat Code Coverage"生成报告
• 合规检查：使用Microsoft.CodeAnalysis验证代码规范符合性

常见误区：过度依赖手动测试，正确做法是将测试命令集成到CI/CD pipeline，如azure-pipelines.yml中配置自动测试步骤。

通过遵循这套规范，开发人员能够构建出符合MCP生态标准的高质量工具，同时确保代码的可维护性和扩展性。完整规范细节可参考项目内docs/目录下的技术文档。