@gleanwork/mcp服务器测试仪
测试和评估框架 模型上下文协议(MCP) 服务器。针对MCP工具编写确定性Playwright测试,或运行数据驱动的eval数据集,包括基于LLM的工具可发现性评估。
剧作家测试
这 mcp Playwright fixture连接到MCP服务器(stdio或HTTP),并公开高级API用于调用工具和断言响应。自定义匹配器使断言可读。```typescript snippet=snippets/basic-test.ts
import { test, expect } from '@gleanwork/mcp-server-tester/fixtures/mcp';
test('read_file returns file contents', async ({ mcp }) => {
const result = await mcp.callTool('read_file', { path: '/tmp/test.txt' });
expect(result).toContainToolText('Hello, world');
expect(result).not.toBeToolError();
});
test('server exposes required tools', async ({ mcp }) => {
const tools = await mcp.listTools();
expect(tools.map((t) => t.name)).toContain('read_file');
});
Playwright测试快速、确定,专为CI设计。将其用于回归测试、模式验证和协议一致性。该框架包括MCP规范的内置一致性检查。
可用匹配:
|匹配器|描述|
| ------------------------ | ---------------------------------------------------- |
| `toMatchToolResponse` |响应与预期值完全匹配(深度相等)|
| `toContainToolText` |响应包含预期的子字符串|
| `toMatchToolSchema` |响应根据Zod模式进行验证|
| `toMatchToolPattern` |响应与正则表达式模式匹配|
| `toMatchToolSnapshot` |响应与保存的基线匹配|
| `toBeToolError` |响应是(或不是)错误|
| `toHaveToolResponseSize` |响应大小在范围内|
| `toSatisfyToolPredicate` |响应满足自定义函数|
| `toHaveToolCalls` |LLM调用了预期的工具|
| `toHaveToolCallCount` |LLM进行了N次工具调用|
| `toPassToolJudge` |LLM根据量规评估响应质量|
## 评估数据集
Eval数据集允许您将测试用例定义为JSON文件,并使用 `runEvalDataset()`每个案例都指定了一个工具调用和一个或多个断言。```json snippet=snippets/eval-dataset.json
{
"name": "file-ops",
"cases": [
{
"id": "read-config",
"toolName": "read_file",
"args": { "path": "/tmp/config.json" },
"expect": {
"schema": "file-content",
"containsText": ["version", "name"]
}
},
{
"id": "read-readme",
"toolName": "read_file",
"args": { "path": "/tmp/README.md" },
"expect": {
"snapshot": "readme-snapshot"
}
}
]
}
``````typescript snippet=snippets/run-eval-dataset.ts
import { test, expect } from '@gleanwork/mcp-server-tester/fixtures/mcp';
import { loadEvalDataset, runEvalDataset } from '@gleanwork/mcp-server-tester';
import { z } from 'zod';
test('file operations eval', async ({ mcp }, testInfo) => {
const dataset = await loadEvalDataset('./data/evals.json', {
schemas: { 'file-content': z.object({ content: z.string() }) },
});
const result = await runEvalDataset({ dataset }, { mcp, testInfo });
expect(result.passed).toBe(result.total);
});
支持的断言类型:
| 类型 | 描述 |
|---|---|
containsText |
响应包括预期的子字符串 |
schema |
响应根据Zod模式进行验证 |
regex |
响应与模式匹配 |
snapshot |
响应与保存的基线匹配 |
judge |
LLM根据量规评估响应质量 |
toolsTriggered |
LLM调用了预期的工具(LLM主机模式) |
LLM主机模式
在LLM主机模式下,真正的LLM会收到服务器的工具列表和自然语言提示,然后决定调用哪些工具。这测试你的工具名称、描述和输入模式是否足够清晰,可以自主使用——这与工具是否返回正确的输出是一个不同的问题。```json snippet=snippets/mcp-host-dataset.json
{
"id": "find-config",
"mode": "mcp_host",
"scenario": "Find the application config file and return its contents",
"mcpHostConfig": {
"provider": "anthropic",
"model": "claude-opus-4-20250514"
},
"expect": {
"toolsTriggered": {
"calls": [{ "name": "read_file", "required": true }]
}
}
}
LLM主机模式进行真正的API调用并产生不确定的结果。使用 `iterations` 多次运行案例并测量通过率,而不是期望单次运行100%。请参阅 LLM主持人指南 用于配置和成本管理。
## 安装
需要Node.js 22+。```bash
npm install --save-dev @gleanwork/mcp-server-tester @playwright/test
Anthropic SDK仅用于LLM作为判断断言或使用Anthropics提供程序的LLM主机模式:```bash
npm install --save-dev @anthropic-ai/sdk
## 快速开始```bash
npx mcp-server-tester init
CLI向导创建 playwright.config.ts,示例测试,以及为您的服务器配置的示例eval数据集。请参阅 CLI指南 对于所有选项。
配置
将框架指向MCP服务器 playwright.config.ts:```typescript snippet=snippets/playwright-config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
reporter: [['list'], ['@gleanwork/mcp-server-tester/reporters/mcpReporter']],
projects: [
{
name: 'my-server',
use: {
mcpConfig: {
transport: 'stdio',
command: 'node',
args: ['server.js'],
},
},
},
],
});
对于HTTP服务器,设置 `transport: 'http'` 和 `serverUrl`。对于需要OAuth的服务器,请参阅 交通指南 和 CLI指南 用于身份验证设置,包括CI/CD令牌管理。
## 文档
- 快速开始 --详细的设置和配置
- 期望 --所有断言类型,包括快照清理程序
- LLM主机模拟 --工具可发现性测试
- API 参考
- 运输 --stdio和HTTP配置、OAuth
- CLI命令 --init、生成、登录、令牌
- UI报表程序 --用于测试结果的交互式web UI
- 发展 --贡献与建设
- 迁移指南(v0.12→ v1.0) --从1.0之前的版本升级
## 人工智能技能
安装人工智能技能,帮助您的编码助手生成测试、评估数据集和MCP主机评估:```bash
npx skills add -g gleanwork/mcp-server-tester
这将在全球范围内安装技能,以便在您的所有项目中都可以使用。包括四项技能:
| 技能 | 描述 |
|---|---|
mcp-tester-guide |
框架参考——匹配器、配置、身份验证、反模式 |
write-mcp-test |
生成直接模式剧作家测试 |
write-mcp-eval |
生成数据驱动的评估数据集 |
write-mcp-host-eval |
生成LLM主机模拟评估 |
与Claude Code、Cursor、Windsurf、Copilot和 40+其他AI代理.
示例
这 examples/ 目录包含完整的工作示例:
- 文件系统服务器/ --Anthropic文件系统MCP服务器的测试套件:5个Playwright测试,11个eval数据集案例,Zod模式验证。
- sqlite服务器/ --SQLite MCP服务器的测试套件:11个Playwright测试,14个eval数据集案例。
- 剧作家的基本用法/ --最小的剧作家模式。
已知限制
目前不支持这些MCP协议功能。这些是经过深思熟虑的范围决策,而不是bug:
- MCP资源(
listResources,readResource) - MCP提示(
listPrompts,getPrompt) - 服务器到客户端通知
- 流媒体工具响应(
callTool等待完整的响应)
如果其中任何一个影响您的用例,请打开一个问题。
许可证
麻省理工学院
