SpectraMCP

One useful job, end to end: name a capability such as fs.write_report, get allow, approval_required, or deny, and leave a locally verifiable audit event. No policy daemon, account, or cloud relay is required.

# Quickstart — run the three decisions without cloning (requires uv)
uvx --from git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack governed-agent demo

Expected decisions:

signal.read_file        allow
fs.write_report         approval_required
shell.execute           deny

{
  "mcpServers": {
    "governed-agent-gate": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack",
        "governed-agent-mcp"
      ]
    }
  }
}

📖 Table of Contents

• What is Governed Agent MCP Stack?

• Key Features

• System Architecture

• Setup & Installation

• Connecting to AI Clients

• How to Use

• CLI Reference

• Comparison

• Scope & Limitations

• File Structure

• Troubleshooting

• Contributing

• License

Related MCP server: sionna-mcp

💡 What is Governed Agent MCP Stack?

Agent tools often jump from harmless reads to file writes, shell execution, or CAD mutations with scattered if statements—or no check at all. This project provides a small gate that can be called from Python, a shell pipeline, or an MCP client before the risky function executes.

Instead of starting with a policy platform, you get:

• A useful starter policy: read-only and in-memory work is allowed, writes require approval, and destructive or unknown capabilities are denied.

• One enforcement API: Gatekeeper.enforce() raises before the wrapped function body runs.

• Evidence you can inspect: every decision is appended to SQLite with a SHA-256 hash chained to the previous event.

The best fit is an MCP server author or agent-platform engineer who needs a reviewable local safety layer today and may graduate to a larger policy system later.

✨ Key Features

• 🔒 Fail closed: unmatched capabilities use default_action: deny.

• 🧩 Exact and glob rules: express fs.read_file or families such as fs.write_* in plain YAML.

• 🐍 Real enforcement: use a Python decorator or enforce() before a tool body; denied and approval-required calls raise distinct exceptions.

• 🔌 Real MCP server: check_action, recent_decisions, and verify_audit_chain run over local stdio with FastMCP.

• 🧾 Tamper-evident audit: changed or reordered SQLite rows fail chain verification. Context stays local and must be JSON serializable.

• 🤖 Automation-friendly CLI: JSON output and stable exit codes let CI, shell scripts, and tool hosts gate actions.

• 🧪 Useful examples, labeled honestly: offline DSP helpers and a best-effort process scanner remain as optional workloads, not product claims.

⚙️ System Architecture

The gate belongs immediately before the code that can cause a side effect.

flowchart LR
    Agent["Agent or MCP client"] --> Intent["Capability + JSON context"]
    Intent --> Gate["Policy gate"]
    Policy["YAML policy"] --> Gate
    Gate -->|"allow"| Tool["Wrapped tool function"]
    Gate -->|"approval_required"| Review["Your approval workflow"]
    Gate -->|"deny"| Stop["Stop"]
    Gate --> Audit[("Local SQLite hash chain")]

    classDef default fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef gate fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
    class Gate gate;

🚀 Setup & Installation

Option A: Run from GitHub with uv

uvx --from git+https://github.com/IamOumarIbrahim/governed-agent-mcp-stack governed-agent demo

uvx runs the command in an isolated environment. Use this path to evaluate the project without changing your current Python environment.

Option B: Clone for development

git clone https://github.com/IamOumarIbrahim/governed-agent-mcp-stack.git
cd governed-agent-mcp-stack
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[all,dev]"
governed-agent doctor

Windows users can run .\setup.ps1 to create .venv, install the development extras, run tests, and print the MCP client config. The script does not edit client settings.

🔍 Verification command:

governed-agent doctor
python -m pytest -q
python -m ruff check .

Expected test summary for this revision: 22 passed.

🔌 Connecting to AI Clients

The zero-edit config near the top uses the packaged starter policy. For a policy you own:

1. Create a local policy:

   governed-agent init --output ./my-policy.yaml

2. Print a config containing the current Python executable and absolute paths:

   governed-agent config --policy ./my-policy.yaml

3. Merge the printed mcpServers entry into your client's configuration and restart the client.

The server exposes:

FastMCP uses stdio by default for local servers, so the client owns the server process lifecycle and no HTTP port is opened.

🖥️ How to Use

Gate one action from a shell

governed-agent check fs.write_report \
  --context '{"path":"reports/result.json"}'

The JSON response includes the decision, matched rule, reason, policy source, and audit event hash.

Enforce before a Python function runs

from interlock import Gatekeeper

gate = Gatekeeper(
    policy_path="interlock.policy.yaml",
    audit_path=".interlock/audit.db",
)

@gate.protect(
    "fs.write_report",
    context_factory=lambda path, content: {"path": path, "bytes": len(content)},
)
def write_report(path: str, content: str) -> None:
    with open(path, "w", encoding="utf-8") as report:
        report.write(content)

With the starter policy, write_report() raises ApprovalRequired before opening the file. Unknown capabilities raise ActionDenied.

Write a policy

version: 1
default_action: deny

capabilities:
  "workspace.read_*":
    mode: allow
    reason: Read-only workspace tools are safe for this host.

  "workspace.write_*":
    mode: approval_required
    reason: A human must review workspace mutations.

  "shell.execute":
    mode: deny
    reason: This host never delegates arbitrary shell execution.

Exact rules win over globs. When multiple globs match, the most specific pattern wins.

📊 CLI Reference

Policy or input errors return 64.

⚖️ Comparison

This project is a stepping stone, not a claim that a small Python library replaces a mature organization-wide authorization system.

🔬 Scope & Limitations

• No transparent interception: an MCP client can ignore the gate. Use the Python wrapper or enforce the call order in the host you control.

• No built-in approval UI: approval_required must feed an approval flow outside this package.

• Tamper-evident, not tamper-proof: the hash chain detects changed or reordered rows, but an attacker with filesystem access can delete the whole database or truncate its tail. Anchor hashes externally for stronger proof.

• Local identity only: rules do not model users, organizations, OAuth scopes, or remote multi-tenant authorization.

• Context is stored: do not pass secrets in decision context.

• Optional examples are examples: spectramcp/ implements offline numeric helpers; agentpulse/ performs best-effort process-name scanning. Neither is a production hardware adapter or transcript telemetry platform.

📁 File Structure

governed-agent-mcp-stack/
├── interlock/
│   ├── gate.py                # Enforcement API and decorator
│   ├── policy.py              # Validated exact/glob policy engine
│   ├── audit.py               # SQLite SHA-256 event chain
│   ├── cli.py                 # JSON CLI, doctor, config, audit commands
│   ├── server.py              # Three-tool FastMCP stdio server
│   └── default_policy.yaml    # Packaged fail-closed starter policy
├── spectramcp/                # Optional offline DSP example helpers
├── agentpulse/                # Optional local process-scanner example
├── tests/                     # Unit, CLI, and in-process MCP tests
├── interlock.policy.yaml      # Editable repository policy
├── GATES.md                   # Product and release gate checklist
└── pyproject.toml             # Package metadata and console scripts

🩹 Troubleshooting

🧩 Contributing

The highest-value contributions are host adapters that make the gate unskippable, approval-flow examples, and adversarial tests for policy or audit edge cases. Start with CONTRIBUTING.md; every pull request must pass the gates in GATES.md.

📄 License

MIT © 2026 Oumar Ibrahim

🙏 Powered By

FastMCP · PyYAML · SQLite · NumPy

If this saved you from rebuilding the same policy gate—or one risky agent write—a ⭐ helps other MCP builders find it.