Agent-Rules 项目中的 MCP 开发最佳实践指南

前言

在开发基于 Model Context Protocol (MCP) 的工具时，遵循一套标准化实践对于确保工具的可靠性、可维护性和用户体验至关重要。本文将深入探讨 agent-rules 项目中关于 MCP 工具开发的最佳实践，帮助开发者构建高质量的 MCP 工具。

一、基础配置与行为规范

1.1 环境变量与默认值

所有环境变量都应设置合理的默认值，确保工具开箱即用。例如，日志文件路径应默认指向系统标准日志目录（如 macOS 的 ~/Library/Logs/），同时允许通过环境变量覆盖。

1.2 动态版本管理

工具版本号应从项目配置文件（如 package.json）动态读取，避免硬编码。版本信息应包含在工具描述中，便于用户识别。

1.3 工具与参数描述

• 工具标题：使用清晰、易懂的自然语言描述
• 参数说明：
  • 每个参数都应提供详细描述
  • 明确标注参数是"可选"还是"必需"
  • 可选参数需说明默认值
• 参数解析：应采用宽松策略，例如接受 path 参数即使正式定义为 project_path，提高工具兼容性

1.4 错误处理机制

• 运行时错误：应提供有意义的错误信息，帮助用户诊断和恢复
• 配置错误：错误的配置不应导致工具崩溃，而应给出明确的修复指导

1.5 输出控制（关键要求）

绝对禁止向标准输出(stdout)或标准错误(stderr)写入任何内容，包括：

• 所有 console 方法调用（log/error/warn 等）
• 直接使用 process.stdout/stderr.write
• 任何调试输出

所有输出必须通过文件日志系统（如 Pino）处理，避免干扰 MCP 客户端运行。

1.6 信息查询功能

至少一个工具应提供 info 子命令，用于查询：

• 工具版本信息
• 原生依赖状态（如存在）
• 配置问题检测结果

二、日志系统实现规范

2.1 Pino 日志配置

• 默认路径：系统日志目录（可配置）
• 路径处理：
  • 自动创建缺失的父目录
  • 写入失败时回退到临时目录
• 日志级别：通过环境变量配置（支持大小写混合）
• 控制台输出：可通过环境变量额外启用

2.2 日志可靠性

确保进程退出前刷新所有日志，避免信息丢失。

三、代码与构建规范

3.1 代码质量

• 依赖管理：保持最新稳定版本
• 静态分析：零 lint 和 TypeScript 错误
• 文件大小：单文件不超过 500 行（理想 300 行内）

3.2 构建要求

• 始终使用编译后的 JavaScript 执行
• 可执行文件需包含正确的 shebang（如 #!/usr/bin/env node）
• 发布包仅包含必要文件（dist/, 原生组件, README, LICENSE）

四、测试策略

4.1 测试框架

• 使用 vitest 作为测试框架
• 包含完整的 TypeScript 测试套件
• 实现端到端(E2E)测试验证完整流程

4.2 测试脚本

• prepare-release：执行完整测试套件
• inspector：启动 MCP 检查器

五、原生二进制规范（如适用）

5.1 平台兼容性

• macOS：支持当前及上一主要版本（n-1）
• 架构：通用二进制（Apple Silicon + Intel）

5.2 代码质量

• 使用 SwiftLint 和 SwiftFormat
• 无静态分析问题
• 包含原生测试套件

5.3 通信机制

• 支持 JSON 格式通信
• 通过 errno 传递错误信息
• 实现 --help 帮助命令
• 使用专业参数解析框架

5.4 版本管理

原生与 TypeScript 部分版本号必须一致，通过构建过程动态注入。

六、发布前检查清单

发布前脚本应执行以下验证：

6.1 版本控制检查

• 分支验证
• 未提交变更检查
• 版本冲突检测
• 变更日志验证

6.2 代码质量检查

• 依赖安全检查
• TypeScript 编译与测试
• 原生代码分析（如存在）

6.3 二进制验证（如存在）

• 架构兼容性检查
• 命令行功能测试
• JSON 输出验证

6.4 包完整性检查

• 关键文件存在性
• 包大小监控
• 集成测试

发布策略建议

首次发布应使用 beta 标签，通过 @beta 标识进行测试验证，确认稳定后再发布正式版本。

结语

遵循这些最佳实践将确保开发的 MCP 工具具有高度可靠性、良好用户体验和易于维护的代码结构。特别是在输出控制、错误处理和日志管理方面需要特别注意，这些是保证 MCP 工具与客户端稳定交互的关键因素。