MCP server

MCP server (commitbrief mcp)

commitbrief mcp runs a Model Context Protocol server over stdio so an AI agent or host can invoke CommitBrief as a tool — typically a self-review gate the agent runs before it submits code. It speaks JSON-RPC 2.0 over the MCP stdio transport, is implemented with the Go standard library only (no MCP SDK, no extra dependency), and is fully opt-in: enabling it changes nothing about the other commands.

Note

The server exposes the same review pipeline as commitbrief --json — diff acquisition, the three-layer filtering, the pre-send guard and secret scanner, the cost preflight, the response cache, the flaky-test pre-pass, and signal control all run exactly as they do for a terminal review. The MCP path reuses the review code rather than re-implementing it.

What it exposes

A single tool, review, that reviews the current repository's diff and returns the structured findings (JSON schema v1) plus a short text summary.

Tool: review

All arguments are optional. With no arguments it reviews the staged diff (commitbrief --staged).

Argument	Type	Default	Meaning
staged	boolean	true	review the staged diff
unstaged	boolean	false	review the working-tree diff instead (mutually exclusive with staged)
diff	string[]	—	git diff arguments for a range review, e.g. ["HEAD~3","HEAD"] or ["main...feature"]; forwarded verbatim to git
provider	string	configured	override the provider for this review
model	string	configured	override the model for this review
fail_on	string	—	critical | high | medium | low | info | any | none — report a gate failure when a finding meets/exceeds this severity. Findings are still returned.
min_severity	string	—	critical | high | medium | low | info | none — hide findings below this severity in the returned set (the gate still sees the full set)
no_flaky	boolean	false	skip the deterministic flaky-test detector

The tool result has two content blocks:

1. A text summary — finding counts by severity, the provider/model used, whether the response was cached, and a GATE FAILED: … note when fail_on tripped.
2. The JSON schema-v1 document — the same bytes commitbrief --json emits.

A genuine failure (no git repo, no changes to review, a provider error, or an aborted secret-scan guard) is returned as an MCP tool error (isError: true) carrying the message, so the agent can react. The fail_on gate is not a tool error — the findings are valid and returned; the gate is reported in the summary.

Wiring it into a host

Register commitbrief mcp as a stdio MCP server in your host's configuration.

Claude Desktop / generic MCP host

{
  "mcpServers": {
    "commitbrief": {
      "command": "commitbrief",
      "args": ["mcp"]
    }
  }
}

If commitbrief is not on the host's PATH, use an absolute path for command (e.g. /usr/local/bin/commitbrief). Provider credentials are resolved the same way as for any review — from ~/.commitbrief/config.yml, the repo config, or environment variables (see Configuration files and Environment variables). Run commitbrief setup once first so the server has a working provider.

The host launches the process, performs the initialize handshake, discovers the review tool via tools/list, and invokes it via tools/call. The process reads JSON-RPC requests on stdin and writes responses on stdout until the host closes the stream; human-readable diagnostics go to stderr and never pollute the JSON-RPC channel.

Protocol

• Transport: line-delimited JSON over stdio — one JSON-RPC 2.0 message per line. (The optional Content-Length header framing is not used; the newline form is the stdio default.)
• Protocol version: 2024-11-05.
• Methods: initialize, tools/list, tools/call, ping. Notifications (id-less requests, e.g. notifications/initialized) are accepted and not answered.

Worked example (raw JSON-RPC)

Requests the host sends (one per line), and the responses the server returns:

// → initialize
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}
// ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"commitbrief","version":"…"}}}

// → notifications/initialized   (no response)
{"jsonrpc":"2.0","method":"notifications/initialized"}

// → tools/list
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
// ← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"review","description":"…","inputSchema":{ "type":"object", … }}]}}

// → tools/call review (staged diff)
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"review","arguments":{"staged":true}}}
// ← {"jsonrpc":"2.0","id":3,"result":{"content":[
//      {"type":"text","text":"CommitBrief review: 1 finding(s) (1 info). Provider: anthropic/…."},
//      {"type":"text","text":"{\"schema\":1,\"content\":\"\",\"findings\":[…],\"summary\":{},\"meta\":{…}}"}
//    ]}}

Notes and limits

• One review at a time. The server is single-connection and processes requests sequentially — a review is a blocking operation and there is exactly one host on the other end of stdio.
• Guards still apply. Because the agent host is non-interactive, a triggered secret-scan or cost preflight aborts (rather than auto-approving) and the abort is surfaced as a tool error — a review that would prompt a human is never silently approved for an agent.
• Config is re-read per call, so editing ~/.commitbrief/config.yml between calls takes effect without restarting the server.

See also

• JSON schema v1 — the exact shape of the returned findings.
• Review (default command) — the pipeline the tool reuses.
• Configuration files · Environment variables — how the provider/credentials resolve.
• --fail-on and exit codes — the gate semantics fail_on mirrors.