MCP 技术规范：构建云平台工具的核心指南

MCP（Microsoft Cloud Platform）技术规范是一套全面的开发框架，旨在帮助开发人员构建高质量、一致性强的云平台工具。本文档通过"核心原则→实践指南→案例解析"的三阶结构，提供从架构设计到代码实现的完整指导，确保工具开发符合行业最佳实践并具备高度可维护性。

一、核心原则：构建一致且可扩展的工具生态

1.1 模块化设计原则

MCP工具开发应遵循模块化架构，确保各组件高内聚低耦合。核心模块应包含命令系统、配置管理和服务接口三大基础组件，形成稳定的工具开发基座。

图1：MCP工具架构示意图，展示了核心模块间的调用关系和数据流路径

关键原则：

• 应采用分层设计，将业务逻辑与数据模型分离
• 不应在命令实现中直接包含复杂业务逻辑
• 建议通过依赖注入实现服务解耦
• 避免硬编码配置和环境相关参数

验证清单：

• 核心功能是否拆分为独立模块？
• 模块间依赖是否通过接口实现？
• 配置是否集中管理且支持环境变量覆盖？
• 是否避免了跨模块的直接数据访问？

1.2 命名体系设计

建立清晰的命名体系是确保代码可读性和一致性的基础。MCP工具采用层级化命名策略，从项目结构到代码元素形成统一的命名规范。

命名决策流程：

1. 确定组件类型（项目/文件/类/方法）
2. 选择适当的命名风格（PascalCase/kebab-case等）
3. 包含功能关键词和上下文信息
4. 验证是否符合整体命名体系

命名规范对比：

元素类型	推荐做法	常见错误
项目名称	Azure.Mcp.Tools.Aks	azure-mcp-aks-tool
源代码文件	AppConfigSetup.cs	appconfigsetup.cs
配置文件	appsettings.Development.json	AppSettings.dev.json
测试项目	Azure.Mcp.Core.UnitTests	Azure.Mcp.Core.Tests

验证清单：

• 项目名称是否遵循[平台].[产品].[组件类型].[功能]结构？
• 文件名是否准确反映其包含的主要类型或功能？
• 测试项目是否以.Tests结尾并明确测试类型？
• 配置文件是否使用环境区分的命名方式？

二、实践指南：从架构到代码的实现路径

2.1 模块化架构指南

问题：如何设计既独立又可集成的工具模块？

解决方案：采用"核心-扩展"架构模式，将工具分为基础框架和业务功能两部分。以AKS工具为例，推荐结构如下：

Azure.Mcp.Tools.Aks/          // 工具根目录
├── src/                      // 源代码目录
│   ├── Commands/             // 命令定义（如CreateCommand.cs、DeleteCommand.cs）
│   ├── Models/               // 数据模型（如AksCluster.cs、NodePool.cs）
│   ├── Options/              // 命令行选项（如CreateOptions.cs）
│   ├── Services/             // 业务服务（如AksService.cs）
│   └── AksSetup.cs           // 工具入口点，注册命令和服务
└── tests/                    // 测试代码目录
    ├── UnitTests/            // 单元测试
    └── LiveTests/            // 集成测试

关键实现要点：

• 命令类应继承CommandBase基类
• 服务类应通过接口抽象，便于测试
• 选项类使用[Option]特性定义命令行参数
• Setup类负责依赖注入配置

验证清单：

• 是否每个命令都有对应的选项类？
• 业务逻辑是否封装在Services目录中？
• 工具入口是否仅负责注册而不包含业务逻辑？
• 是否为所有公共接口编写了XML注释？

2.2 日志与错误处理规范

问题：如何确保工具行为可观测且错误处理一致？

解决方案：使用MCP核心日志接口和统一的错误处理模式。日志系统应支持分级输出，错误处理应提供明确的用户反馈。

// 推荐的日志使用方式
private readonly ILogger _logger;

public AksService(ILogger<AksService> logger)
{
    _logger = logger;
}

public async Task CreateClusterAsync(AksOptions options)
{
    _logger.LogInformation("Starting AKS cluster creation: {ClusterName}", options.ClusterName);
    
    try
    {
        // 业务逻辑实现
        _logger.LogDebug("Using Kubernetes version: {K8sVersion}", options.KubernetesVersion);
    }
    catch (AzureException ex)
    {
        _logger.LogError(ex, "Azure API error occurred: {Message}", ex.Message);
        throw new ToolException($"Failed to create cluster: {ex.Message}", ex)
        {
            ErrorCode = "AKS001",
            Recommendation = "Check Azure subscription permissions and try again"
        };
    }
}

日志级别使用规范：

