Skip to main content
Glama
Sign In
deenesjakoruzh
gavel-mcp

gavel-mcp

by newlix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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: Spec Kit Acceptance Gate MCP

契約

オラクルは言い換えられた結果を決して信頼しません — コマンド自体を実行するため、不合格の判定が合格として説明されることはありません。構造上の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

Available Tools

1 tool
gavel_acceptanceA

Run an acceptance command cold and report the mechanical verdict. The command must be one self-contained shell command; it runs from the project root via the platform shell. Exit code 0 is the only passing verdict — never paraphrase or pre-empt it. Signal deaths report 128+signal; a spawn failure reports -1; 127 means the command was not found. Output is raw merged stdout+stderr (head+tail when truncated).

NameRequiredDescriptionDefault
cmdYesSelf-contained acceptance command, e.g. `go test ./...` or `make check`. Must assert intent, not recapitulate the implementation.
cwdNoAbsolute working directory. Default: the server's cwd (hosts spawn it at the workspace root).
timeout_secNoKill the run after this many seconds (default 600).

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly. It discloses exit-code semantics (0 = pass, 128+signal = signal death, -1 = spawn failure, 127 = not found), raw merged stdout+stderr, truncation behavior, and the 'cold'/mechanical nature of the run. This goes well beyond a generic 'run a command' statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized and front-loaded: the core action appears first, followed by the necessary command constraint, verdict semantics, and output details. Every sentence earns its place; there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema and no annotations, the description fully covers what an agent needs to invoke the tool correctly: command format, working directory, exit-code interpretation, and output shape. It is complete for the tool's complexity and parameter set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and every parameter (cmd, cwd, timeout_sec) is already documented in the schema with type, constraints, and defaults. The tool description mainly reinforces that the command must be self-contained, which adds marginal value but does not improve on the schema's parameter-level explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Run an acceptance command cold and report the mechanical verdict.' It makes clear this is a command-execution tool focused on acceptance verification, and the absence of sibling tools means there is no risk of confusion with alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage constraints: the command must be a single self-contained shell command, runs from the project root, and the agent must not paraphrase or pre-empt the exit-code verdict. With no sibling tools listed, there is no alternative-routing guidance needed, but the when-and-how guidance is otherwise strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.5.0
    • First observedgavel_acceptance
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so there is no possibility of an agent confusing it with another. Its purpose is clearly distinct by default.

Naming Consistency4/5

With a single tool there are no conflicting conventions to penalize. The name gavel_acceptance is clear and follows snake_case, though it is noun-oriented rather than a verb_noun pattern.

Tool Count4/5

One tool is minimal, but the server appears purpose-built for a single acceptance action, so the count is slightly under the typical range yet reasonable for the stated scope.

Completeness5/5

The tool fully covers the server's apparent purpose: running an acceptance command and returning a mechanical verdict with well-specified exit-code and output handling. No obvious operations are missing for this narrow domain.

Maintenance

ActivityStale
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers