MCPBench - 模型上下文协议兼容性测试框架

概述

MCPBench 是一个开放标准，用于测试各种模型上下文协议（MCP https://github.com/modelcontextprotocol）客户端和服务器SDK实现之间的兼容性。随着MCP生态系统的发展，不是每个服务器或客户端都会用同一种编程语言编写，这形成了一个N×N的兼容性矩阵，其中N代表可用的语言SDK的数量。

我们的目标是确保不同MCP实现之间无缝互操作，无论使用的编程语言是什么。

当前状态

初始SDK支持：

• Python SDK（官方）
• TypeScript SDK（官方）
• Rust SDK（官方）

未来扩展： 随着MCP生态系统的发展，将添加更多语言的SDK。

基础阶段 M0

我们已经成功展示了关键的基础能力：

1. Git包信息提取

• 自动从官方MCP SDK仓库中获取并解析Git包信息
• 构建特定语言的兼容性矩阵
• 跟踪SDK之间的版本信息和依赖关系

2. Docker Compose生成

• 生成docker-compose配置以运行跨语言矩阵的客户端-服务器组合
• 支持跨语言测试场景
• 自动设置兼容性测试环境

3. 端到端（E2E）测试框架

• 工作中的Python客户端 ↔ TypeScript服务器通信
• 流式HTTP传输验证
• 工具调用和响应验证
• 会话管理和协议合规性测试

项目结构

mcpbench/
├── README.md                           # 本文件
├── matrix/                             # 核心兼容性测试框架
│   ├── templates/                      # 不同场景的测试模板
│   │   ├── python/                     # Python客户端/服务器模板
│   │   │   ├── client/
│   │   │   │   ├── e2e/               # 端到端客户端测试
│   │   │   │   ├── connection/        # 连接测试
│   │   │   │   └── ...                # 其他测试类别
│   │   │   └── server/
│   │   │       ├── e2e/               # 端到端服务器实现
│   │   │       └── ...                # 其他服务器模板
│   │   ├── typescript/                 # TypeScript客户端/服务器模板
│   │   │   ├── client/
│   │   │   └── server/
│   │   │       └── e2e/               # TypeScript服务器实现
│   │   └── rust/                       # Rust客户端/服务器模板
│   │       ├── client/
│   │       └── server/
│   ├── driver/                         # 测试编排和自动化
│   │   ├── update_sdk_info.py         # SDK信息提取
│   │   ├── setup.py                   # 环境设置
│   │   └── docker_generator.py        # Docker compose生成
│   └── requirements.txt               # Python依赖项
└── docs/                              # 文档和指南

关键组件

matrix/templates/：按语言和测试类型组织的测试模板。每个模板都提供了特定测试场景下MCP客户端/服务器实现的工作示例。

matrix/driver/：核心自动化脚本，包括：

• 从Git仓库中提取SDK信息
• 生成兼容性矩阵
• 创建docker-compose配置
• 编排跨语言测试

matrix/templates/*/e2e/：展示使用MCP协议进行完整客户端-服务器通信的端到端测试实现。

如何运行端到端测试

先决条件

• Python 3.8+ 和 pip
• Node.js 18+ 和 npm
• Docker（用于容器化测试）

快速开始：Python客户端 ↔ TypeScript服务器

1. 安装Python依赖项

   cd mcpbench/matrix/templates/python/server
   pip install -r requirements.txt
   

2. 启动TypeScript服务器

   cd mcpbench/matrix/templates/typescript/server/e2e
   npm install
   npm run dev
   

   服务器将在 http://localhost:8000 上启动

3. 运行Python客户端测试

   cd mcpbench/matrix/templates/python/client/e2e
   python3 test_connection.py
   

预期输出

你应该看到：

• 成功建立连接
• 工具发现和列出
• 工具调用和响应验证
• 清洁的会话终止

测试其他语言组合

可以按照类似的模式测试其他语言组合：

• Python客户端 ↔ Rust服务器
• TypeScript客户端 ↔ Python服务器
• Rust客户端 ↔ TypeScript服务器

每种组合在 matrix/templates/ 目录中都有自己的模板。

发展路线图

阶段 M1 - 矩阵扩展

• 目标：完成Python、TypeScript和Rust的N×N兼容性矩阵
• 交付成果：
  • 所有客户端-服务器组合正常工作
  • 自动化矩阵测试
  • 性能基准测试
  • 协议合规性验证

阶段 M2 - 高级测试

• 目标：全面的测试覆盖和边缘情况处理
• 交付成果：
  • 认证测试
  • 错误处理场景
  • 资源管理测试
  • 通知和流测试
  • 负载测试和压力测试

阶段 M3 - 生态系统集成

• 目标：与CI/CD和开发者工作流程集成
• 交付成果：
  • GitHub Actions集成
  • 自动兼容性报告
  • SDK版本兼容性跟踪
  • 性能退化检测

阶段 M4 - 扩展语言支持

• 目标：支持额外语言的SDK
• 交付成果：
  • Go SDK支持
• Java SDK支持
• C# SDK支持
• 社区SDK集成

阶段 M5 - 生产就绪

• 目标：企业级兼容性测试
• 交付成果：
  • 完整文档
  • 性能SLA
  • 安全测试
  • 合规性验证

贡献

我们欢迎来自MCP社区的贡献！以下是你可以帮助的方式：

开始贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 进行更改
4. 为新功能添加测试
5. 根据需要更新文档
6. 提交拉取请求

贡献领域

• 新的语言SDK支持：为额外的MCP SDK添加模板和测试
• 测试改进：增强现有测试或添加新的测试场景
• 文档：改善指南、示例和API文档
• 自动化：增强测试框架和CI/CD集成
• 性能：优化测试执行并添加性能基准

开发指南

• 代码风格：遵循每种语言现有的代码风格
• 测试：确保所有新功能都包含适当的测试
• 文档：更新相关的新功能文档
• 兼容性：验证更改不会破坏现有功能

报告问题

• 使用GitHub Issues报告错误或请求功能
• 包括详细的重现步骤
• 提供相关的日志和错误消息
• 指定受影响的语言组合

社区

• 加入我们在GitHub Discussions上的讨论
• 参与MCP社区活动
• 分享你的使用案例和需求
• 帮助其他贡献者

许可证

该项目采用MIT许可证 - 详情见LICENSE文件。

致谢

• 模型上下文协议团队，提供规范和官方SDK
• MCP社区，提供反馈和贡献
• 帮助构建和测试此框架的贡献者

---

MCPBench - 确保MCP跨所有语言和实现的兼容性。