Skip to main content
Glama

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: shipcheck

契约

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

  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

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

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

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers