gavel-mcp

El oráculo de aceptación de gavel como servidor MCP: una herramienta que convierte el "hecho" de un agente en un comprobante. gavel_acceptance ejecuta un comando en frío y notifica el código de salida. El código de salida 0 es el único veredicto que aprueba.

Configuración

1. Compilación

Requiere Node ≥ 20 y git.

cd gavel-mcp
npm install
npm run build        # → dist/index.js

dist/ está en gitignore: cada clon nuevo necesita este paso antes de que el servidor pueda arrancar.

2. Integración en ZCode

Dos ámbitos; ambos se conectan automáticamente al inicio de la sesión.

Ámbito de workspace — versionado con el repositorio, compartido con el equipo. Crea <repo>/.zcode/config.json:

{
  "mcp": {
    "servers": {
      "gavel": {
        "command": "node",
        "args": ["/ABS/PATH/TO/gavel-mcp/dist/index.js"]
      }
    }
  }
}

Ámbito de usuario — se aplica a todos los workspaces. Pon el mismo objeto mcp.servers en ~/.zcode/cli/config.json y combínalo con la regla de aceptación (sección 5) en ~/.zcode/AGENTS.md para que cada sesión sepa cuándo llamar a la herramienta, no solo cómo.

Una instalación de ámbito de usuario fija todos los workspaces a la compilación de esta máquina:

• Después de cambiar src/, ejecuta npm run build; las demás sesiones seguirán cargando el dist/ antiguo hasta que lo hagas.

• Mover o eliminar el directorio del repositorio rompe todas las sesiones a la vez.

Funciona desde un remoto de git hoy mismo: no se necesita registro. El script prepare compila dist/ al instalar, así que npx se encarga del resto:

{
  "command": "npx",
  "args": ["-y", "github:newlix/gavel-mcp#v0.5.0"]
}

Fija una etiqueta (#v0.5.0) para que la caché de npx sea estable; sin ella sigues la rama por defecto y la actualización de caché queda a discreción de npx. El primer arranque en una máquina supone un clonado + instalación + compilación únicos. Una vez publicado en npm, ["-y", "gavel-mcp"] es equivalente y omite el requisito de git. Cualquier otro host de MCP también funciona; solo difiere la forma de la configuración.

3. Reinicio de la sesión

Los servidores MCP se conectan al inicio de la sesión. Una sesión ya en ejecución no detectará el servidor.

4. Verificación

• ZCode: Configuración → MCP muestra gavel conectado.

• O simplemente pide al agente que llame a gavel_acceptance con cmd: "test -d ." — espera verdict=pass exit=0.

5. La regla (AGENTS.md)

La herramienta es la estructura; la regla le dice al agente cuándo usarla. Coloca esto en <repo>/AGENTS.md:

## Acceptance

- Done = `gavel_acceptance` returned exit 0. One self-contained
  command, cold from the repo root; report the verdict and the
  command itself — never a paraphrase of test results.
- The command asserts intent (what should happen), not the
  implementation.
- `refused` means it never ran. Report it verbatim.

Para instalaciones de ámbito de usuario, el mismo bloque va en ~/.zcode/AGENTS.md — las instrucciones de usuario se cargan primero, así que el AGENTS.md del propio repositorio aún puede acotar la regla por proyecto.

Related MCP server: TruthGate

El contrato

El oráculo nunca se fía de un resultado parafraseado — ejecuta el comando él mismo, así que una aceptación en rojo no puede narrarse en verde. Dos capas estructurales, primero la de menor coste:

1. Lint (src/lint.ts): un comando que no puede fallar (true, exit 0, echo/printf a secas, x && true sin ninguna comprobación real) se rechaza antes de ejecutarse — passed: false, refused: <reason>, no se emite ningún comprobante. Las comprobaciones de sintaxis y de patrones destructivos del linter de Go se omiten deliberadamente: la sintaxis falla de forma idéntica al ejecutarse, y vigilar comandos peligrosos es trabajo de la capa de permisos del host, no de la capa de veredicto.

2. Ejecución en frío (src/runner.ts): el comando se ejecuta mediante el shell de la plataforma desde la raíz del proyecto; el código de salida 0 es la única forma de aprobar. Las terminaciones por señal notifican 128+señal, fallo de spawn -1, comando no encontrado 127.

Semántica del comprobante: refused = nunca ejecutado. Repórtalo tal cual.

Herramientas

gavel_acceptance(cmd, cwd?, timeout_sec?)

→ { passed, exit_code, duration_ms, refused, output }

• output: stdout+stderr combinados, sin procesar; cabeza y cola con un marcador cuando supere ~20 KB.

• Un timeout mata todo el árbol de procesos y hace fallar la ejecución.

Solución de problemas

• Servidor no conectado (Configuración → MCP muestra un error): la ruta de dist es incorrecta o se omitió npm run build. La ruta debe ser absoluta y apuntar a dist/index.js.

• exit_code: 127: el propio comando de aceptación no se encontró.

Desarrollo

npm install
npm test       # node:test via tsx (24 tests)
npm run build  # tsc → dist/

Estructura: src/index.ts es el bootstrap ligero de stdio; la interfaz MCP (buildServer) se encuentra en src/server.ts para que las pruebas puedan manejarlo en proceso a través de InMemoryTransport, más una prueba de humo de stdio en frío con tsx. La prueba de humo manual de abajo es el mismo intercambio que ejecuta la prueba de stdio.

Prueba de humo manual (MCP stdio es JSON delimitado por saltos de línea):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"gavel_acceptance","arguments":{"cmd":"test -d ."}}}' \
  | node dist/index.js