MCP Eval Runner

MCP评估跑者

npm mcp-eval-runner 包裹

MCP服务器和代理工作流的标准化测试工具。将测试用例定义为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..output}}.
• 回归报告：将当前运行与任何过去的运行进行比较，并显示更改的内容。
• 观看模式：文件更改时自动重新运行受影响的夹具。
• CI就绪：包括一个GitHub操作，用于在每次配置更改时运行evals。

需求

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

入门

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

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

默认情况下，eval装置从以下位置加载 ./evals/ 在当前工作目录中。要使用其他路径，请执行以下操作：

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

MCP客户端配置

放大器·克劳德码·克莱恩·光标·VS码·风帆·泽德

您的第一个提示

在以下位置创建文件 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.

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

夹具格式

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

顶级字段

server 块（实时模式）

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

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

steps 数组

每个步骤都有以下字段：

执行模式

实时模式 --夹具具有 server 块：

• 生成服务器，每一步都通过MCP stdio调用指定的工具。
• 断言与真实的工具响应相反。
• 服务器的错误会导致该步骤（以及默认情况下的情况）立即失败。

模拟模式 --没有 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..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目录中的所有fixture；返回通过/失败摘要
• 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 eval夹具文件的目录。

类型： string 违约： ./evals

--db / --db-path

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

类型： string 违约： ~/.mcp/evals.db

--timeout

标记为失败之前等待单个步骤的最长时间（毫秒）。

类型： number 违约： 30000

--watch

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

类型： boolean 违约： false

--format

eval结果的输出格式。

类型： string 选择： console, json, html 违约： console

--concurrency

并行运行的测试用例数。

类型： number 违约： 1

--http-port

在此端口而不是stdio传输上启动HTTP服务器。

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

通过传递旗帜 args JSON配置中的属性：

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

设计原则

• 不要嘲笑：实时模式评估针对真实服务器运行。正确性是不可谈判的。
• 固定装置为文本：版本控制中的YAML/JSON；没有专有格式或数据库。
• 狗粮优先eval runner自己的烟雾装置测试eval runners本身。

验证

在发布新版本之前，使用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灯具。

npm install && npm test

MCP注册与市场

此插件可在以下网站上使用：

• MCP注册表
• MCP市场

搜索 mcp-eval-runner.