MCP-测试框架
项目介绍
MCP-Jest
首个（或许唯一的）针对模型上下文协议（MCP）服务器的测试框架——像 Jest，但专为 MCP 设计
🚀 终于来了！ 信心满满地测试你的 MCP 服务器。无需手动验证，不再有部署失败的情况。
遇到的问题
你构建了一个连接 AI 助手到数据库、文件系统或 API 的 MCP 服务器。但是如何知道它真的工作了呢？
npm install mcp-jest
为什么选择 mcp-jest？
遇到的问题 😤
构建 MCP 服务器？你可能遇到过这些问题：
- ❌ 手动测试地狱：手动连接客户端以测试每个更改
- ❌ 无声失败：服务器崩溃而你不知道，直到 Claude Code 崩溃
- ❌ 没有 CI/CD：无法在流水线中自动化 MCP 服务器测试
- ❌ 调试噩梦：当出现问题时，你不知道哪里出了错
- ❌ 部署恐惧：每次更新都是一场赌博
解决方案 ✨
mcp-jest 是 MCP 生态系统中缺失的一环：
- ✅ 自动化测试：编写一次测试，到处运行
- ✅ 即时反馈：立即知道何时出现问题
- ✅ CI/CD 就绪：无缝集成到任何构建流水线
- ✅ 清晰的结果：详细的报告展示哪些工作正常，哪些不正常
- ✅ 自信部署：生产前进行全面测试
📋 目录
📚 文档：https://mcp-jest.ddiy.diy/
⚡ 快速开始 (30 秒)
1. 安装
npm install mcp-jest # 作为依赖项
npm install -g mcp-jest # 或全局安装用于 CLI
2. 测试你的服务器
import { mcpTest } from 'mcp-jest';
const results = await mcpTest(
{ command: 'node', args: ['./server.js'] },
{ tools: ['search', 'email'] }
);
console.log(`${results.passed}/${results.total} 测试通过`);
3. 或使用 CLI
mcp-jest node ./server.js --tools search,email
就这样！ 你的 MCP 服务器现在已经被测试了。🎉
🔥 关键特性
🧪 简单易用的 API
一个函数调用即可测试整个服务器。无需复杂的设置，无需样板代码。
📝 声明式测试
描述要测试的内容，而不是如何测试。专注于你的服务器逻辑，而非测试基础设施。
🔍 全面覆盖
- 连接测试：服务器启动并响应
- 能力发现：工具/资源/提示存在
- 功能性测试：一切实际工作
- 验证：结果符合预期
🚀 面向生产
- CI/CD 集成：与 GitHub Actions、Jenkins 等兼容
- 快速执行：完整的测试套件在 500 毫秒内完成
- 详细报告：确切知道什么失败以及原因
- 零依赖：仅使用官方 MCP SDK
🛠️ 灵活使用
- 库：集成到现有的测试套件
- CLI：适合脚本和流水线
- 配置文件：复杂测试场景
- TypeScript：完全类型安全
📸 快照测试
- 捕获输出：保存 MCP 响应作为快照
- 检测变化：知道输出意外改变时
- 轻松更新：使用单个标志更新快照
- 选择性快照：选择特定字段进行跟踪
🎯 测试过滤 (新 v1.0.10!)
- 过滤测试：运行匹配模式的测试
--filter - 跳过测试：排除某些测试
--skip - 通配符支持：使用
*进行灵活模式匹配 - 快速迭代：开发期间专注于特定测试
🌐 HTTP 传输支持 (新 v1.0.13!)
- 多种传输方式：通过 stdio、HTTP 流式传输或 SSE 测试服务器
- 灵活连接：支持远程和本地 HTTP 服务器
- 简单配置：简单的 CLI 标志或配置文件设置
- 向后兼容：现有 stdio 测试无需更改
🛡️ 增强兼容性 (新 v1.0.13!)
- FastMCP 支持：适用于实现部分 MCP 协议的服务器
- 优雅错误处理：优雅处理“方法未找到”错误
- 灵活服务器：测试只实现某些功能的服务器
🎯 实际案例
测试搜索服务器
const results = await mcpTest(
{ command: 'python', args: ['search-server.py'] },
{
tools: {
search: {
args: { query: '人工智能' },
expect: result => result.results.length > 0
},
autocomplete: {
args: { partial: 'artif' },
expect: 'suggestions.length >= 3'
}
}
}
);
CI/CD 集成
# .github/workflows/test.yml
- name: 测试 MCP 服务器
run: |
npm install -g mcp-jest
mcp-jest node ./dist/server.js --tools "search,analyze"
开发流程
{
"scripts": {
"test": "jest && npm run test:mcp",
"test:mcp": "mcp-jest node ./server.js --tools search,email",
"dev": "concurrently 'npm run dev:server' 'npm run test:mcp:watch'"
}
}
快照测试 (新！)
// 捕获并比较 MCP 输出随时间的变化
const results = await mcpTest(
{ command: 'node', args: ['./weather-server.js'] },
{
tools: {
getWeather: {
args: { city: '伦敦' },
snapshot: {
exclude: ['temperature', 'timestamp'], // 排除变化的数据
properties: ['format', 'units', 'structure'] // 跟踪结构
}
}
}
}
);
// 当更改是故意时更新快照
// mcp-jest node ./server.js --update-snapshots
测试过滤 (新！)
# 只运行与搜索相关的测试
mcp-jest node ./server.js --tools "search,email,weather" --filter search
# 开发期间跳过电子邮件测试
m
mcp-jest node ./server.js --tools "search,email,weather" --skip email
# 使用通配符进行灵活过滤
mcp-jest node ./server.js --tools "getUser,getUserProfile,updateUser" --filter "user*"
# 结合其他选项
mcp-jest node ./server.js --filter search --timeout 5000 --update-snapshots
HTTP 传输测试 (新！)
# 测试 stdio 服务器 (默认)
mcp-jest node ./server.js --tools search,email
# 测试 HTTP 流式传输服务器
mcp-jest --transport streamable-http --url http://localhost:3000 --tools search
# 测试 SSE 服务器
mcp-jest --transport sse --url http://api.example.com/sse --tools search,email
# 使用配置文件进行 HTTP 传输
cat > mcp-jest.json << EOF
{
"server": {
"transport": "streamable-http",
"url": "http://localhost:3000/mcp"
},
"tests": {
"tools": ["search", "calculate"],
"timeout": 60000
}
}
EOF
mcp-jest --config mcp-jest.json
📖 CLI 参考
命令行选项
mcp-jest [OPTIONS] [SERVER_COMMAND]
选项
| 选项 | 描述 | 示例 |
|---|---|---|
-h, --help | 显示帮助信息 | mcp-jest --help |
-v, --version | 显示版本 | mcp-jest --version |
-c, --config <file> | 从 JSON 文件加载配置 | mcp-jest --config test.json |
-s, --server <cmd> | 要测试的服务器命令 (仅限 stdio) | mcp-jest --server "node server.js" |
--transport <type> | 传输类型：stdio, sse, streamable-http | mcp-jest --transport streamable-http |
--url <url> | 服务器 URL (HTTP 传输必需) | mcp-jest --url http://localhost:3000 |
--args <args> | 逗号分隔的服务器参数 | mcp-jest node server.js --args "port=3000,debug" |
-t, --tools <tools> | 逗号分隔的工具列表 | mcp-jest --tools search,calculate |
-r, --resources <res> | 逗号分隔的资源列表 | mcp-jest --resources "data/*,config.json" |
-p, --prompts <prompts> | 逗号分隔的提示列表 | mcp-jest --prompts analyze,summarize |
--timeout <ms> | 测试超时时间 (毫秒) | mcp-jest --timeout 60000 |
-u, --update-snapshots | 更新快照而不是比较 | mcp-jest -u |
-f, --filter <pattern> | 只运行匹配模式的测试 | mcp-jest --filter "search*" |
--skip <pattern> | 跳过匹配模式的测试 | mcp-jest --skip "*test*" |
🚀 生态系统集成
与一切兼容
- MCP 服务器：任何语言，任何框架
- AI 客户端：Claude Code，自定义客户端，SDK
- CI/CD：GitHub Actions，GitLab CI，Jenkins，CircleCI
- 包管理器：npm，pnpm，yarn
- 测试运行器：Jest，Vitest，Mocha (作为库)
流行用例
- 开发：开发过程中即时测试更改
- CI/CD：构建流水线中的自动化测试
- 部署：上线前验证服务器是否正常工作
- 监控：生产环境中的定期健康检查
- 文档：确保示例实际工作
解决的问题
┌─────────────────────┐ ┌─────────────────────┐
│ │ │ │
│ MCP 服务器开发 │ ??? │ 如何知道我的 │
│ 实现工具 │ ──────> │ 服务器工作？ │
│ │ │ │
└─────────────────────┘ └─────────────────────┘
在 MCP-JEST 之前：手动测试，无自动化，无信心
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ │ │ │ │ │
│ MCP 服务器开发 │ ──────> │ MCP-JEST │ ──────> │ ✓ 自动化测试 │
│ 实现工具 │ │ 测试框架 │ │ ✓ CI/CD 就绪 │
│ │ │ │ │ ✓ 快照测试 │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
有了 MCP-JEST：自动化、可重复、有信心的测试
架构概述
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP-JEST 架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CLI │ │ 库 │ │ 类型 │ │
│ │ (cli.ts) │ │ (index.ts) │ │ (types.ts) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────────┴────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ MCPTestRunner │ │
│ │ (runner.ts) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ │
│ │ MCPTestClient│ │SnapshotManager│ │ Expectation │ │
│ │ (client.ts) │ │ (snapshot.ts) │ │ Evaluator │ │
│ └──────┬───────┘ └───────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ MCP 协议通信 │ │
│ │ (通过 @modelcontextprotocol/sdk) │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
└─────────────────────────────┼──────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 你的 MCP 服务器│
│ (正在测试) │
└─────────────────┘
MCP-JEST 因其协议特定设计而独特
┌─────────────────────────────────────────────────────────┐
│ 通用测试 vs MCP-JEST │
├─────────────────────────────────────────────────────────┤
│ │
│ 通用测试框架： │
│ ┌─────────┐ │
│ │ 测试 │──[HTTP/函数调用]──> 响应 │
│ └─────────┘ │
│ │
│ MCP-JEST： │
│ ┌─────────┐ │
│ │ 测试 │ │
│ └────┬────┘ │
│ │ │
│ ├──[1. 进程管理] │
│ ├──[2. StdioTransport 设置] │
│ ├──[3. MCP 协议握手] │
│ ├──[4. 能力发现] │
│ ├──[5. 工具/资源/提示执行] │
│ └──[6. 结构化验证] │
│ │
└─────────────────────────────────────────────────────────┘
MCP-JEST 因其全面测试覆盖而独特
┌────────────────────────────────────────────────┐
│ MCP-JEST 测试覆盖 │
├────────────────────────────────────────────────┤
│ │
│ 连接层： │
│ • 服务器启动 │
│ • 协议握手 │
│ • 超时处理 │
│ │
│ 发现层： │
│ • 可用工具 │
│ • 可用资源 │
│ • 可用提示 │
│ • 能力匹配 │
│ │
│ 功能层： │
│ • 带参数的工具执行 │
│ • 资源读取 │
│ • 提示生成 │
│ • 错误处理 │
│ │
│ 验证层： │
│ • 响应结构 │
│ • 内容验证 │
│ • 快照比较 │
│ • 自定义