MCP 服务器

shugo

A minimal guardrails framework for AI agents, acting as an MCP proxy to enforce policies, approvals, and audit logging on tool calls.

README

<h3>A practical, readable AI agent guardrails framework —<br>and a working example of how agents should be governed.</h3>

<a href="docs/">Documentation</a> · <a href="#-quickstart">Quickstart</a> · <a href="#-repo-structure">Repo Structure</a> · <a href="policies/">Policies</a> · <a href="#️-roadmap">Roadmap</a>

<br>

uvx shugo init      # scaffold guardrails.yaml from your existing MCP config
uvx shugo serve     # start guarding

<sub>Available on PyPI as <a href="https://pypi.org/project/shugo/"><code>shugo</code></a> · latest version <b>0.1.0</b> (2026-07-30)</sub>

</div>

<br>

<h2>🛡️ What is SHUGO?</h2>

<p>SHUGO is a guardrails-first framework for the agentic AI community.</p>

<p>It helps teams define policies, approval gates, tool access, evaluation, observability, and incident response in one repo.</p>

<p>It is designed to make AI agent behaviour <b>bounded, visible, and accountable</b>.</p>

<p>Responsible AI should not live in a slide deck. It should live in the same repo as the agent — expressed as code, enforced at runtime, and producing evidence by default.</p>

</td> <td width="58%" valign="top">

<pre><code>shugo_repo -> shugo_policy -> shugo_runtime</code></pre>

<h2>📁 Repo Structure</h2>

<table> <tr><td><code>src/shugo/</code></td><td>Proxy, policy engine, audit, CLI</td></tr> <tr><td><code>policies/</code></td><td>Policy rules and standards</td></tr> <tr><td><code>examples/</code></td><td>Runnable demo agents and configs</td></tr> <tr><td><code>evaluations/</code></td><td>Tests, evals, and benchmarks</td></tr> <tr><td><code>logs/</code></td><td>Runtime events and audit logs</td></tr> <tr><td><code>docs/</code></td><td>Quickstart, policy guide, layers</td></tr> <tr><td><code>guardrails.yaml</code></td><td>Guardrail configuration</td></tr> <tr><td><code>incident-playbook.md</code></td><td>Incident response and recovery</td></tr> <tr><td><code>README.md</code></td><td>Project overview and getting started</td></tr> </table>

</td> </tr> </table>

A guardrail should not merely tell an agent what it should do.<br> The system should enforce what the agent is allowed to do.

</div>

<h2>🧱 Five Guardrail Layers</h2>

<table> <tr> <td width="20%" valign="top"><h4>👤 Identity<br>& Access</h4></td> <td width="20%" valign="top"><h4>🗄️ Data<br>& Context</h4></td> <td width="20%" valign="top"><h4>🔧 Action<br>& Autonomy</h4></td> <td width="20%" valign="top"><h4>🛡️ Safety<br>& Resilience</h4></td> <td width="20%" valign="top"><h4>🎖️ Governance<br>& Assurance</h4></td> </tr> <tr> <td valign="top">Verify who and what can act, with least privilege and strong authentication.</td> <td valign="top">Control what data enters the agent and how context is handled.</td> <td valign="top">Restrict tools, enforce policies, and require approvals for high-risk actions.</td> <td valign="top">Detect, block, and recover from unsafe behaviour and system failures.</td> <td valign="top">Audit, evaluate, and report to ensure accountability and continuous trust.</td> </tr> <tr> <td align="center"><sub>v0.1 · partial</sub></td> <td align="center"><sub>v0.1 · partial</sub></td> <td align="center"><sub>v0.1 · <b>full</b></sub></td> <td align="center"><sub>v0.1 · partial</sub></td> <td align="center"><sub>v0.1 · <b>full</b></sub></td> </tr> </table>

Layers ③ and ⑤ ship complete in v0.1. The others ship at the minimum depth needed to make those two credible, then deepen along the roadmap.

⚙️ How it works

SHUGO presents itself to your agent as a standard MCP server and sits between the agent and the tools it calls. Every tools/call is evaluated against a human-readable policy file before it reaches an upstream server. No protocol changes. No agent code changes.

┌──────────────┐   MCP    ┌───────────┐   MCP    ┌──────────────────┐
│  MCP client  │ ───────▶ │   SHUGO   │ ───────▶ │ Upstream MCP     │
│ (any agent)  │ ◀─────── │   guard   │ ◀─────── │ servers (n)      │
└──────────────┘          └─────┬─────┘          └──────────────────┘
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
              guardrails    audit log    approval
                 .yaml      (JSONL)       channel

Works with Claude Desktop, Claude Code, Cursor, VS Code, and any framework with an MCP adapter — LangGraph, CrewAI, the OpenAI Agents SDK, n8n.

⚡ Quickstart

uvx shugo init      # scaffold a policy from your existing MCP config
uvx shugo serve     # start guarding

Point your MCP client at SHUGO instead of your servers:

{
  "mcpServers": {
    "shugo": {
      "command": "uvx",
      "args": ["shugo", "serve", "--config", "guardrails.yaml"]
    }
  }
}

