{"id":"c7071ed0-56ee-4050-837d-8fca1c4a96a7","slug":"gov-mcp","kind":"mcp","name":"gov-mcp","summary":"Governed execution layer for AI agents — MCP server with Y*gov runtime enforcement","owner":"liuhaotian2024-prog","repoUrl":"https://github.com/liuhaotian2024-prog/gov-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-05T12:57:44.000Z","addedAt":"2026-10-21T08:40:09.261Z","logoUrl":"https://avatars.githubusercontent.com/u/249964321?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra"],"tags":["ai-agent","claude-code","governance","security"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T18:32:07.270Z","sample":false,"url":"https://conduits.dev/tools/gov-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"gov-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# gov-mcp\n\n**Governed execution for any AI agent framework. Install in 30 seconds. Works with Claude Code, OpenClaw, and any MCP-compatible client.**\n\n```bash\npip install gov-mcp\ngov-mcp install\n```\n\nAn MCP server that enforces runtime governance on AI agent actions — file access, command execution, delegation chains, and permission escalation. Built on the [Y*gov](https://github.com/liuhaotian2024-prog/Y-star-gov) governance kernel.\n\n## Why\n\nAI agents can read files, run commands, and call APIs. Without governance, a single prompt injection or misaligned sub-agent can `rm -rf /`, leak `.env` secrets, or escalate privileges.\n\ngov-mcp sits between the agent and the system. Every action is checked against a governance contract before execution. Deterministic commands are auto-executed inline — no second tool call needed.\n\n## Performance (EXP-008)\n\n| Metric | Without gov-mcp | With gov-mcp | Delta |\n|---|---|---|---|\n| Output tokens | 6,107 | 3,352 | **-45.1%** |\n| Wall time | 171.1s | 65.8s | **-61.5%** |\n| Throughput | — | 39,000+ checks/s | — |\n| Concurrent agents | — | 50 agents, zero deadlock | — |\n| False positives | 0 | 0 | **0** |\n\n**Security (SIM-001 tested):** 50 concurrent agents, 1,000 checks, zero data leaks across isolated tenants.\n\n**Compliance:** FINRA audit trail (3/4 requirements met), EU AI Act Article 14 compatible (3/5 met out of box, remaining 2 partial with clear upgrade path).\n\n### Limitations (Honest Assessment)\n\n- **Per-event auto-hash:** Implemented in v0.1.0 via governance envelope chain\n- **Confidence score:** Included in every governance response (1.0 deterministic, 0.95 auto-routed)\n- **Multi-currency amount parsing:** Supported ($, ¥, €, £, USD/EUR/CNY prefix, comma separators)\n- **Per-client encryption keys:** Not yet available (roadmap for legal vertical)\n- **COSO/ISO report templates:** Not yet available (roadmap for enterprise compliance)\n- **Non-MCP ERP integration:** Requires custom adapter (no native SAP/Oracle bridge)\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install gov-mcp\n```\n\n### 2. Write your governance contract\n\nCreate `AGENTS.md`:\n\n```markdown\n## Agent: my-agent\n## Prohibited: rm -rf, sudo, .env files, /etc access\n## Permitted: file read/write, shell commands\n```\n\n### 3. One-command install\n\n```bash\ngov-mcp install\n```\n\nThis will:\n1. Detect your environment (Claude Code, Cursor, Windsurf, OpenClaw)\n2. Start the GOV MCP server (background, auto port selection)\n3. Auto-configure detected clients\n4. Verify the connection\n5. Print a summary with next steps\n\n### 4. Management commands\n\n```bash\ngov-mcp status     # Check if server is running\ngov-mcp restart    # Restart with fresh config\ngov-mcp uninstall  # Stop server, remove all configs\n```\n\n### 5. Manual setup (alternative)\n\nIf you prefer manual configuration:\n\n```bash\n# Start server directly\npython -m gov_mcp --agents-md ./AGENTS.md --transport sse --port 7922\n```\n\nConnect from any MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"gov-mcp\": {\n      \"url\": \"http://127.0.0.1:7922/sse\",\n      \"transport\": \"sse\"\n    }\n  }\n}\n```\n\n## Tools (38)\n\n### Core Enforcement\n| Tool | Description |\n|---|---|\n| `gov_check` | Check action + auto-execute deterministic commands. Single entry point. |\n| `gov_enforce` | Full pipeline: check + obligation scan + delegation verify. |\n| `gov_exec` | **[DEPRECATED]** Use `gov_check` instead. Redirects with migration guide. |\n\n### Delegation & Escalation\n| Tool | Description |\n|---|---|\n| `gov_delegate` | Register parent-child delegation with monotonicity validation. |\n| `gov_escalate` | Request permission expansion from principal. CIEU audit trail. |\n| `gov_chain_reset` | Clear stale delegation links (selective or full reset). |\n\n### Contract Management\n| Tool | Description |\n|---|---|\n| `gov_contract_load` | Translate AGENTS.md into draft contract. |\n| `gov_contract_validate` | Validate draft contract coverage and health. |\n| `gov_contract_activate` | Activate validated contract for enforcement. |\n\n### Audit & Observability\n| Tool | Description |\n|---|---|\n| `gov_report` | CIEU summary: decisions, deny rate, top violations. |\n| `gov_verify` | SHA-256 Merkle chain integrity verification. |\n| `gov_obligations` | Query obligation status from OmissionEngine. |\n| `gov_doctor` | Full 14-layer health check (contract, CIEU, obligations, heartbeat, hooks). |\n| `gov_benchmark` | Token savings benchmark: Mode A vs Mode B vs Mode C. |\n| `gov_seal` | Seal CIEU session with Merkle root for tamper-evident preservation. |\n| `gov_audit` | Causal audit report with violation replay for compliance evidence. |\n| `gov_trend` | 7-day CIEU event trend analysis with deny rate direction. |\n\n### Governance Analysis\n| Tool | Description |\n|---|---|\n| `gov_baseline` | Snapshot current governance state for later comparison. |\n| `gov_delta` | Compare current state against saved baseline. |\n| `gov_coverage` | Detect agent governance blind spots. |\n| `gov_quality` | Contract quality scoring (8 dimensions). |\n| `gov_simulate` | A/B simulation: intercept rate, false positive rate, risk reduction. |\n| `gov_impact` | Predict contract change effects via CIEU replay. |\n| `gov_check_impact` | Convenience wrapper for gov_impact with explicit params. |\n| `gov_pretrain` | Learn contract improvements from historical CIEU data. |\n\n### User Experience\n| Tool | Description |\n|---|---|\n| `gov_demo` | Zero-config 5-scenario governance demo. |\n| `gov_init` | Generate AGENTS.md template (python/node/go/generic). |\n| `gov_version` | Version info (gov-mcp + ystar-gov + python). |\n| `gov_policy_builder` | Contract data for UI rendering. |\n| `gov_reset_breaker` | Reset circuit breaker after manual intervention. |\n\n### Domain & Data\n| Tool | Description |\n|---|---|\n| `gov_archive` | Hot/cold CIEU data tiering. |\n| `gov_domain_list` | List registered governance domain packs. |\n| `gov_domain_describe` | Domain pack details and vocabulary. |\n| `gov_domain_init` | Generate custom domain pack template. |\n\n## How It Works\n\n```\nAgent proposes action\n    |\n    v\ngov_check(agent_id, tool_name, params)\n    |\n    +-- Is agent delegated? --> Use delegated contract\n    |   (otherwise)         --> Use global contract\n    |\n    +-- Contract check: ALLOW or DENY\n    |\n    +-- If ALLOW + deterministic Bash command:\n    |   Execute inline, return stdout in response\n    |   { \"decision\": \"ALLOW\", \"auto_executed\": true, \"stdout\": \"...\" }\n    |\n    +-- If ALLOW + non-deterministic:\n    |   Return ALLOW only (agent handles execution)\n    |\n    +-- If DENY:\n        Return DENY with violation details\n```\n\n## Auto-Execution\n\nDeterministic commands (`ls`, `git status`, `cat`, `pwd`, etc.) are classified\nby the structural router and **executed inline** within `gov_check`. The agent\nreceives stdout/stderr in the same response — no second tool call needed.\n\nThis saves **22% tokens** and eliminates one LLM round-trip per safe command.\n66.7% of typical Bash commands are auto-executed (based on stress testing).\n\n## Governance Extension Layer\n\nEvery `gov_check` response includes a `governance` field — a structured\naudit envelope that rides on top of the MCP protocol:\n\n```json\n{\n  \"decision\": \"ALLOW\",\n  \"auto_executed\": true,\n  \"stdout\": \"...\",\n  \"governance\": {\n    \"cieu_seq\": 17753,\n    \"contract_hash\": \"sha256:b6e47016...\",\n    \"contract_version\": \"1.0\",\n    \"latency_ms\": 1.9,\n    \"host\": \"claude_code\"\n  }\n}\n```\n\n| Field | Description |\n|---|---|\n| `cieu_seq` | Monotonic sequence number — total governance decisions made |\n| `contract_hash` | SHA-256 of the active governance contract |\n| `contract_version` | Contract name/version string |\n| `latency_ms` | Governance check latency (sub-2ms typical) |\n| `host` | Detected client ecosystem |\n\nThis is backward compatible — callers that don't inspect `governance` are\nunaffected. The field enables audit trails, compliance reporting, and\ncontract versioning across multi-agent deployments.\n\n## A2A Integration (Coming Soon)\n\nY*gov is designed as the governance layer for A2A (Agent-to-Agent) ecosystems.\nEvery agent-to-agent communication can be audited, controlled, and proven\ncompliant with CIEU five-tuple records.\n\n**Roadmap:**\n- **Phase 1 (Current):** GOV MCP — governance for MCP tool calls (33 tools, 100% coverage)\n- **Phase 2 (2026 Q3):** GOV A2A — governance layer for the A2A protocol\n- **Phase 3 (2026 Q4):** Gov Pipeline — end-to-end multi-agent workflow governance\n\n## License\n\nMIT\n"}