gavel-mcp

Das gavel-Akzeptanz-Orakel als MCP-Server: ein Werkzeug, das das „done“ eines Agenten in eine Quittung verwandelt. gavel_acceptance führt einen Befehl kalt aus und meldet den Exit-Code. Nur Exit-Code 0 zählt als bestanden.

Einrichtung

1. Erstellen

Erfordert Node ≥ 20 und git.

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

dist/ ist gitignoriert – jeder frische Klon benötigt diesen Schritt, bevor der Server starten kann.

2. In ZCode einbinden

Zwei Ebenen; beide verbinden sich automatisch beim Sitzungsstart.

Workspace-Ebene – versioniert mit dem Repo, mit dem Team geteilt. Erstelle <repo>/.zcode/config.json:

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

Benutzer-Ebene – gilt für jeden Workspace. Lege dasselbe mcp.servers-Objekt in ~/.zcode/cli/config.json ab und kombiniere es mit der Akzeptanzregel (Abschnitt 5) in ~/.zcode/AGENTS.md, damit jede Sitzung weiß, wann sie das Werkzeug aufrufen soll – nicht nur wie.

Eine Installation auf Benutzer-Ebene bindet jeden Workspace an den Build dieser Maschine:

• Nach Änderungen an src/ führe npm run build aus – andere Sitzungen laden weiterhin das alte dist/, bis du das tust.

• Das Verschieben oder Löschen des Repo-Verzeichnisses bricht jede Sitzung auf einmal.

Funktioniert heute über ein Git-Remote – keine Registry nötig. Das prepare-Skript baut dist/ bei der Installation, sodass npx den Rest erledigt:

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

Pinne einen Tag (#v0.5.0), um den npx-Cache stabil zu machen; ohne einen solchen folgst du dem Standard-Branch, und die Cache-Aktualisierung liegt im Ermessen von npx. Der erste Start auf einer Maschine kostet einen einmaligen Clone + Install + Build. Sobald es auf npm veröffentlicht ist, ist ["-y", "gavel-mcp"] gleichwertig und überspringt die Git-Anforderung. Jeder andere MCP-Host funktioniert ebenfalls; nur die Form der Konfiguration unterscheidet sich.

3. Sitzung neu starten

MCP-Server verbinden sich beim Sitzungsstart. Eine bereits laufende Sitzung nimmt den Server nicht mehr auf.

4. Überprüfen

• ZCode: Einstellungen → MCP zeigt gavel verbunden.

• Oder bitte den Agenten einfach, gavel_acceptance mit cmd: "test -d ." aufzurufen – erwarte verdict=pass exit=0.

5. Die Regel (AGENTS.md)

Das Werkzeug ist die Struktur; die Regel sagt dem Agenten, wann er es verwenden soll. Lege dies in <repo>/AGENTS.md ab:

## 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.

Bei Installationen auf Benutzer-Ebene kommt derselbe Block stattdessen in ~/.zcode/AGENTS.md – Benutzeranweisungen werden zuerst geladen, sodass ein repo-eigenes AGENTS.md die Regel weiterhin pro Projekt einschränken kann.

Related MCP server: Spec Kit Acceptance Gate MCP

Der Vertrag

Das Orakel vertraut nie einem paraphrasierten Ergebnis – es führt den Befehl selbst aus, sodass eine rote Akzeptanz nicht als grün erzählt werden kann. Zwei strukturelle Ebenen, zuerst die kostengünstigste:

1. Lint (src/lint.ts): Ein Befehl, der nicht fehlschlagen kann (true, exit 0, bloßes echo/printf, x && true ohne echte Prüfung), wird vor der Ausführung abgelehnt – passed: false, refused: <reason>, keine Quittung wird ausgestellt. Die Syntax- und Destruktivmuster-Prüfungen des Go-Linters wurden bewusst entfernt: Syntax schlägt bei der Ausführung identisch fehl, und gefährliche Befehle zu überwachen ist Aufgabe der Host-Berechtigungsebene, nicht der Urteilsebene.

2. Kaltlauf (src/runner.ts): Der Befehl läuft über die Plattform-Shell aus dem Projektstamm; Exit-Code 0 ist der einzige Erfolg. Signaltode werden als 128+Signal gemeldet, Spawn-Fehler als -1, Befehl-nicht-gefunden als 127.

Quittungs-Semantik: refused = nie ausgeführt. Melde es unverändert.

Werkzeuge

gavel_acceptance(cmd, cwd?, timeout_sec?)

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

• output: zusammengeführte stdout+stderr, roh; Anfang und Ende mit einem Marker, wenn länger als ~20 KB.

• Ein Timeout beendet den gesamten Prozessbaum und lässt den Lauf fehlschlagen.

Fehlerbehebung

• Server nicht verbunden (Einstellungen → MCP zeigt einen Fehler): Der dist-Pfad ist falsch oder npm run build wurde übersprungen. Der Pfad muss absolut sein und auf dist/index.js zeigen.

• exit_code: 127: Der Akzeptanzbefehl selbst wurde nicht gefunden.

Entwicklung

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

Aufbau: src/index.ts ist der schlanke Stdio-Bootstrap; die MCP-Oberfläche (buildServer) lebt in src/server.ts, sodass Tests sie prozessintern über InMemoryTransport steuern können; dazu kommt ein Kaltlauf-Stdio-Smoke-Test via tsx. Der manuelle Smoke-Test unten ist derselbe Austausch, den der Stdio-Test ausführt.

Manueller Smoke-Test (MCP-stdio ist zeilengetrenntes JSON):

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