MCP Eval Runner

Entorno de pruebas estandarizado para servidores MCP y flujos de trabajo de agentes

Documentación

MCP Eval Runner

Paquete npm mcp-eval-runner

Un arnés de pruebas estandarizado para servidores MCP y flujos de trabajo de agentes. Define casos de prueba como archivos YAML (pasos → llamadas de herramientas esperadas → salidas esperadas), ejecuta suites de regresión directamente desde tu cliente MCP y obtén resultados de aprobado/fallido con diferencias, sin salir de Claude Code o Cursor.

Características clave

Fixtures YAML: Los casos de prueba son archivos simples en control de versiones: comparables, revisables y compartibles.
Dos modos de ejecución: El modo en vivo inicia un servidor MCP real y llama a las herramientas mediante stdio; el modo de simulación ejecuta aserciones contra expected_output sin un servidor.
Aserciones componibles: Combina output_contains, output_not_contains, output_equals, output_matches, schema_match, tool_called y latency_under por paso.
Canalización de salida de pasos: Referencia la salida de un paso anterior en entradas posteriores mediante {{steps.<step_id>.output}}.
Informes de regresión: Compara la ejecución actual con cualquier ejecución anterior y muestra qué cambió.
Modo de vigilancia: Vuelve a ejecutar automáticamente el fixture afectado cuando los archivos cambian.
Listo para CI: Incluye una GitHub Action para ejecutar evaluaciones en cada cambio de configuración.

Requisitos

Node.js v22.5.0 o superior.
npm.

Primeros pasos

Agrega la siguiente configuración a tu cliente MCP:

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

De forma predeterminada, los fixtures de evaluación se cargan desde ./evals/ en el directorio de trabajo actual. Para usar una ruta diferente:

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

Configuración del cliente MCP

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

Tu primer prompt

Crea un archivo en evals/smoke.yaml. Usa el modo en vivo (recomendado) incluyendo un bloque 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"

Luego ingresa lo siguiente en tu cliente MCP:

Run the eval suite.

Tu cliente debería devolver un resultado de aprobado/fallido para la prueba de humo.

Formato de fixtures

Los fixtures son archivos YAML (o JSON) ubicados en el directorio de fixtures. Cada archivo define un caso de prueba.

Campos de nivel superior

Campo	Obligatorio	Descripción
`name`	Sí	Nombre único para el caso de prueba
`description`	No	Descripción legible para humanos
`server`	No	Configuración del servidor: si está presente, se ejecuta en modo en vivo; si está ausente, se ejecuta en modo de simulación
`steps`	Sí	Matriz de pasos a ejecutar

Bloque `server` (modo en vivo)

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

Cuando server está presente, el ejecutor de evaluaciones inicia el servidor como un proceso hijo, se conecta mediante el transporte MCP stdio y llama a la herramienta de cada paso contra el servidor en vivo.

Matriz `steps`

Cada paso tiene los siguientes campos:

Campo	Obligatorio	Descripción
`id`	Sí	Identificador único dentro del fixture (se usa para la canalización de salida)
`tool`	Sí	Nombre de la herramienta MCP a llamar
`description`	No	Descripción del paso legible para humanos
`input`	No	Mapa clave-valor de argumentos pasados a la herramienta (predeterminado: `{}`)
`expected_output`	No	Cadena literal usada como salida en modo de simulación
`expect`	No	Aserciones evaluadas contra la salida del paso

Modos de ejecución

Modo en vivo: el fixture tiene un bloque server:

El servidor se inicia y cada paso llama a la herramienta nombrada mediante MCP stdio.
Las aserciones se ejecutan contra la respuesta real de la herramienta.
Los errores del servidor hacen que el paso (y de forma predeterminada el caso) falle inmediatamente.

Modo de simulación: sin bloque server:

No se inicia ningún servidor.
La salida de cada paso se toma de expected_output (o una cadena vacía si está ausente).
Las aserciones se ejecutan contra esa salida estática.
Útil para la redacción y pruebas en seco de CI, pero las aserciones output_contains siempre fallarán si expected_output no está configurado.

Tipos de aserciones

Todas las aserciones van dentro del bloque expect de un paso:

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

Múltiples aserciones en un bloque expect se evalúan todas; el paso falla si alguna aserción falla.

Canalización de salida de pasos

