mcp-eval-runner

MCP Eval Runner

npm mcp-eval-runner 包

面向 MCP 服务和 Agent 工作流的标准化测试工具。使用 YAML 固定数据定义测试用例（步骤 → 预期工具调用 → 预期输出），直接从 MCP 客户端运行回归测试套件，并查看包含差异的通过／失败结果——无需离开 Claude Code 或 Cursor。

工具参考 | 配置 | 固定数据格式 | 参与贡献 | 故障排除 | 设计原则

主要功能

• YAML 固定数据：测试用例是版本控制中的普通文件，可比较差异、供人审阅并分享。
• 两种执行模式：实时模式会启动实际的 MCP 服务，并通过 stdio 调用工具；模拟模式会根据 expected_output 运行断言，无需服务。
• 可组合断言：每个步骤都可以组合使用 output_contains、output_not_contains、output_equals、output_matches、schema_match、tool_called 和 latency_under。
• 步骤输出传递：通过 {{steps.<step_id>.output}} 在后续步骤的输入中引用先前步骤的输出。
• 回归报告：将当前运行结果与任意历史运行结果进行比较，并显示发生的变化。
• 监视模式：文件变更时自动重新运行受影响的固定数据。
• 适用于 CI：提供 GitHub Action，可在每次配置变更时运行评估。

要求

• Node.js v22.5.0 或更高版本。
• npm。

开始使用

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest"]
    }
  }
}

默认情况下，评估固定数据会从当前工作目录下的 ./evals/ 加载。要使用其他路径：

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest", "--fixtures=~/my-project/evals"]
    }
  }
}

MCP 客户端配置

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

编写你的第一个提示词

在 evals/smoke.yaml 创建文件。添加 server 块以使用实时模式（推荐）：

name: smoke
description: "Verify eval runner itself is working"
server:
  command: node
  args: ["dist/index.js"]
steps:
  - id: list_check
    description: "List available test cases"
    tool: list_cases
    input: {}
    expect:
      output_contains: "smoke"

然后在 MCP 客户端中输入以下内容：

Run the eval suite.

客户端应为冒烟测试返回通过／失败结果。

固定数据格式

固定数据是放在固定数据目录中的 YAML（或 JSON）文件。每个文件定义一个测试用例。

顶层字段

字段	必填	说明
name	是	测试用例的唯一名称
description	否	供人阅读的说明
server	否	服务配置——若存在，则运行于实时模式；若不存在，则运行于模拟模式
steps	是	要执行的步骤数组

server 块（实时模式）

server:
  command: node # executable to spawn
  args: ["dist/index.js"] # arguments
  env: # optional environment variables
    MY_VAR: "value"

存在 server 时，评估运行器会将该服务作为子进程启动，通过 MCP stdio 传输连接，并针对实时服务调用每个步骤中的工具。

steps 数组

每个步骤包含以下字段：

字段	必填	说明
id	是	在固定数据中唯一的标识符（用于传递输出）
tool	是	要调用的 MCP 工具名称
description	否	供人阅读的步骤说明
input	否	传递给工具的键值对参数映射（默认值：{}）
expected_output	否	模拟模式中用作输出的字面字符串
expect	否	根据步骤输出评估的断言

执行模式

实时模式 — 测试夹具包含 server 块：

• 启动服务，并通过 MCP stdio 调用每个步骤指定的工具。
• 根据真实工具响应运行断言。
• 服务端错误会立即导致步骤（默认情况下也会导致测试用例）失败。

模拟模式 — 不包含 server 块：

• 不会启动服务。
• 每个步骤的输出取自 expected_output（若未设置，则为空字符串）。
• 根据该静态输出运行断言。
• 适用于编写测试和 CI 空跑，但如果未设置 expected_output，output_contains 断言将始终失败。

断言类型

所有断言都放在步骤的 expect 块中：

