MCP工具开发规范：构建云平台工具的系统化方法

【基础规范】建立统一开发语言

设计项目命名体系

项目命名如同给工具贴标签，好的命名能直观反映功能定位。采用三层命名结构：平台标识+功能域+组件类型，形成清晰的"身份标识"。

规范类型	正确示例	错误示例	设计理念
项目命名	Azure.Mcp.Tools.Aks	AzureAKSTool	采用PascalCase，通过点分隔符明确层级关系，便于按功能域检索
文件命名	AppConfigSetup.cs	appconfigsetup.cs	类文件名与类名保持一致，使用PascalCase提升可读性
测试项目	Azure.Mcp.Core.UnitTests	AzureMcpCoreTests	测试项目以.Tests结尾，明确区分测试类型（Unit/Live）

[!TIP] 命名时思考：这个名称能否让新团队成员在3秒内理解其功能和归属？避免使用缩写和内部术语。

构建标准化项目结构

项目结构好比工具的"骨架"，统一的结构让开发者能快速定位功能模块。每个工具项目遵循"核心功能+支撑系统"的双轨结构：

工具项目根目录/
├── src/                # 源代码目录
│   ├── Commands/       # 命令定义（用户交互入口）
│   ├── Models/         # 数据模型（信息载体）
│   ├── Options/        # 命令选项（参数处理）
│   ├── Services/       # 业务服务（核心逻辑）
│   └── *Setup.cs       # 工具入口（初始化配置）
└── tests/              # 测试代码目录
    ├── UnitTests/      # 单元测试
    └── LiveTests/      # 集成测试

⚙️ 关键规范：

1. 命令集中管理：所有用户交互命令必须放在Commands目录，继承CommandBase基类
2. 依赖注入优先：业务逻辑通过接口定义，在Services目录实现，便于测试和替换
3. 配置集中化：工具配置应通过Options目录下的类进行管理，支持命令行和配置文件双来源

实现一致的代码风格

代码风格如同团队的"书写笔迹"，统一的风格减少认知负担。采用以下核心规范：

📋 C#代码风格要点：

• 使用var关键字声明局部变量，提高可读性
• 方法参数和局部变量采用camelCase命名法
• 类成员顺序：字段→构造函数→属性→方法
• 控制流语句（if/for等）必须使用大括号，即使单行代码

// 规范示例：命令类实现
public class CreateAksCommand : CommandBase
{
    private readonly IAksService _aksService;
    
    // 构造函数注入依赖
    public CreateAksCommand(IAksService aksService)
    {
        _aksService = aksService;
    }
    
    // 选项定义
    [Option("--node-count", Description = "节点数量")]
    public int NodeCount { get; set; } = 3;
    
    // 命令执行逻辑
    protected override async Task<int> ExecuteAsync(CommandContext context)
    {
        // 日志记录规范：使用统一日志接口
        Logger.LogInformation("开始创建AKS集群，节点数量：{NodeCount}", NodeCount);
        
        await _aksService.CreateClusterAsync(NodeCount);
        return 0;
    }
}

【核心架构】理解工具的内部构造

解析命令系统设计

命令系统是工具与用户交互的"对话窗口"，采用分层设计实现关注点分离：

1. 命令定义层：负责用户输入解析和参数验证
2. 业务逻辑层：实现核心功能，独立于命令交互
3. 基础设施层：提供日志、配置、网络等横切关注点

图：MCP工具命令执行流程追踪图，展示了请求从命令行输入到服务调用的完整路径

[!TIP] 复杂命令应拆分为多个子命令，遵循"单一职责原则"。例如aks命令可分为aks create、aks delete、aks scale等子命令。

构建服务层抽象

服务层是工具的"大脑"，封装业务逻辑并提供可测试的接口。设计时遵循以下原则：

✅ 服务设计规范：

1. 接口优先：每个服务必须定义接口，如IAksService
2. 依赖注入：通过构造函数注入依赖，避免硬编码
3. 异常处理：服务方法应抛出语义化异常，由命令层统一处理
4. 可测试性：业务逻辑与外部依赖分离，便于单元测试

// 服务接口定义示例
public interface IAksService
{
    /// <summary>
    /// 创建AKS集群
    /// </summary>
    /// <param name="nodeCount">节点数量</param>
    /// <returns>集群ID</returns>
    Task<string> CreateClusterAsync(int nodeCount);
}

设计数据模型体系

数据模型是工具内部的"信息载体"，良好的模型设计提升代码可维护性：

1. 分层模型：

   • 输入模型（*Options）：接收用户输入
   • 领域模型（*Model）：业务逻辑处理
   • 输出模型（*Result）：返回结果给用户

