gavel-mcp

Оракул приёмки gavel как MCP-сервер: один инструмент, который превращает «готово» агента в квитанцию. gavel_acceptance холодно запускает команду и сообщает код возврата. Код возврата 0 — единственный проходной вердикт.

Настройка

1. Сборка

Требуются Node ≥ 20 и git.

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

dist/ игнорируется git — в каждой свежей копии репозитория этот шаг обязателен, прежде чем сервер сможет запуститься.

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 и добавьте к нему правило приёмки (раздел 5) в ~/.zcode/AGENTS.md, чтобы каждая сессия знала, когда вызывать инструмент, а не только как.

Установка в область пользователя привязывает все рабочие пространства к сборке этой машины:

• После изменения 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: 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

Контракт

Оракул никогда не доверяет перефразированному результату — он сам выполняет команду, поэтому красную приёмку нельзя описать как зелёную. Два структурных уровня, сначала самый дешёвый:

1. Линт (src/lint.ts): команда, которая не может завершиться ошибкой (true, exit 0, голые echo/printf, x && true без реальной проверки), отклоняется до выполнения — passed: false, refused: <reason>, квитанция не выпускается. Проверки синтаксиса и деструктивных паттернов из Go-линтера намеренно опущены: синтаксис при выполнении падает точно так же, а контроль опасных команд — задача уровня разрешений хоста, а не уровня вердикта.

2. Холодный запуск (src/runner.ts): команда выполняется через системную оболочку из корня проекта; код возврата 0 — единственный признак успеха. Завершения по сигналу сообщаются как 128+signal, сбой запуска — -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, плюс один холодный смоук-тест stdio через tsx. Ручной смоук-тест ниже — это тот же обмен, который выполняет 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