expect:
  output_contains: "substring" # output includes this text
  output_not_contains: "error" # output must NOT include this text
  output_equals: "exact string" # output exactly matches
  output_matches: "regex pattern" # output matches a regular expression
  tool_called: "tool_name" # verifies which tool was called
  latency_under: 500 # latency in ms must be below this threshold
  schema_match: # output (parsed as JSON) matches JSON Schema
    type: object
    required: [id]
    properties:
      id:
        type: number

同一个 expect 块中的多个断言都会被评估；只要有任何断言失败，该步骤就会失败。

步骤输出传递

在下游步骤的 input 中使用 {{steps.<step_id>.output}} 引用先前步骤的输出：

steps:
  - id: search_step
    tool: search
    input:
      query: "mcp eval runner"
    expected_output: "result: mcp-eval-runner v1.0"
    expect:
      output_contains: "mcp-eval-runner"

  - id: summarize_step
    tool: summarize
    input:
      text: "{{steps.search_step.output}}"
    expected_output: "Summary: mcp-eval-runner v1.0"
    expect:
      output_contains: "Summary"

输出传递在实时模式和模拟模式下均可用。

关于 create_test_case 的说明

使用 create_test_case 工具创建的测试夹具不包含 server 块。它们始终以模拟模式运行。若要使用实时模式，请手动将 server 块添加到生成的 YAML 文件中。

工具

运行

• run_suite — 执行 fixtures 目录中的所有测试夹具；返回通过/失败摘要
• run_case — 按名称运行单个测试夹具
• list_cases — 列出可用测试夹具及其步骤数量和描述

编写

• create_test_case — 创建新的 YAML 测试夹具文件（模拟模式；不包含 server 块）
• scaffold_fixture — 生成包含占位步骤和预填断言注释的样板测试夹具

报告

• regression_report — 将当前测试夹具状态与上次运行进行比较；显示回归和修复
• compare_results — 按运行 ID 对比两次特定运行
• generate_html_report — 为已完成的运行生成单文件 HTML 报告

运维

• evaluate_deployment_gate — CI 门禁；如果近期通过率低于可配置阈值，则失败
• discover_fixtures — 在一个或多个目录中发现测试夹具文件（遵循 FIXTURE_LIBRARY_DIRS）

配置

--fixtures / --fixtures-dir

用于加载 YAML/JSON 评估测试夹具文件的目录。

类型：string 默认值：./evals

--db / --db-path

用于存储运行历史记录的 SQLite 数据库文件路径。

类型：string 默认值：~/.mcp/evals.db

--timeout

将单个步骤标记为失败前的最长等待时间，单位为毫秒。

类型：number 默认值：30000

--watch

监视测试夹具目录，并在文件变更时自动重新运行受影响的测试夹具。

类型：boolean 默认值：false

--format

评估结果的输出格式。

类型：string 可选值：console、json、html 默认值：console

--concurrency

并行运行的测试用例数量。

类型：number 默认值：1

--http-port

在此端口启动 HTTP 服务，而不是使用 stdio 传输。

类型：number 默认值：已禁用（使用 stdio）

通过 JSON 配置中的 args 属性传递标志：

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest", "--watch", "--timeout=60000"]
    }
  }
}

设计原则

• 不使用模拟：实时模式评估针对真实服务运行。正确性不容妥协。
• 测试夹具是文本文件：使用版本控制管理 YAML/JSON；不使用专有格式或数据库。
• 优先自测：评估运行器自身的冒烟测试夹具用于测试评估运行器本身。

验证

发布新版本前，使用 MCP Inspector 验证服务，确认所有工具均正确暴露，且协议握手成功。

交互式 UI（打开浏览器）：

npm run build && npm run inspect

CLI 模式（适用于脚本 / CI）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_cases

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name run_case --tool-arg name=smoke

发布前运行，以发现工具注册和运行时启动方面的回归。

贡献

新的断言类型应添加到 src/assertions.ts 中 — 实现 Assertion 接口并添加测试。集成测试以单元测试的形式放在 tests/ 下，以评估测试夹具的形式放在 evals/ 下。

npm install && npm test

MCP 注册中心与市场

此插件可在以下平台获取：

• MCP Registry
• MCP Market

搜索 mcp-eval-runner。