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에 연결

두 가지 범위가 있으며, 둘 다 세션 시작 시 자동으로 연결됩니다.

워크스페이스 범위 — 저장소와 함께 버전 관리되며 팀과 공유됩니다. <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"]
}

npx 캐시를 안정적으로 만들려면 태그(#v0.5.0)를 고정하세요. 태그가 없으면 기본 브랜치를 따라가며 캐시 갱신은 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 린터의 구문 및 파괴적 패턴 검사는 의도적으로 제외되었습니다. 구문은 실행 시 동일하게 실패하며, 위험한 명령어를 단속하는 것은 호스트 권한 계층의 역할이지 판정 계층의 역할이 아니기 때문입니다.

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가 병합된 원본입니다. 약 20KB보다 길면 머리+꼬리 부분이 마커와 함께 표시됩니다.

• 시간 초과는 전체 프로세스 트리를 종료하고 실행을 실패시킵니다.

문제 해결

• 서버가 연결되지 않음 (설정 → 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