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

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

1.1 项目命名体系

核心规范：采用三级命名分类，确保项目结构清晰可辨。

• 项目级：使用PascalCase命名法，格式为[平台].[产品].[模块]
  ✅ 正确示例：Azure.Mcp.Tools.Aks（Azure平台的MCP工具集之AKS组件）
  ❌ 错误示例：azure_mcp_aks_tools（混合命名风格）
  为什么这样做：统一的命名模式便于代码导航和功能识别，尤其在大型项目中能快速定位相关组件。

• 文件级：源代码文件使用PascalCase，配置文件使用kebab-case
  ✅ 正确示例：AppConfigSetup.cs（C#代码）、appsettings.Development.json（配置文件）
  ❌ 错误示例：appconfigsetup.cs（未使用帕斯卡命名）、AppSettings.dev.json（混合大小写）
  为什么这样做：区分文件类型，提升IDE自动识别和代码提示效率。

• 代码级：遵循C#编码规范，类名使用PascalCase，方法和变量使用camelCase
  ✅ 正确示例：public class ResourceManager { private string resourceId; }
  ❌ 错误示例：public class resource_manager { public String ResourceID; }
  为什么这样做：符合C#社区最佳实践，降低团队协作的认知成本。

1.2 目录结构规范

核心规范：采用"功能模块化"组织方式，每个工具项目包含标准子目录。

工具项目基本结构
├── src/                 # 源代码目录
│   ├── Commands/        # 命令定义
│   ├── Models/          # 数据模型
│   ├── Options/         # 命令行选项
│   ├── Services/        # 业务逻辑服务
│   └── [ToolName]Setup.cs # 工具入口点
└── tests/               # 测试代码目录
    ├── UnitTests/       # 单元测试
    └── LiveTests/       # 集成测试

为什么这样做：标准化的目录结构使新团队成员能快速定位功能模块，同时便于自动化构建工具识别项目组件。

二、架构设计：构建可靠的模块系统

2.1 核心模块划分

MCP工具集采用分层架构，主要包含三大核心模块：

• 基础核心层（core/）：提供跨工具的基础功能

  • 命令系统：处理命令解析和执行流程
  • 配置管理：统一配置加载和验证
  • 服务接口：定义工具与外部系统交互的标准接口

• 服务器层（servers/）：提供工具运行时环境

  • 服务宿主：管理工具生命周期
  • 通信协议：处理客户端与工具的交互
  • 扩展系统：支持工具动态加载

• 工具层（tools/）：具体功能实现

  • 按云服务类型划分（如Aks、AppService、KeyVault等）
  • 每个工具独立封装特定领域功能

图1：MCP工具架构示意图，展示了核心模块间的调用关系和数据流（开发规范-架构设计）

2.2 模块间通信协议

核心规范：采用基于HTTP的RESTful通信模式，配合JSON作为数据交换格式。

• 请求格式：{ "command": "tool:action", "parameters": {}, "context": {} }
• 响应格式：{ "status": "success|error", "result": {}, "message": "" }
• 错误处理：统一使用HTTP状态码+自定义错误码，如400 Bad Request配合INVALID_ARGUMENT错误码

为什么这样做：标准化的通信协议降低了模块间集成成本，使不同工具间能无缝协作。

三、开发实践：从环境到部署的全流程

3.1 环境配置

核心步骤：

1. 基础环境准备

   # 克隆代码仓库
   git clone https://gitcode.com/GitHub_Trending/mcp27/mcp
   
   # 安装开发依赖
   cd mcp
   ./eng/scripts/Install-GitHooks.ps1
   

2. 开发工具配置

   • 安装Visual Studio 2022或VS Code
   • 安装.NET 7.0 SDK
   • 配置代码分析器：./eng/scripts/Analyze-Code.ps1 --install

图2：VS Code中MCP Server扩展的安装配置过程（开发规范-环境配置）

3.2 核心开发流程

三阶段开发模型：

1. 功能设计

   • 编写命令规范文档（存放于工具目录的docs/下）
   • 设计数据模型和服务接口
   • 创建单元测试用例

2. 代码实现

   • 实现命令逻辑，继承CommandBase基类
   • 遵循依赖注入原则设计服务组件
   • 编写XML注释，确保API文档自动生成

3. 本地验证

   # 构建项目
   dotnet build src/Azure.Mcp.Tools.[ToolName]/
   
   # 运行测试
   dotnet test tests/Azure.Mcp.Tools.[ToolName].UnitTests/
   
   # 本地调试
   dotnet run --project src/Azure.Mcp.Tools.[ToolName]/ -- [command] [arguments]
   

3.3 常见问题解决方案

🔧 依赖冲突：使用Directory.Packages.props统一管理NuGet包版本
🔧 测试环境隔离：使用test-resources.bicep创建独立测试资源
🔧 命令行参数解析：使用System.CommandLine库处理复杂参数场景
🔧 配置管理：通过IOptions<T>模式注入配置，避免硬编码
🔧 日志记录：使用ILogger接口，遵循"日志级别=详细程度"原则

四、质量保障：构建可靠的自动化体系

4.1 自动化测试策略

测试金字塔实现：

• 单元测试：覆盖核心业务逻辑，目标覆盖率>80%

  # 运行所有单元测试
  dotnet test --filter "Category=Unit"
  

• 集成测试：验证模块间交互，使用测试代理录制HTTP请求

  # 启动测试代理
  ./eng/common/testproxy/start-proxy.ps1
  
  # 运行集成测试
  dotnet test --filter "Category=Integration"
  

• 端到端测试：模拟真实用户场景，验证完整功能流程
  测试脚本存放于tests/E2ETests/目录

4.2 持续集成工具链

核心工具链：

• 代码分析：eng/scripts/Analyze-Code.ps1
  执行静态代码分析，检查代码规范和潜在问题

• 构建验证：eng/scripts/Build-Code.ps1
  跨平台构建验证，确保在Windows/Linux/macOS上均可编译

• 自动化部署：eng/pipelines/templates/jobs/
  包含构建、测试、打包、发布的完整CI/CD流程

图3：MCP服务器运行日志示例，显示服务启动和工具发现过程（开发规范-质量监控）

4.3 文档与变更管理

文档规范：

• 每个工具需提供README.md，包含：

  • 功能说明
  • 安装指南
  • 命令参考
  • 示例用法

• 变更日志管理：

  • 使用changelog-entries/目录下的YAML文件记录变更
  • 执行eng/scripts/Compile-Changelog.ps1生成汇总CHANGELOG.md

五、规范自查清单 📋

命名规范

• [ ] 项目名称使用PascalCase且格式为[平台].[产品].[模块]
• [ ] 代码文件使用PascalCase，配置文件使用kebab-case
• [ ] 类名使用PascalCase，方法和变量使用camelCase

架构规范

• [ ] 工具项目包含Commands/、Models/、Options/、Services/目录
• [ ] 业务逻辑封装在Services层，不直接出现在命令处理中
• [ ] 跨模块通信使用标准HTTP/JSON协议

开发规范

• [ ] 所有公共方法有XML注释
• [ ] 单元测试覆盖率达到80%以上
• [ ] 提交前运行Analyze-Code.ps1无错误

质量规范

• [ ] 所有测试通过（dotnet test无失败）
• [ ] 已添加变更日志条目
• [ ] 文档已更新且符合格式要求

通过遵循以上规范，开发团队可以构建出高质量、一致性强的MCP工具，同时降低维护成本和协作摩擦。规范不是束缚，而是提高效率的工具，帮助团队将精力集中在创新而非解决本可避免的问题上。