flowchart LR
    A[AI agent / LLM] --> B[MCP client]
    B -- stdio / JSON-RPC --> C[govmcp MCP server]
    C --> D{Policy engine<br/>rate limit, schema,<br/>lockdown, ranges}
    D -- read tools --> E[(Simulated<br/>environment)]
    D -- write, auto-approved<br/>non-prod only --> F[Executor]
    D -- write, needs approval --> G[Approval queue]
    H[Human approver<br/>govmcp approvals CLI] -- approve / reject --> G
    G -- re-validate, execute once --> F
    F --> E
    C -.every call and decision.-> I[(Hash-chained<br/>audit log)]
    H -.-> I

git clone https://github.com/sarathalapad/governed-mcp-server.git
cd governed-mcp-server
python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt

python -m pytest                     # run the test suite
python examples/demo_client.py       # scripted agent + human approver, over real stdio

python -m govmcp serve --caller my-agent     # MCP over stdio (normally started by your MCP client)
python -m govmcp approvals list              # see pending requests
python -m govmcp approvals approve apr-1234abcd --user bob
python -m govmcp approvals reject  apr-1234abcd --user bob --reason "restart first"
python -m govmcp verify-audit                # check the hash chain

### Tools advertised by the server
[
  "list_services",
  "get_service_health",
  "search_runbooks",
  "get_recent_incidents",
  "get_approval_status",
  "restart_service  (write)",
  "scale_service  (write)",
  "rollback_deployment  (write)"
]

### Agent: get_service_health(payments-api, prod)
{
  "status": "degraded",
  "version": "2.4.0",
  "error_rate": 6.8,
  "p95_latency_ms": 910
}

### Agent: search_runbooks('rollback error rate')
[
  {"runbook": "payments-api-high-error-rate.md", "title": "payments-api: high error rate"}
]

### Agent: rollback_deployment(..., dry_run=true)
{
  "ok": true,
  "status": "dry_run",
  "would_change": {"target": "payments-api@prod", "before": {"version": "2.4.0"}, "after": {"version": "2.3.1"}},
  "requires_approval": true,
  "note": "no changes were made"
}

### Agent: rollback_deployment(payments-api, prod)
{
  "ok": true,
  "status": "pending_approval",
  "approval_id": "apr-998482d0",
  "risk": "high",
  "would_change": {"target": "payments-api@prod", "before": {"version": "2.4.0"}, "after": {"version": "2.3.1"}},
  "expires_in_seconds": 900,
  "note": "a different human must approve this before it runs"
}

### Agent: scale_service(replicas=50) is outside policy
{
  "ok": false,
  "error": {"code": "POLICY_DENIED", "message": "replicas must be between 1 and 10", "hint": "larger changes need a capacity review"}
}

### Human: review queue
$ python -m govmcp approvals list
apr-998482d0  rollback_deployment  payments-api@prod        risk=high   by=demo-agent   expires in 899s
    change: {"version": "2.4.0"} -> {"version": "2.3.1"}

### Agent identity tries to approve its own request
$ python -m govmcp approvals approve apr-998482d0 --user demo-agent
{
  "ok": false,
  "error": {"code": "POLICY_DENIED", "message": "maker-checker: the requester cannot approve their own action"}
}

### Human (bob) approves
$ python -m govmcp approvals approve apr-998482d0 --user bob
{
  "ok": true,
  "status": "executed",
  "approval_id": "apr-998482d0",
  "change": {"target": "payments-api@prod", "before": {"version": "2.4.0"}, "after": {"version": "2.3.1"}},
  "result": {"service": "payments-api", "env": "prod", "status": "healthy", "version": "2.3.1", "replicas": 4, "restarts": 0}
}

### Replay attempt
$ python -m govmcp approvals approve apr-998482d0 --user bob
{
  "ok": false,
  "error": {"code": "POLICY_DENIED", "message": "approval apr-998482d0 is already executed; approvals cannot be reused"}
}

### Agent: get_approval_status
{
  "ok": true,
  "result": {"id": "apr-998482d0", "tool": "rollback_deployment", "status": "executed", "requester": "demo-agent", "decided_by": "bob", "result": {"service": "payments-api", "env": "prod", "status": "healthy", "version": "2.3.1", "replicas": 4, "restarts": 0}}
}

### Agent: health after rollback
{
  "status": "healthy",
  "version": "2.3.1",
  "error_rate": 0.2,
  "p95_latency_ms": 150
}

### Auditor: verify the hash chain
$ python -m govmcp verify-audit
audit log OK: 10 records, chain intact

### Auditor: verify again after someone edits the log
$ python -m govmcp verify-audit
audit log TAMPERED: line 7: record hash mismatch (edited?) (6 records verified before the break)

{
  "mcpServers": {
    "governed-ops": {
      "command": "/path/to/governed-mcp-server/.venv/bin/python",
      "args": ["-m", "govmcp", "serve", "--caller", "desktop-agent"],
      "env": {
        "PYTHONPATH": "/path/to/governed-mcp-server",
        "GOVMCP_AUDIT_KEY": "set-a-long-random-secret"
      }
    }
  }
}

governed-mcp-server/
├── govmcp/
│   ├── __main__.py        # python -m govmcp
│   ├── cli.py             # serve | approvals list/approve/reject | verify-audit
│   ├── server.py          # MCP tool definitions (thin wrappers, MCP Python SDK)
│   ├── gateway.py         # the single enforcement point: policy, approvals, execution, audit
│   ├── policy.py          # policy model, strict loader, rate limiter
│   ├── schema.py          # tool argument schemas and validation
│   ├── approvals.py       # persistent maker-checker queue
│   ├── audit.py           # hash-chained / HMAC audit log and verifier
│   ├── environment.py     # simulated services, plan/apply for write actions
│   └── errors.py          # structured, agent-readable failures
├── data/                  # fictional services, incidents and runbooks (seed data)
├── examples/demo_client.py
├── tests/                 # policy, approvals, audit, MCP end-to-end (in-memory + stdio)
├── policy.json
├── requirements.txt       # runtime: mcp
└── requirements-dev.txt   # + pytest