Skip to content

SHUGO v0.1.0 — first release

Latest
Latest

Choose a tag to compare

View all tags
@aritraghosh01 aritraghosh01 released this 30 Jul 15:13
v0.1.0
f049a39
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

First release of SHUGO — a minimal MCP guardrails proxy. Install with uvx shugo and integrate into any MCP client (Claude Desktop, Claude Code, Cursor, VS Code) in under 5 minutes.

Highlights

  • Guard proxy over stdio — SHUGO speaks MCP to both your client and any number of upstream servers, forwarding tools/call only when policy allows. Tools are namespaced <server>__<tool> so multiple upstreams merge cleanly.
  • YAML policy engine — deny-by-default, first-match-wins, fnmatch globs on server/tool, nested-equality on args. Three decisions: allow, deny, escalate.
  • Human approvals in two flavors — file-drop queue at ~/.shugo/pending/, resolved by either shugo approve --watch (Rich TUI) or an opt-in browser UI (shugo serve --approvals http).
  • Tamper-evident audit — append-only JSONL, rolling SHA-256 hash chain, 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 a SHA-256 manifest.
  • shugo init — reads your Claude Desktop / Code / Cursor / VS Code MCP config, enumerates upstream tools, writes a starter policy, prints the exact JSON snippet to paste.
  • Kill switch — shugo halt denies everything at the top of the handler until shugo unhalt.

Installation

uvx shugo init          # scaffold guardrails.yaml from your existing MCP config
uvx shugo serve         # run the guard

Stack

All permissive OSS: mcp (MIT), typer (MIT), pydantic v2 (MIT), PyYAML (MIT), rich (MIT), inputimeout (MIT), aiohttp (Apache-2.0). No copyleft, no BSL, no commercial deps.

Quality

  • 102 fast tests + 1 e2e test (real @modelcontextprotocol/server-filesystem via npx)
  • CI matrix: Python 3.11 / 3.12 / 3.13 × macOS / Ubuntu / Windows
  • Clean-room implementation from the README's design intent

Docs

What's next (roadmap)

  • v0.2 — Layer ① depth: OAuth 2.1 / OIDC identity, per-principal policy, delegation scoping
  • v0.3 — Layer ② depth: retrieval boundaries, context filters, memory access rules
  • v0.4 — Layer ④ depth: injection detection, output validation, rollback
  • v0.5 — Layer ⑤ depth: policy regression suites, adversarial harness
  • v1.0 — Frozen policy schema, semver guarantee, plugin API

Scope note

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

Assets 2
Loading