gavel-mcp

MCP サーバーとしての gavel 受け入れ判定オラクル: エージェントの「完了」をレシートに変える単一のツールです。gavel_acceptance はコマンドをコールドランし、終了コードを報告します。終了コード0のみが合格判定です。

セットアップ

1. ビルド

Node ≥ 20 と git が必要です。

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

dist/ は gitignore されています — 新しくクローンするたびに、サーバーを起動する前にこの手順が必要です。

2. ZCode に組み込む

2つのスコープがあります。どちらもセッション開始時に自動接続されます。

ワークスペーススコープ — リポジトリとともにバージョン管理され、チームで共有されます。<repo>/.zcode/config.json を作成します:

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

ユーザースコープ — すべてのワークスペースに適用されます。同じ mcp.servers オブジェクトを ~/.zcode/cli/config.json に置き、~/.zcode/AGENTS.md 内の受け入れルール(セクション5)と組み合わせます。そうすることで、すべてのセッションがツールの呼び出し方だけでなく、いつ呼び出すべきかも把握できます。

ユーザースコープのインストールは、すべてのワークスペースをこのマシンのビルドに固定します:

• src/ を変更したら、npm run build を実行してください — 実行するまで、他のセッションは以前の dist/ を読み込み続けます。

• リポジトリディレクトリを移動または削除すると、すべてのセッションが一度に壊れます。

現在は git リモートから動作します — レジストリは不要です。prepare スクリプトがインストール時に dist/ をビルドするので、残りは npx が処理します:

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

タグ(#v0.5.0)を固定すると npx キャッシュが安定します。固定しない場合、デフォルトブランチを追跡することになり、キャッシュの更新は npx の裁量に委ねられます。マシンでの初回起動時には、一度だけ clone + install + build のコストがかかります。npm に公開されたら、["-y", "gavel-mcp"] は同等の動作になり、git の要件をスキップします。他の MCP ホストでも動作します。設定の形状が異なるだけです。

3. セッションを再起動する

MCP サーバーはセッション開始時に接続されます。すでに実行中のセッションはサーバーを認識しません。

4. 確認

• ZCode: Settings → MCP に gavel が接続済みと表示されます。

• または、エージェントに gavel_acceptance を cmd: "test -d ." で呼び出すよう依頼してください — verdict=pass exit=0 が返るはずです。

5. ルール(AGENTS.md)

ツールが構造であり、ルールはエージェントにいつ使うかを伝えます。これを <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.

ユーザースコープのインストールでは、同じブロックは代わりに ~/.zcode/AGENTS.md に置きます — ユーザー指示が先に読み込まれるため、リポジトリ自身の AGENTS.md でプロジェクトごとにルールを絞り込むことができます。

Related MCP server: TruthGate

契約

オラクルは言い換えられた結果を決して信頼しません — コマンド自体を実行するため、不合格の判定が合格として説明されることはありません。構造上の2つのレイヤーを、低コストな順に示します:

1. Lint (src/lint.ts): 失敗し得ないコマンド(true、 exit 0、ベアの echo/printf、実際のチェックが含まれていない x && true) は実行前に拒否されます — passed: false、refused: <reason>、レシートは発行されません。 Go リンターの構文チェックと破壊的パターンチェックは意図的に省略されています。 構文は実行時にも同様に失敗しますし、危険なコマンドの取り締まりは、判定レイヤーではなく ホストの権限レイヤーの仕事だからです。

2. Cold run (src/runner.ts): コマンドはプロジェクトルートからプラットフォームのシェル経由で 実行されます。終了コード0のみが合格です。シグナルによる終了は 128+シグナル番号、 spawn 失敗は -1、コマンド未検出は 127 を報告します。

レシートの意味: refused は未実行を意味します。そのまま報告してください。

ツール

gavel_acceptance(cmd, cwd?, timeout_sec?)

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

• output: stdout と stderr を結合した生の出力。約20 KB を超える場合は、マーカー付きで先頭と末尾を返します。

• タイムアウトするとプロセスツリー全体が強制終了され、実行は失敗となります。

トラブルシューティング

• サーバーが接続されない(Settings → MCP にエラーが表示される): dist パスが間違っているか、npm run build がスキップされています。パスは絶対パスで、dist/index.js を指している必要があります。

• exit_code: 127: 受け入れコマンド自体が見つかりません。

開発

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

構成: src/index.ts は薄い stdio ブートストラップです。MCP サーフェス(buildServer)は src/server.ts にあり、テストは InMemoryTransport 経由でプロセス内から駆動でき、さらに tsx によるコールド stdio スモークテストが1つあります。以下の手動スモークテストは、stdio テストが実行するのと同じやり取りです。

手動スモークテスト(MCP stdio は改行区切りの 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