Your agent now sees only the tools policy allows, blocks on anything needing approval, and writes an audit record for every call it makes.

📜 Policy as code

The most important file in the project. Design target: a risk lead can read it unaided, and a reviewer can diff it in a pull request.

version: "0.1"

defaults:
  decision: deny            # deny by default; allowlist upward
  on_error: deny            # fail closed

rules:
  - id: read-only-github
    match:
      server: github
      tool: ["get_*", "list_*", "search_*"]
    decision: allow

  - id: no-force-push
    description: Force push can destroy history irrecoverably
    match:
      server: github
      tool: push
      args: { force: true }
    decision: deny
    reason: Force push is prohibited for autonomous agents.
    controls: [OWASP-LLM06, NIST-AI-RMF-MANAGE-2.2]

  - id: ticket-write-needs-approval
    match:
      server: tickets
      tool: ["update_ticket", "close_ticket"]
    decision: escalate
    approval:
      channel: cli
      timeout_seconds: 300
      on_timeout: deny
    controls: [EU-AI-ACT-ART-14]

Deny by default. First match wins, top to bottom. Globs, not regex — readability is the constraint.

🧾 Evidence, not just logs

Enforcement without evidence is unauditable. Evidence without enforcement is theatre. SHUGO does both.

shugo evidence --framework owasp-llm --since 30d --out evidence/

Reads the audit log and produces a control-by-control bundle: which rules were in force, how often each fired, approval latency, exceptions, coverage gaps, and a hash-chain integrity check.

Framework mappings ship as data files sourced from public standards only — NIST AI RMF, EU AI Act, OWASP Top 10 for LLM Applications, and ISO/IEC 42001 control identifiers.

Scope note. SHUGO produces evidence about the guardrail layer. It does not certify an organisation as compliant with any standard.

🧰 CLI

Command	Purpose
`shugo serve`	Run the guard proxy
`shugo init`	Scaffold a starter policy from installed MCP servers
`shugo validate`	Lint and schema-check the policy file
`shugo explain`	Dry-run a call — see which rule fires and why
`shugo audit tail` / `verify`	Inspect the log, verify the hash chain
`shugo evidence`	Generate an evidence bundle
`shugo halt`	Kill switch — deny all calls immediately

📦 Release notes — v0.1.0 (2026-07-30)

First release. Everything in the sections above is now real code you can install with uvx shugo.

What ships:

Guard proxy over stdio — SHUGO speaks MCP to both your client and any number of upstream servers, namespaces tools as <server>__<tool>, and applies policy on every tools/call.
Policy engine — deny-by-default, first-match-wins, fnmatch globs on server/tool, nested-equality on args. Decisions: allow, deny, escalate.
Human approvals — file-drop queue at ~/.shugo/pending/ resolved by either shugo approve --watch (Rich TUI) or an opt-in local HTTP UI (shugo serve --approvals http).
Hash-chained audit log — append-only JSONL, rolling SHA-256, NFC-canonical JSON, per-line fsync. shugo audit verify detects any post-hoc edit.
Evidence bundles — shugo evidence -f <owasp-llm|nist-ai-rmf|eu-ai-act|iso-42001> produces a control-mapped report, policy snapshot, filtered audit-log window, and SHA-256 manifest.
shugo init — reads Claude Desktop / Code / Cursor / VS Code MCP configs, enumerates upstream tools, writes a starter policy, prints the exact JSON snippet to paste.
Kill switch — shugo halt denies everything until shugo unhalt.

Quality: 102 fast tests + 1 e2e test (real @modelcontextprotocol/server-filesystem via npx). CI on Python 3.11–3.13 × macOS / Ubuntu / Windows. All dependencies MIT / BSD-3 / Apache-2.0; no copyleft, no BSL.

Full changelog: CHANGELOG.md · GitHub release: v0.1.0

🗺️ Roadmap

Version	Theme	Status
v0.1	Guard proxy, policy engine, approvals, audit log, evidence packs	✅ released 2026-07-30
v0.2	Layer ① depth — OAuth 2.1 / OIDC identity, per-principal policy, delegation scoping	planned
v0.3	Layer ② depth — retrieval boundaries, context filters, memory access rules	planned
v0.4	Layer ④ depth — injection detection, output validation, rollback	planned
v0.5	Layer ⑤ depth — policy regression suites, adversarial harness	planned
v1.0	Frozen policy schema, semantic versioning guarantee, plugin API	planned

🤝 Contributing

SHUGO is built in public, and the contribution ladder is deliberately low to the ground:

policy pack → scenario test → framework mapping → core

A new policy pack is a self-contained YAML file. You do not need to read the codebase to ship one. Start with CONTRIBUTING.md and the good first issues.

📄 License

Released under the MIT License. Use it, fork it, adapt it to your own agent architecture — that is the point.

<br>

<sub>守護 — <em>shugo</em>, to guard and protect.</sub>

</div>

shugo

README

⚙️ How it works

⚡ Quickstart

📜 Policy as code

🧾 Evidence, not just logs

🧰 CLI

📦 Release notes — v0.1.0 (2026-07-30)

🗺️ Roadmap

🤝 Contributing

📄 License

推荐服务器