git clone https://github.com/azambd/guardrail-mcp && cd guardrail-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
guardrail-mcp demo

  agent → describe_permissions()                               [ALLOW]     15 tools allowed, 1 gated, 1 hidden
  agent → list_issues()                                        [ALLOW]     3 open issues
  agent → get_file(path="config/settings.py")                  [ALLOW]     1 credential redacted before reaching the model
  agent → get_file(path=".env")                                [DENY]      paths.deny_read
  agent → create_issue(repo="acme/billing")                    [DENY]      repos.allow
  agent → commit_file(branch="main", path="src/checkout.py")   [DENY]      branches.protected
  agent → create_branch(branch="agent/fix-double-submit")      [ALLOW]     branch created from main
  agent → commit_file(path=".github/workflows/deploy.yml")     [DENY]      paths.deny_write
  agent → commit_file(path="src/checkout.py")                  [ALLOW]     commit ed5afd8 on agent/fix-double-submit
  agent → comment_on_issue(number=1, body="...ghp_ZZZZ...")    [DENY]      content.block_secrets
  agent → open_pull_request(dry_run=true)                      [DRY RUN]   preview returned, nothing changed
  agent → open_pull_request(head="agent/fix-double-submit")    [ALLOW]     PR #4 opened as draft (policy)
  agent → open_pull_request(...)  # agent retries              [REPLAY]    original result returned, no duplicate PR
  agent → close_issue(number=1)                                [APPROVAL]  paused, request apr_c6214176 waits for a human
  human → guardrail-mcp approvals approve apr_c6214176         [APPROVED]  single use, logged with who approved
  agent → close_issue(number=1)  # same args                   [ALLOW]     issue #1 is closed
  agent → merge_pull_request(number=4)                         [HIDDEN]    not exposed by policy, the agent cannot see or call it
  agent → get_ci_status(ref="main")                            [ALLOW]     failure: unit-tests (run 9001)

  6 actions blocked before reaching GitHub, 5 real API writes performed.
  audit log: 22 records, hash chain intact

flowchart TD
    A["AI agent: Claude Code, Codex, your harness"] -->|MCP tool call| P{"Policy check: tool, repo, branch, path, size, secrets"}
    P -->|violation| D["Denied with rule id"]
    P -->|read| R["GitHub read"] --> X["Redact secrets in the result"]
    P -->|write| I{"Identical write already done?"}
    I -->|yes| C["Return the original result"]
    I -->|no| Y{"Dry run?"}
    Y -->|yes| V["Return a preview"]
    Y -->|no| B{"Write budget left?"}
    B -->|no| D
    B -->|yes| G{"Needs approval?"}
    G -->|not approved yet| Q["Pending approval id"]
    G -->|approved or not required| W["Write-ahead audit record"] --> H["GitHub write"]
    D --> L[("Hash-chained audit log")]
    X --> L
    C --> L
    V --> L
    Q --> L
    H --> L

src/guardrail_mcp/
  catalog.py      tool metadata: which args name a repo, branch, path or free text
  policy.py       strict YAML policy model (unknown keys and tool names are errors)
  guard.py        the decision pipeline above
  audit.py        append-only, hash-chained JSONL with verification and file locking
  state.py        SQLite store for approvals and idempotency
  scanning.py     secret detection and redaction
  github.py       REST client with retry rules that never duplicate a write
  tools.py        the 18 MCP tools
  server.py       wires it together; only enabled tools are registered
  cli.py          serve, check, doctor, approvals, audit, demo
  fake_github.py  in-memory GitHub for the demo and tests

cp policy.example.yaml policy.yaml   # then set repos.allow
guardrail-mcp check --policy policy.yaml

repos:
  allow: [your-org/your-repo]
tools:
  allow: [get_repo, list_issues, get_issue, get_file, get_ci_status,
          create_branch, commit_file, open_pull_request, comment_on_issue]
  require_approval: [close_issue]
branches:
  agent_prefix: "agent/"
  protected: ["main", "release/*"]
paths:
  deny_write: [".github/workflows/**", ".env", ".env.*", "**/*.pem"]
limits:
  max_writes_per_session: 25

export GITHUB_TOKEN=github_pat_...
guardrail-mcp doctor --policy policy.yaml

{
  "mcpServers": {
    "github-guarded": {
      "command": "/absolute/path/to/.venv/bin/guardrail-mcp",
      "args": ["serve", "--policy", "/absolute/path/to/policy.yaml", "--agent-id", "claude-code"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

[mcp_servers.github-guarded]
command = "/absolute/path/to/.venv/bin/guardrail-mcp"
args = ["serve", "--policy", "/absolute/path/to/policy.yaml", "--agent-id", "codex"]
env = { GITHUB_TOKEN = "github_pat_..." }

guardrail-mcp serve --policy policy.yaml --transport streamable-http --port 8000
# endpoint: http://127.0.0.1:8000/mcp

agent  close_issue(number=1)
       -> APPROVAL REQUIRED: request apr_c6214176 is pending. Ask the user to run
          `guardrail-mcp approvals approve apr_c6214176`, then call close_issue again
          with exactly the same arguments.

you    guardrail-mcp approvals list
you    guardrail-mcp approvals approve apr_c6214176

agent  close_issue(number=1)        # same arguments
       -> ok

{
  "seq": 11,
  "ts": "2026-11-02T00:21:18.014Z",
  "session": "s_1a0acd0e",
  "agent": "claude-code",
  "request_id": "11",
  "tool": "commit_file",
  "kind": "write",
  "repo": "acme/web-app",
  "args": {
    "branch": "agent/fix-double-submit",
    "path": "src/checkout.py",
    "content": { "bytes": 86, "sha256": "6d5f094c6ea5..." },
    "message": "Make order submission idempotent (#1)"
  },
  "decision": "allow",
  "phase": "intent",
  "prev": "6402e3ea9044...",
  "hash": "5a15f440a5f8..."
}

guardrail-mcp audit tail -n 50 --policy policy.yaml
guardrail-mcp audit verify --policy policy.yaml   # exits 1 if any record was edited, removed or reordered

pip install -e ".[dev]"
pytest