gavel-mcp

gavel 验收预言机作为一个 MCP 服务器：一个将代理的“完成”变成收据的工具。gavel_acceptance 冷运行一条命令并报告退出码。退出码 0 是唯一通过的判定。

设置

1. 构建

需要 Node ≥ 20 和 git。

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

dist/ 已被 gitignore——每次全新克隆都需要先执行此步骤，服务器才能启动。

2. 接入 ZCode

两种作用域；两者都会在会话启动时自动连接。

工作区作用域——随仓库进行版本控制，与团队共享。创建 <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 自行决定。在一台机器上的首次启动需要一次性付出克隆 + 安装 + 构建的成本。一旦发布到 npm，["-y", "gavel-mcp"] 是等效的，并且跳过了对 git 的要求。任何其他 MCP 主机也都可以；只是配置形式不同。

3. 重启会话

MCP 服务器在会话启动时连接。已经运行的会话不会加载该服务器。

4. 验证

• ZCode：设置 → MCP 显示 gavel 已连接。

• 或者直接让代理调用带 cmd: "test -d ." 的 gavel_acceptance——预期会得到 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

契约

预言机从不相信转述的结果——它会自己运行命令，所以红色的验收结果无法被口头说成绿色。两个结构层，按成本从低到高：

1. Lint（src/lint.ts）：一条不可能失败的命令（true、exit 0、裸 echo/printf、没有任何真实检查的 x && true）会在执行前被拒绝——passed: false、refused: <reason>，不会铸造收据。Go linter 的语法检查和破坏性模式检查被有意舍弃：语法错误在执行时同样会失败，而管制危险命令是宿主权限层的职责，而不是判定层的职责。

2. 冷运行（src/runner.ts）：命令通过平台 shell 从项目根目录运行；退出码 0 是唯一通过条件。信号终止报告为 128+signal，进程生成失败为 -1，命令未找到为 127。

收据语义：refused = 从未执行。请原样报告该值。

工具

gavel_acceptance(cmd, cwd?, timeout_sec?)

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

• output：合并的 stdout+stderr，原始输出；超过约 20 KB 时显示头部和尾部，并带有标记。

• 超时将会终止整个进程树并使运行失败。

故障排除

• 服务器未连接（设置 → 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 冒烟测试。下面的手动冒烟测试就是 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