Referencia la salida de un paso anterior en el input de un paso posterior usando {{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"

La canalización funciona tanto en modo en vivo como en modo de simulación.

Nota sobre `create_test_case`

Los fixtures creados con la herramienta create_test_case no incluyen un bloque server. Siempre se ejecutan en modo de simulación. Para usar el modo en vivo, agrega un bloque server manualmente al archivo YAML generado.

Herramientas

Ejecución

run_suite: ejecuta todos los fixtures en el directorio de fixtures; devuelve un resumen de aprobado/fallido
run_case: ejecuta un solo fixture nombrado por nombre
list_cases: enumera los fixtures disponibles con recuentos de pasos y descripciones

Redacción

create_test_case: crea un nuevo archivo de fixture YAML (modo de simulación; sin bloque server)
scaffold_fixture: genera un fixture de plantilla con pasos de marcador de posición y comentarios de aserción prellenados

Informes

regression_report: compara el estado actual del fixture con la última ejecución; muestra regresiones y correcciones
compare_results: compara dos ejecuciones específicas por ID de ejecución
generate_html_report: genera un informe HTML de un solo archivo para una ejecución completada

Operaciones

evaluate_deployment_gate: puerta de CI; falla si la tasa de aprobación reciente cae por debajo de un umbral configurable
discover_fixtures: descubre archivos de fixture en uno o más directorios (respeta FIXTURE_LIBRARY_DIRS)

Configuración

`--fixtures` / `--fixtures-dir`

Directorio para cargar archivos de fixture de evaluación YAML/JSON.

Tipo: string Predeterminado: ./evals

`--db` / `--db-path`

Ruta al archivo de base de datos SQLite utilizado para almacenar el historial de ejecuciones.

Tipo: string Predeterminado: ~/.mcp/evals.db

`--timeout`

Tiempo máximo en milisegundos para esperar un solo paso antes de marcarlo como fallido.

Tipo: number Predeterminado: 30000

`--watch`

Vigila el directorio de fixtures y vuelve a ejecutar automáticamente el fixture afectado cuando los archivos cambian.

Tipo: boolean Predeterminado: false

`--format`

Formato de salida para los resultados de evaluación.

Tipo: string Opciones: console, json, html Predeterminado: console

`--concurrency`

Número de casos de prueba para ejecutar en paralelo.

Tipo: number Predeterminado: 1

`--http-port`

Inicia un servidor HTTP en este puerto en lugar del transporte stdio.

Tipo: number Predeterminado: deshabilitado (usa stdio)

Pasa las banderas mediante la propiedad args en tu configuración JSON:

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

Principios de diseño

Sin simulación: Las evaluaciones en modo en vivo se ejecutan contra servidores reales. La corrección no es negociable.
Los fixtures son texto: YAML/JSON en control de versiones; sin formatos propietarios ni bases de datos.
Primero el uso propio: El fixture de prueba de humo del propio ejecutor de evaluaciones prueba al ejecutor de evaluaciones.

Verificación

Antes de publicar una nueva versión, verifica el servidor con MCP Inspector para confirmar que todas las herramientas estén expuestas correctamente y que el protocolo de negociación tenga éxito.

Interfaz interactiva (abre el navegador):

npm run build && npm run inspect

Modo CLI (scriptado / apto para 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

Ejecuta antes de publicar para detectar regresiones en el registro de herramientas y el inicio del tiempo de ejecución.

Contribuciones

Los nuevos tipos de aserciones van en src/assertions.ts: implementa la interfaz Assertion y agrega una prueba. Las pruebas de integración viven bajo tests/ como pruebas unitarias y bajo evals/ como fixtures de evaluación.

npm install && npm test

Registro MCP y Marketplace

Este plugin está disponible en:

Busca mcp-eval-runner.

MCP Eval Runner

Documentación

MCP Eval Runner

Características clave

Requisitos

Primeros pasos

Configuración del cliente MCP

Tu primer prompt

Formato de fixtures

Campos de nivel superior

Bloque server (modo en vivo)

Matriz steps

Modos de ejecución

Tipos de aserciones

Canalización de salida de pasos

Nota sobre create_test_case

Herramientas

Ejecución

Redacción

Informes

Operaciones

Configuración

--fixtures / --fixtures-dir

--db / --db-path

--timeout

--watch

--format

--concurrency

--http-port

Principios de diseño

Verificación

Contribuciones

Registro MCP y Marketplace

Bloque `server` (modo en vivo)

Matriz `steps`

Nota sobre `create_test_case`

`--fixtures` / `--fixtures-dir`

`--db` / `--db-path`

`--timeout`

`--watch`

`--format`

`--concurrency`

`--http-port`