Server Tester

@gleanwork/mcp服务器测试仪

 ](https://www.npmjs.com/package/@gleanwork/mcp-server-tester)  

测试和评估框架 模型上下文协议（MCP） 服务器。针对MCP工具编写确定性Playwright测试，或运行数据驱动的eval数据集，包括基于LLM的工具可发现性评估。

剧作家测试

这 mcp Playwright fixture连接到MCP服务器（stdio或HTTP），并公开高级API用于调用工具和断言响应。自定义匹配器使断言可读。

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规范的内置一致性检查。

可用匹配：

评估数据集

Eval数据集允许您将测试用例定义为JSON文件，并使用 runEvalDataset()每个案例都指定了一个工具调用和一个或多个断言。

{
  "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"
      }
    }
  ]
}

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);
});

支持的断言类型：

LLM主机模式

在LLM主机模式下，真正的LLM会收到服务器的工具列表和自然语言提示，然后决定调用哪些工具。这测试你的工具名称、描述和输入模式是否足够清晰，可以自主使用——这与工具是否返回正确的输出是一个不同的问题。

{
  "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+。

npm install --save-dev @gleanwork/mcp-server-tester @playwright/test

Anthropic SDK仅用于LLM作为判断断言或使用Anthropics提供程序的LLM主机模式：

npm install --save-dev @anthropic-ai/sdk

快速开始

npx mcp-server-tester init

CLI向导创建 playwright.config.ts，示例测试，以及为您的服务器配置的示例eval数据集。请参阅 CLI指南 对于所有选项。

配置

将框架指向MCP服务器 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主机评估：

npx skills add -g gleanwork/mcp-server-tester

这将在全球范围内安装技能，以便在您的所有项目中都可以使用。包括四项技能：

与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 等待完整的响应）

如果其中任何一个影响您的用例，请打开一个问题。

许可证

麻省理工学院