MCP Eval Runner

npm mcp-eval-runner 包

用于MCP服务器和代理工作流的标准化测试工具。将测试用例定义为YAML fixture（步骤→预期的工具调用→预期的输出），直接从您的MCP客户端运行回归套件，并使用差异获得通过/失败结果-无需离开Claude Code或Cursor。

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

关键特性

• YAML装置测试用例是版本控制中的普通文件——可修改的、可审查的和可共享的。
• 两种执行模式：实时模式生成一个真正的MCP服务器，并通过工作室调用工具；模拟模式运行断言 expected_output 没有服务器。
• 可组合的断言:结合 output_contains， output_not_contains， output_equals， output_matches， schema_match， tool_called, latency_under 每一步。
• 阶跃输出管路：在下游输入中引用前一步的输出 {{steps.<step_id>.output}}。
• 回归的报告：将当前运行与以往运行进行比较，找出变化的地方。
• 观看模式：当文件更改时，自动重新运行受影响的fixture。
• CI-ready包含一个GitHub Action，用于在每次配置更改上运行eval。

需求

• 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.

您的客户端应该返回冒烟测试的通过/失败结果。

固定的格式

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

顶级域

server 阻塞（实时模式）

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

当 server eval运行程序将服务器作为子进程生成，通过MCP工作室传输连接，并针对活动服务器调用每个步骤的工具。

steps 数组

每一步都有以下字段：

执行模式

生活模式 -夹具有 server 布洛克:

• 服务器被生成，每个步骤通过MCP studio调用命名工具。
• 断言运行在真实的工具响应之上。
• 来自服务器的错误会导致步骤（默认情况下是case）立即失败。

模拟模式 ——不 server 布洛克:

• 没有服务器启动。
• 每个步骤的输出都取自 expected_output （如果没有，则为空字符串）。
• 断言根据静态输出运行。
• 对于创作和CI演练很有用，但是 output_contains 断言总是会失败 expected_output 未设置。

断言类型

所有断言都在一个步骤中 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

创建的fixture create_test_case 工具不包括 server 块。它们总是在模拟模式下运行。若要使用live模式，请添加 server 块手动添加到生成的YAML文件。

工具

运行

• run_suite -执行fixture目录下的所有fixture；返回通过/失败摘要
• run_case -按名称运行单个命名fixture
• 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文件 FIXTURE_LIBRARY_DIRS）

配置

--fixtures / --fixtures-dir

加载YAML/JSON eval fixture文件的目录。

类型: string 默认值: ./evals

--db / --db-path

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

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

--timeout

在将单个步骤标记为失败之前等待的最大时间（以毫秒为单位）。

类型: number 默认值: 30000

--watch

观察fixture目录，并在文件更改时自动重新运行受影响的fixture。

类型: boolean 默认值: false

--format

eval结果的输出格式。

类型: string 选择: console， json， html 默认值: console

--concurrency

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

类型: number 默认值: 1

--http-port

在此端口上启动HTTP服务器，而不是在演播室传输上启动。

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

传递标志 args 属性在JSON配置中：

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

设计原则

• 没有嘲笑：在实服务器上运行实时模式评估。正确性是不容置疑的。
• 固定装置是文本：版本控制中的YAML/JSON；没有专有格式或数据库。
• Dogfood-first： eval运行程序自己的烟雾装置测试eval运行程序本身。

验证

在发布新版本之前，请使用MCP Inspector验证服务器，以确认所有工具都正确公开并且协议握手成功。

交互式用户界面 (打开浏览器):

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/ 作为eval fixture。

npm install && npm test

MCP注册和市场

此插件可用于：

• MCP注册表
• MCP市场

搜索 mcp-eval-runner。