gavel-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gavel-mcp Cold-run `npm test` as the acceptance command and report the verdict."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gavel-mcp
The gavel acceptance oracle as an MCP server: one tool that turns an
agent's "done" into a receipt. gavel_acceptance cold-runs a command
and reports the exit code. Exit code 0 is the only passing verdict.
Setup
1. Build
Requires Node ≥ 20 and git.
cd gavel-mcp
npm install
npm run build # → dist/index.jsdist/ is gitignored — every fresh clone needs this step before the
server can start.
2. Wire it into ZCode
Two scopes; both auto-connect at session start.
Workspace scope — versioned with the repo, shared with the team.
Create <repo>/.zcode/config.json:
{
"mcp": {
"servers": {
"gavel": {
"command": "node",
"args": ["/ABS/PATH/TO/gavel-mcp/dist/index.js"]
}
}
}
}User scope — applies to every workspace. Put the same
mcp.servers object in ~/.zcode/cli/config.json, and pair it with
the acceptance rule (section 5) in ~/.zcode/AGENTS.md so every
session knows when to call the tool, not just how.
A user-scope install pins every workspace to this machine's build:
After changing
src/, runnpm run build— other sessions keep loading the olddist/until you do.Moving or deleting the repo directory breaks every session at once.
Works from a git remote today — no registry needed. The prepare
script builds dist/ on install, so npx handles the rest:
{
"command": "npx",
"args": ["-y", "github:newlix/gavel-mcp#v0.5.0"]
}Pin a tag (#v0.5.0) to make the npx cache stable; without one you
track the default branch and cache refresh is at npx's discretion.
First start on a machine pays a one-time clone + install + build.
Once published to npm, ["-y", "gavel-mcp"] is equivalent and skips
the git requirement. Any other MCP host works too; only the config
shape differs.
3. Restart the session
MCP servers connect at session start. An already-running session will not pick the server up.
4. Verify
ZCode: Settings → MCP shows
gavelconnected.Or simply ask the agent to call
gavel_acceptancewithcmd: "test -d ."— expectverdict=pass exit=0.
5. The rule (AGENTS.md)
The tool is the structure; the rule tells the agent when to use it.
Drop this into <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.For user-scope installs, the same block goes in ~/.zcode/AGENTS.md
instead — user instructions load first, so a repo's own AGENTS.md can
still narrow the rule per project.
Related MCP server: shipcheck
The contract
The oracle never trusts a paraphrased result — it runs the command itself, so a red acceptance cannot be narrated green. Two structural layers, cheapest first:
Lint (
src/lint.ts): a command that cannot fail (true,exit 0, bare echo/printf,x && truewith no real check in it) is refused before execution —passed: false,refused: <reason>, no receipt minted. The Go linter's syntax and destructive-pattern checks are deliberately dropped: syntax fails identically when executed, and policing dangerous commands is the host permission layer's job, not the verdict layer's.Cold run (
src/runner.ts): the command runs via the platform shell from the project root; exit code 0 is the only pass. Signal deaths report 128+signal, spawn failure -1, command-not-found 127.
Receipt semantics: refused = never executed. Report it verbatim.
Tools
gavel_acceptance(cmd, cwd?, timeout_sec?)
→ { passed, exit_code, duration_ms, refused, output }
output: merged stdout+stderr, raw; head+tail with a marker when longer than ~20 KB.A timeout kills the whole process tree and fails the run.
Troubleshooting
Server not connected (Settings → MCP shows an error): the dist path is wrong or
npm run buildwas skipped. The path must be absolute and point atdist/index.js.exit_code: 127: the acceptance command itself was not found.
Dev
npm install
npm test # node:test via tsx (24 tests)
npm run build # tsc → dist/Layout: src/index.ts is the thin stdio bootstrap; the MCP surface
(buildServer) lives in src/server.ts so tests can drive it
in-process over InMemoryTransport plus one cold stdio smoke via
tsx. The manual smoke below is the same exchange the stdio test runs.
Manual smoke (MCP stdio is newline-delimited 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.jsAvailable Tools
1 toolgavel_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).
Inputs: cmd (required), cwd, timeout_sec.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of an agent confusing it with another. Its purpose is clearly distinct by default.
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.
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.
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
Related MCP Connectors
Proof of delivery for agent work: verify countersigned receipts and deliverable hashes. Free.
Agent completion verification with defects, corrections, and evidence receipts.
Hand off AI work with a signed Verification Receipt — an independent verifier proves it runs.
Verification for AI coding agents: runs the tests and checks a change affects, with a receipt.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables spec-driven development acceptance gate with structured receipts, audit logs, and reviewer-ready evidence.-
- FlicenseNot gradedqualityDmaintenanceEnables coding agents to submit a public preview URL and acceptance stories for independent QA, returning pass/fail evidence packs with screenshots and supporting human notes on failures.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to verify claims against evidence through MCP tools, returning approved, rejected, or needs_review verdicts with replayable receipts.MIT
- AlicenseNot gradedqualityBmaintenanceEnables deterministic verification of AI agent decisions and actions, providing PASS/FAIL/ABSTAIN verdicts with replayable proofs and an optional signed receipt ledger.Apache 2.0