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

一、基础规范：构建代码的基石

1.1 命名约定

命名是代码的脸面，好的命名能让代码自文档化。MCP项目采用以下命名规则：

• 项目名称：使用PascalCase，如Azure.Mcp.Server，清晰表达项目所属和功能
• 文件命名：C#源代码用PascalCase（如AppConfigSetup.cs），配置文件用kebab-case（如appsettings.Development.json）
• 测试项目：以.Tests结尾，如Azure.Mcp.Core.UnitTests，便于识别测试代码

💡 为什么这么做：统一的命名规则降低认知成本，让团队成员能快速理解代码结构和用途。

错误示例：

azure_mcp_server/  // 使用下划线而非PascalCase
appSettings.dev.json  // 混合大小写
Azure.Mcp.Core.Tests/  // 缺少Unit前缀，无法区分测试类型

正确示范：

Azure.Mcp.Server/  // PascalCase命名
appsettings.Development.json  // kebab-case配置文件
Azure.Mcp.Core.UnitTests/  // 明确的测试类型标识

1.2 目录结构

MCP项目采用模块化的目录组织，核心目录包括：

• core/：基础组件库，包含命令系统、配置管理等核心功能
• servers/：服务器组件，提供工具运行的基础环境
• tools/：各类工具实现，每个工具独立成项目

💡 为什么这么做：清晰的目录结构如同良好的书架分类，让开发者能快速定位所需代码。

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

2.1 工具项目结构

每个工具项目遵循统一的结构，以tools/Azure.Mcp.Tools.Aks/为例：

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

💡 为什么这么做：一致的项目结构降低学习成本，新团队成员能快速适应不同工具的代码组织。

2.2 核心模块交互

MCP工具通过核心模块实现功能复用，主要交互流程如下：

图1：MCP工具架构设计图，展示了各组件间的调用关系和数据流，体现开发规范中的模块化设计思想

核心模块位于core/Azure.Mcp.Core/src/，包含：

• 命令系统：core/Azure.Mcp.Core/src/Commands/
• 配置管理：core/Azure.Mcp.Core/src/Configuration/
• 服务接口：core/Azure.Mcp.Core/src/Services/

三、开发实践：从代码到部署

3.1 环境搭建

开发MCP工具前，需要准备好开发环境：

1. 克隆仓库：git clone https://gitcode.com/GitHub_Trending/mcp27/mcp
2. 安装依赖：运行eng/scripts/Install-GitHooks.ps1
3. 配置开发环境：参考docs/bug-bash/installation-testing.md

图2：VS Code中安装MCP Server扩展的界面，展示开发规范中的环境配置流程

3.2 工具开发步骤

开发新工具建议遵循以下步骤：

1. 创建工具项目，遵循命名规范
2. 实现命令逻辑，继承CommandBase类
3. 添加单元测试，确保代码质量
4. 运行测试：dotnet test
5. 构建项目：dotnet build

💡 为什么这么做：标准化的开发流程确保代码质量，减少错误。

命令示例：

# 运行单元测试
dotnet test tests/Azure.Mcp.Tools.Aks.UnitTests/

# 构建项目
dotnet build src/Azure.Mcp.Tools.Aks/

四、质量保障：打造可靠的工具

4.1 代码质量控制

保持代码质量是开发规范的核心要求：

• 遵循Microsoft代码规范
• 使用eng/scripts/Analyze-Code.ps1进行代码分析
• 确保测试覆盖率达到80%以上

命令示例：

# 执行代码分析
./eng/scripts/Analyze-Code.ps1 -ProjectPath src/Azure.Mcp.Tools.Aks/

4.2 日志记录规范

良好的日志记录有助于问题排查：

• 使用统一的日志接口：core/Azure.Mcp.Core/src/Logging/
• 日志级别使用标准分类：Trace, Debug, Info, Warning, Error, Critical

图3：MCP服务器运行日志示例，展示开发规范中的日志记录标准

💡 为什么这么做：标准化的日志格式和级别便于问题定位和系统监控。

4.3 文档规范

完善的文档是工具易用性的关键：

• 每个工具需提供详细的使用文档，放在工具目录下的README.md
• API文档使用XML注释生成
• 变更日志遵循Keep a Changelog规范，存放在servers/Azure.Mcp.Server/changelog-entries/

正确示范：

/// <summary>
/// 初始化AKS集群配置
/// </summary>
/// <param name="options">配置选项</param>
/// <returns>配置结果</returns>
public async Task<ConfigResult> InitializeClusterAsync(AksOptions options)

总结

本指南从基础规范、架构设计、开发实践到质量保障，全面介绍了MCP工具开发的规范要求。遵循这些规范不仅能提高代码质量和可维护性，还能促进团队协作效率。记住，规范不是束缚，而是帮助我们构建更好软件的工具。随着项目的发展，这些规范也会不断演进，欢迎大家贡献自己的想法和建议。