MCP 协议验证器

一个用于 模型上下文协议 (MCP) 的测试套件和参考实现。

摘要

MCP 协议验证器提供了一个全面的环境，用于测试和验证 MCP 服务器的实现。 凭借 STDIO 和 HTTP 传输的参考实现，以及广泛的测试框架，它可以确保开发人员验证他们的服务器是否符合 MCP 规范。 模块化架构支持各种服务器配置、传输方法，并提供详细的合规性报告，使其成为 MCP 服务器开发和验证的重要工具。

概述

此存储库包含：

1. 最小 MCP 服务器：使用 STDIO 传输的参考实现
2. 最小 HTTP MCP 服务器：使用 HTTP 传输的参考实现
3. MCP 测试框架：一个全面的测试框架，用于验证 MCP 服务器的实现

当前的实现完全符合最新的 MCP 协议规范 (2025-03-26)。

✅ 参考实现的所有测试均通过！

---

参考实现

最小 MCP 服务器 (STDIO)

一个简单的参考实现，它使用 STDIO 进行传输并支持：

• 基本协议操作（初始化、关闭）
• 同步工具调用
• 异步工具调用（适用于 2025-03-26）
• 用于文件系统操作的实用工具

# 运行服务器
python ./minimal_mcp_server/minimal_mcp_server.py

支持的工具

• echo: 回显输入文本
• add: 添加两个数字
• sleep: 休眠指定的秒数（用于测试异步操作）
• list_directory: 列出目录中的文件
• read_file: 读取文件
• write_file: 写入文件

最小 HTTP MCP 服务器

一个使用 HTTP 传输的参考实现，具有：

• 基于 HTTP 的 JSON-RPC 2.0 实现
• 支持两个协议版本（2024-11-05 和 2025-03-26）
• 同步和异步工具调用
• 资源功能（适用于 2025-03-26）
• 批量请求支持
• 对浏览器客户端的 CORS 支持

# 使用默认设置运行服务器 (localhost:8000)
python ./minimal_http_server/minimal_http_server.py

# 使用自定义主机和端口运行
python ./minimal_http_server/minimal_http_server.py --host 0.0.0.0 --port 8080

# 运行基本的 HTTP 测试套件
python ./minimal_http_server/test_http_server.py

# 针对 HTTP 服务器运行合规性测试
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000 --protocol-version 2025-03-26

有关更多详细信息，请参见 HTTP Server README。

---

MCP 测试框架

一个灵活的框架，用于验证 MCP 服务器是否符合协议规范。

主要特点

• 支持 2024-11-05 和 2025-03-26 协议版本
• 支持 STDIO 和 HTTP 传输协议
• 适应服务器功能的动态工具测试
• 详细的合规性报告
• 用于有针对性的功能测试的可配置测试模式
• 综合规范要求测试 (MUST, SHOULD, MAY)
• 用于各种实现的服务器配置系统

快速开始

对于 STDIO 服务器：

# 基本交互 - 验证服务器是否工作的最简单测试
python -m mcp_testing.scripts.basic_interaction --server-command "./minimal_mcp_server/minimal_mcp_server.py"

# 运行完整的合规性测试
python -m mcp_testing.scripts.compliance_report --server-command "./minimal_mcp_server/minimal_mcp_server.py" --protocol-version 2025-03-26

对于 HTTP 服务器：

# 快速 HTTP 测试
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26

# 简单的连接性检查
python minimal_http_server/check_server.py http://localhost:8000/mcp

测试通过 Pip 安装的 MCP 服务器

要测试通过 pip 安装的 MCP 服务器（如 mcp-server-fetch）：

1. 安装在与测试框架相同的环境中：

# 确保您在正确的虚拟环境中
source .venv/bin/activate

# 安装服务器包和依赖项
pip install mcp-server-fetch sseclient-py==1.7.2  # 对于 fetch 服务器示例

2. 使用模块样式命令运行测试：

# 基本交互测试
python -m mcp_testing.scripts.basic_interaction --server-command "python -m mcp_server_fetch" --protocol-version 2024-11-05

# 仅使用工具模式的合规性测试
python -m mcp_testing.scripts.compliance_report --server-command "python -m mcp_server_fetch" --protocol-version 2024-11-05 --test-mode tools

3. 处理超时问题：

# 为工具测试与其他测试设置超时
python -m mcp_testing.scripts.compliance_report --server-command "python -m mcp_server_fetch" --protocol-version 2024-11-05 --test-timeout 30 --tools-timeout 15

与工具相关的超时测试被视为非关键测试，允许测试继续进行。

故障排除 Pip 安装的服务器

• “Failed to start transport” 错误：确保服务器安装在同一环境中
• 找不到模块错误：使用 python -c "import module_name" 验证模块安装
• 依赖项问题：安装所有必需的依赖项
• 挂起/超时问题：使用超时参数设置适当的值

高级测试选项

服务器配置系统

该框架包括一个用于不同服务器实现的配置系统：

• JSON 配置文件：mcp_testing/server_configs/ 中的服务器特定配置
• 自动检测：根据命令模式识别服务器
• 环境管理：管理每个服务器所需的环境变量

用法示例：

# 需要 API 密钥的服务器
API_KEY="your_key" python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server"

# 使用默认值模式
MCP_DEFAULT_API_KEY="default_key" python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server"

有关详细信息，请参见 Server Configurations README。

传输特定测试

STDIO 测试：

# 完整的合规性测试
python -m mcp_testing.scripts.compliance_report --server-command "./minimal_mcp_server/minimal_mcp_server.py" --protocol-version 2025-03-26

# 仅规范要求测试
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --spec-coverage-only --protocol-version 2025-03-26

HTTP 测试：

# 使用 HTTP 测试脚本
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26

# 使用可执行脚本
./mcp_testing/bin/http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26

测试自定义选项

# 跳过旧服务器的异步测试
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --skip-async

# 仅测试动态工具功能
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --dynamic-only

# 使用特定的测试子集
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --test-mode tools

# 跳过已知失败的测试
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --skip-tests "test_shutdown,test_exit_after_shutdown"

# 自动检测服务器功能和协议版本
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --auto-detect

# 设置自定义超时
python -m mcp_testing.scripts.compliance_report --server-command "/path/to/server" --test-timeout 30 --tools-timeout 15

# HTTP 调试输出
python -m mcp_testing.scripts.http_test --server-url http://example.com/mcp --debug

生成合规性报告

# STDIO 服务器报告
python -m mcp_testing.scripts.compliance_report --server-command "./minimal_mcp_server/minimal_mcp_server.py" --protocol-version 2025-03-26 --output-dir "./reports"

# HTTP 服务器报告
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26 --output-dir "./reports"

报告包括：

• 测试结果摘要
• 通过和失败测试的详细列表
• 规范覆盖率指标
• 服务器功能概述
• 合规性状态和分数

基本测试

对于存在潜在问题的服务器：

# 验证服务器初始化并列出工具
python -m mcp_testing.scripts.basic_interaction --server-command "python -m mcp_server_fetch" --protocol-version 2024-11-05

此脚本：

• 启动服务器
• 发送初始化请求
• 验证响应
• 列出工具（如果服务器响应正确）
• 正常终止

对于初始验证和故障排除很有用。

运行测试套件

# 运行整个测试套件
pytest

# 运行特定的测试模块
pytest mcp_testing/tests/base_protocol/

---

许可证

SPDX-License-Identifier: AGPL-3.0-or-later 版权所有 (c) 2025 Scott Wilcox