MCP y salida JSON

¿Para quién es esta página? Para quien quiera conectar becwright a una herramienta de IA o a un script. La instalación normal ya cuida tus commits por sí sola — esta página trata la capa siguiente: dejar que un agente de IA (u otro programa) lea los resultados de becwright y actúe sobre ellos. Si hacia allá vas, todo lo que necesitas está abajo.

becwright expone sus resultados en formato legible por máquina de dos maneras: una salida JSON para scripts y un servidor MCP para agentes de IA. (MCP — Model Context Protocol — es un enchufe estándar para darles habilidades extra a las herramientas de IA.)

becwright check --json

Igual que becwright check, pero imprime un resumen JSON en vez de texto coloreado y se consume sin parsear. El código de salida no cambia (1 si falló una regla blocking, si no 0).

{
  "rule_count": 3,
  "checked_files": 1,
  "blocked": true,
  "results": [
    {
      "id": "no-debugger-js",
      "severity": "blocking",
      "passed": false,
      "intent": "Do not leave 'debugger;' in JavaScript/TypeScript code.",
      "why_it_matters": "A forgotten 'debugger' halts execution ...",
      "output": "app.js:1\n      > function f(){ debugger; }"
    }
  ]
}

Esto no necesita ninguna dependencia extra y funciona también desde el binario autónomo.

¿Cómo debería leer un agente esta salida?

Los dos campos de nivel superior sobre los que ramificar son blocked y results. blocked refleja el código de salida: es true exactamente cuando falló al menos una regla blocking, así que un script puede condicionar sobre cualquiera de las dos señales. rule_count y checked_files son contexto — cuántas reglas corrieron y sobre cuántos archivos.

Cada entrada de results describe una regla. passed y severity dan el veredicto (los fallos con severity: "warning" nunca bloquean); intent dice qué exige la regla; why_it_matters explica el razonamiento detrás; y output es el stdout del propio check, que apunta al archivo y la línea del problema. Un agente que trabaja el ciclo lee intent y why_it_matters, arregla el código y vuelve a llamar a check hasta que blocked regrese en false — mira Agentes de IA para ese ciclo de punta a punta.

Servidor MCP

becwright mcp levanta un servidor Model Context Protocol sobre stdio, así cualquier agente con soporte MCP (Claude, Cursor, Windsurf, …) obtiene becwright como herramientas estructuradas.

Requiere el extra opcional mcp:

pipx install "becwright[mcp]"     # o: pip install "becwright[mcp]"

Herramientas

Herramienta	Argumentos	Devuelve
check	all_files (bool), path (dir de repo opcional)	el mismo resumen que check --json
list_checks	—	los checks incluidos como {name, description}
list_rules	path (dir de repo opcional)	las reglas del repo como registros de decisión (id, severity, intent, why_it_matters, rejected_alternatives, paths, check)
preview_rule	check, paths, exclude (opcional), all_files, path	{matched_files, passed, output, note} — un dry-run sin escribir la regla
propose_rules_from_claude_md	path (dir de repo opcional)	{rules, unmapped_hint} — las reglas que becwright deriva del CLAUDE.md del repo
add_rule	id, check, paths, intent, why_it_matters, severity, exclude, confirm, path	escribe una regla en .bec/rules.yaml — preview salvo confirm=true

check y list_checks son el lado de lectura que un agente usa para trabajar un commit fallido. Las otras cuatro son el lado de autoría — leer las decisiones que un repo ya impone y luego redactar nuevas de forma segura.

list_rules es la memoria de decisiones: devuelve cada regla con su intent, el motivo detrás y el check que la impone, para que un agente pueda leer las decisiones que no debe violar antes de escribir código — los mismos datos que check muestra al fallar, pero disponibles de antemano. Refleja el CLI becwright why --json.

propose_rules_from_claude_md devuelve las reglas que becwright puede derivar determinísticamente de la prosa (cada una con la frase que la disparó) — el punto de partida del agente. preview_rule deja que el agente valide una regla antes de escribirla: dado un check candidato y sus paths, corre el check contra el repo e informa cuántos archivos seleccionan los globs, si la regla pasaría y qué marca — detectando una regla que no matchea nada o que nombra un check inexistente.

add_rule persiste una regla validada. Nunca escribe a ciegas: con confirm=false (el default) devuelve un preview de lo que escribiría; solo confirm=true la escribe. Por seguridad acepta solo checks built-in (becwright run <name>) — una regla con un comando shell arbitrario corre en cada commit, así que esas van por el becwright import del CLI, que le muestra el código a un humano.

Juntas definen el reparto: becwright garantiza la ejecución; el agente hace la traducción, arrancando de propose_rules_from_claude_md, usando list_checks como vocabulario, extendiendo con reglas para lo que el extractor no captó, usando preview_rule para chequear cada una, y add_rule (confirmado) para persistir. Lo de criterio se queda en CLAUDE.md.

Configuración del cliente

Apunta la config MCP de tu agente al comando:

{
  "mcpServers": {
    "becwright": {
      "command": "becwright",
      "args": ["mcp"]
    }
  }
}

El servidor MCP viene solo con el paquete de Python (no está en el binario de npm). Para uso de CLI/hook sin Python, sigue usando la instalación de npm.

¿Cuándo usar MCP y cuándo check --json?

Ambos devuelven el mismo resumen, así que la elección depende del cliente, no de los datos:

• Usa check --json cuando el agente (o el script) puede correr comandos de shell. No necesita ninguna dependencia extra, funciona desde el binario autónomo de npm sin Python, y encaja en jobs de CI y scripts sueltos.
• Usa el servidor MCP cuando el cliente es MCP-nativo — Cursor o Windsurf, por ejemplo — y quieres que becwright aparezca como herramientas estructuradas y descubribles, en vez de un comando que el agente tiene que saber teclear. Requiere el paquete de Python con el extra mcp.
• Claude Code puede usar cualquiera de los dos, pero el plugin dedicado es el camino más cómodo — envuelve la CLI en un skill y un comando /becwright.

Para la configuración por agente, mira las guías de integración de Claude Code y Cursor.