2. 模型设计原则：

   • 使用不可变属性（get-only）
   • 添加必要的验证特性
   • 实现ToString()方法便于日志输出

// 数据模型示例
public class AksClusterModel
{
    public string ClusterId { get; init; }
    
    [Required]
    public string Name { get; init; }
    
    public int NodeCount { get; init; }
    
    public DateTime CreatedAt { get; init; } = DateTime.UtcNow;
    
    public override string ToString() => 
        $"AksCluster: {Name} (Nodes: {NodeCount}, Id: {ClusterId})";
}

【实践指南】从零开始开发工具

初始化工具项目

创建新工具如同搭建房子，需要先打好地基。使用项目模板快速初始化：

# 创建工具项目结构
dotnet new classlib -n Azure.Mcp.Tools.NewTool
mkdir -p Azure.Mcp.Tools.NewTool/src/{Commands,Models,Options,Services}

⚙️ 项目配置要点：

• 引用核心库Azure.Mcp.Core
• 设置正确的目标框架（net8.0）
• 配置代码分析规则

实现命令与服务

工具开发遵循"先设计接口，后实现功能"的流程：

1. 定义命令：创建命令类并继承CommandBase
2. 实现服务：编写业务逻辑代码
3. 注册依赖：在*Setup.cs中配置依赖注入

[!TIP] 使用[Description]特性为命令和选项提供详细帮助信息，这些信息会自动生成帮助文档。

规范落地工具链

自动化工具确保规范执行不依赖人工检查：

1. 代码分析：配置Analyze-Code.ps1脚本

   # 运行代码分析
   .\eng\scripts\Analyze-Code.ps1 -ProjectPath .\tools\Azure.Mcp.Tools.NewTool
   

2. 格式检查：集成EditorConfig

   # .editorconfig配置示例
   [*.cs]
   indent_style = space
   indent_size = 4
   csharp_style_var_for_built_in_types = true:suggestion
   

3. 提交验证：安装Git Hooks

   # 安装提交前验证钩子
   .\eng\scripts\Install-GitHooks.ps1
   

【质量保障】构建可靠工具

编写测试策略

测试是工具质量的"安全网"，采用多层次测试策略：

测试类型	覆盖范围	实现方式
单元测试	独立功能单元	xUnit + Moq
集成测试	模块间交互	测试容器
端到端测试	完整用户场景	实际命令执行

// 单元测试示例
public class AksServiceTests
{
    [Fact]
    public async Task CreateClusterAsync_WithValidNodeCount_ReturnsClusterId()
    {
        // Arrange
        var mockClient = new Mock<IAzureClient>();
        mockClient.Setup(c => c.CreateClusterAsync(It.IsAny<int>()))
                  .ReturnsAsync("cluster-123");
                  
        var service = new AksService(mockClient.Object);
        
        // Act
        var result = await service.CreateClusterAsync(3);
        
        // Assert
        Assert.Equal("cluster-123", result);
        mockClient.Verify(c => c.CreateClusterAsync(3), Times.Once);
    }
}

实施日志与监控

日志是工具的"黑匣子"，帮助诊断问题：

1. 日志级别使用规范：

   • Trace：详细调试信息
   • Debug：开发调试信息
   • Information：正常操作记录
   • Warning：非严重问题
   • Error：功能失败
   • Critical：系统级故障

2. 结构化日志：使用日志模板和参数，避免字符串拼接

// 推荐的日志记录方式
Logger.LogInformation("集群创建成功: {ClusterId}, 节点数: {NodeCount}", 
                      clusterId, nodeCount);

// 不推荐的方式
Logger.LogInformation($"集群创建成功: {clusterId}, 节点数: {nodeCount}"); // 缺少结构化信息

复杂场景规范适配

面对特殊需求，在规范框架内灵活调整：

1. 大型工具拆分：当工具功能过于复杂，可拆分为多个子工具，通过共享库复用代码
2. 遗留代码兼容：逐步迁移而非一次性重写，使用适配器模式连接新旧代码
3. 性能优化：对高频操作，可在保持接口不变的前提下优化实现

规范演进路线

技术规范不是一成不变的，需要持续迭代：

• v1.0：基础命名和结构规范
• v2.0：引入依赖注入和接口抽象
• v3.0：增加异步编程模型
• v4.0：支持AOT编译和 trimming

[!TIP] 定期回顾规范适用性，通过团队讨论收集改进建议，每次规范变更需提供迁移指南。

通过系统化的规范体系，MCP工具开发实现了"一次学习，处处适用"的开发体验。统一的设计语言不仅提升了代码质量，更降低了团队协作成本，使开发者能专注于创造业务价值而非解决基础问题。