# mcp-eval-runner 中文文档

规范地址：https://npmcn.com/package/mcp-eval-runner/

版本：1\.0\.1
npm 元数据更新时间：2026-11-04T02:14:11.764Z
中文译文更新时间：2026-11-04T04:02:48.652Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/mcp-eval-runner
原文对照：https://npmcn.com/package/mcp-eval-runner/?lang=original
项目主页：https://github.com/dbsectrainer/mcp-eval-runner#readme
源码仓库：https://github.com/dbsectrainer/mcp-eval-runner

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：148 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.5\.0
- 运行依赖：5 个
- 首次发布：2026-03-23T19:56:29.360Z
- 最新版本发布：2026-11-04T02:14:11.598Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于MCP服务器和代理工作流的标准化测试工具

## 安装

```sh
npm install mcp-eval-runner
```

也可以使用：`pnpm add mcp-eval-runner`、`yarn add mcp-eval-runner`、`bun add mcp-eval-runner`

## README

# MCP Eval Runner

npm `mcp-eval-runner` 包

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

[参考工具](https://npmcn.com/package/mcp-eval-runner/#readme-tools) | [配置](https://npmcn.com/package/mcp-eval-runner/#readme-configuration) | [固定的格式](https://npmcn.com/package/mcp-eval-runner/#readme-fixture-format) | [贡献](https://npmcn.com/package/mcp-eval-runner/#readme-contributing) | [故障排除](https://npmcn.com/package/mcp-eval-runner/#readme-troubleshooting) | [设计原则](https://npmcn.com/package/mcp-eval-runner/#readme-design-principles)

## 关键特性

-   **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客户端中添加以下配置：

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

默认情况下，从 `./evals/` 在当前工作目录中。使用不同的路径：

```json
{
  "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` 布洛克:

```yaml
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）文件。每个文件定义一个测试用例。

### 顶级域

| 场 | 要求 | 描述 |
| --- | --- | --- |
| `name` | 是 | 测试用例的唯一名称 |
| `description` | 否 | 人类可读的描述 |
| `server` | 否 | 服务器配置-如果存在，则运行 **生活模式**;如果缺席，就补上 **模拟模式** |
| `steps` | 是 | 要执行的步骤数组 |

### `server` 阻塞（实时模式）

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

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

### `steps` 数组

每一步都有以下字段：

| 场 | 要求 | 描述 |
| --- | --- | --- |
| `id` | 是 | 夹具内的唯一标识符（用于输出管道） |
| `tool` | 是 | 要调用的MCP工具名称 |
| `description` | 否 | 人类可读的步骤描述 |
| `input` | 否 | 传递给工具的参数的键值映射(默认值： `{}`） |
| `expected_output` | 否 | 在仿真模式下用作输出的字面值字符串 |
| `expect` | 否 | 根据步骤输出计算断言 |

### 执行模式

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

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

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

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

### 断言类型

所有断言都在一个步骤中 `expect` 布洛克:

```yaml
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}}`：

```yaml
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配置中：

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

## 设计原则

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

## 验证

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

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

```bash
npm run build && npm run inspect
```

**CLI模式** （脚本/ ci友好）：

```bash
# 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。

```bash
npm install && npm test
```

## MCP注册和市场

此插件可用于：

-   [MCP注册表](https://registry.modelcontextprotocol.io/)
-   [MCP市场](https://mcpmarket.com/)

搜索 `mcp-eval-runner`。

## 常见问题

### mcp-eval-runner 是什么？

用于MCP服务器和代理工作流的标准化测试工具

### 如何安装 mcp-eval-runner？

在项目目录运行 npm install mcp-eval-runner，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-eval-runner，可以用 npx mcp-eval-runner 直接运行。

### mcp-eval-runner 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/mcp-eval-runner 是否存在。

### mcp-eval-runner 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### mcp-eval-runner 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.5\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### mcp-eval-runner 可以商用吗？

mcp-eval-runner 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### mcp-eval-runner 还在维护吗？

最新版本 1\.0\.1 发布于 2026/11/04（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。