• Trace：详细调试信息，默认不输出
• Debug：开发调试信息，仅在调试模式启用
• Info：正常操作信息，如"Cluster created successfully"
• Warning：非致命问题，如"Using default values for missing parameters"
• Error：操作失败，如"Failed to connect to Azure"
• Critical：严重错误，如"Authentication failed"

图2：MCP服务器日志输出示例，展示了服务启动过程和工具发现结果

验证清单：

• 是否使用了ILogger接口而非直接实例化日志类？
• 错误是否包含错误码和用户建议？
• 是否避免在日志中记录敏感信息？
• 不同操作阶段是否使用了适当的日志级别？

三、案例解析：规范落地的实践示例

3.1 工具项目创建全流程

如何从零开始创建符合规范的MCP工具？

1. 项目初始化

   # 克隆仓库
   git clone https://gitcode.com/GitHub_Trending/mcp27/mcp
   
   # 创建基础项目结构
   dotnet new classlib -n Azure.Mcp.Tools.NewTool -o tools/Azure.Mcp.Tools.NewTool/src
   

2. 添加核心依赖

   <!-- 在.csproj文件中添加 -->
   <ItemGroup>
     <ProjectReference Include="..\..\core\Azure.Mcp.Core\src\Azure.Mcp.Core.csproj" />
   </ItemGroup>
   

3. 实现基础结构

   // NewToolSetup.cs - 工具入口点
   public class NewToolSetup : IToolSetup
   {
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddScoped<INewToolService, NewToolService>();
       }
       
       public void ConfigureCommands(ICommandBuilder commandBuilder)
       {
           commandBuilder.AddCommand<CreateCommand>("create");
           commandBuilder.AddCommand<DeleteCommand>("delete");
       }
   }
   

4. 添加测试项目

   dotnet new xunit -n Azure.Mcp.Tools.NewTool.UnitTests -o tools/Azure.Mcp.Tools.NewTool/tests/UnitTests
   

验证清单：

• 项目结构是否符合"src/tests"分离原则？
• 是否实现了IToolSetup接口？
• 命令和服务是否通过依赖注入注册？
• 是否添加了必要的XML文档注释？

3.2 常见问题解决方案

问题1：工具间代码重复

解决方案：提取共享功能到核心库

// 不好的做法：每个工具重复实现相同的Azure认证逻辑
// 好的做法：使用核心库中的认证服务
public class AksService
{
    private readonly IAzureCredentialProvider _credentialProvider;
    
    public AksService(IAzureCredentialProvider credentialProvider)
    {
        _credentialProvider = credentialProvider;
    }
    
    public async Task<IAzure> GetAzureClientAsync()
    {
        var credentials = await _credentialProvider.GetCredentialsAsync();
        return Azure.Configure()
            .WithLogLevel(HttpLoggingDelegatingHandler.Level.Basic)
            .Authenticate(credentials)
            .WithDefaultSubscription();
    }
}

问题2：命令行选项处理不一致

解决方案：使用统一的选项模式

// 推荐的选项类实现
public class CreateOptions : CommandOptionsBase
{
    [Option("--cluster-name", Description = "Name of the AKS cluster")]
    [Required]
    public string ClusterName { get; set; } = string.Empty;
    
    [Option("--node-count", Description = "Number of nodes in the node pool")]
    [DefaultValue(3)]
    public int NodeCount { get; set; }
    
    [Option("--sku", Description = "VM SKU for nodes")]
    [AllowedValues("Standard_D2_v2", "Standard_D4_v2", "Standard_D8_v2")]
    public string Sku { get; set; } = "Standard_D2_v2";
}

验证清单：

• 是否复用了核心库中的公共服务？
• 命令选项是否使用了一致的验证和默认值模式？
• 是否避免了硬编码的服务端点和版本号？
• 错误处理是否遵循统一的异常类型？

附录：规范速查表

项目结构速查表

目录	用途
core/	核心框架和公共服务
servers/	服务器组件和扩展
tools/	各功能工具实现
eng/	工程工具和脚本
docs/	文档和设计规范

命名风格速查表

元素	风格	示例
命名空间	PascalCase	Azure.Mcp.Tools.Aks
类名	PascalCase	ClusterManager
方法名	PascalCase	CreateClusterAsync
参数名	camelCase	clusterName
配置文件	kebab-case	appsettings.development.json

常见问题解决指引

1. 工具注册失败：检查Setup类是否实现IToolSetup接口并正确注册
2. 依赖冲突：使用Directory.Packages.props统一管理包版本
3. 日志不输出：确保在appsettings.json中正确配置日志级别
4. 命令行参数解析错误：使用[Option]特性并提供完整的描述信息
5. 测试失败：检查是否正确使用了测试资源管理脚本

通过遵循以上规范，开发人员可以构建出符合MCP生态标准的高质量云平台工具，确保代码一致性、可维护性和可扩展性。