MCP工具

Install

pip install sanna                # Core library (Python 3.10+)
pip install sanna[mcp]           # MCP server + gateway
pip install sanna[otel]          # OpenTelemetry bridge

Quick Start — Library Mode

pip install sanna

Set up governance (one-time):

```bash sanna init # Choose template, set agent name, enforcement level sanna keygen # Generate Ed25519 keypair (~/.sanna/keys/)

Quick Start — Gateway Mode

No code changes to your agent. The gateway sits between your MCP client and downstream servers.

pip install sanna[mcp]

sanna init         # Creates constitution.yaml + gateway.yaml
sanna keygen --label gateway
sanna sign constitution.yaml --private-key ~/.sanna/keys/<key-id>.key
sanna gateway --config gateway.yaml

Minimum gateway.yaml:

gateway:
  constitution: ./constitution.yaml
  signing_key: ~/.sanna/keys/<gateway-key-id>.key        # Key generated by sanna keygen
  constitution_public_key: ~/.sanna/keys/<author-key-id>.pub  # Public key of constitution signer
  receipt_store: .sanna/receipts/

downstream:
  - name: notion
    command: npx
    args: ["-y", "@notionhq/notion-mcp-server"]
    env:
      OPENAPI_MCP_HEADERS: "${OPENAPI_MCP_HEADERS}"
    default_policy: can_execute

Point your MCP client (Claude Desktop, Claude Code, Cursor) at the gateway instead of directly at your downstream servers. Every tool call is now governed. The gateway governs tool calls that pass through it — only actions that cross the governance boundary produce receipts. Reasoning is captured via the explicit _justification parameter in tool calls, not from internal model reasoning. The gateway cannot observe LLM chain-of-thought.

MCP Client (Claude Desktop / Claude Code / Cursor)
        |
        v  (MCP stdio)
sanna-gateway
        |  1. Receive tool call
        |  2. Evaluate against constitution
        |  3. Enforce policy (allow / escalate / deny)
        |  4. Generate signed receipt
        |  5. Forward to downstream (if allowed)
        v  (MCP stdio)
Downstream MCP Servers (Notion, GitHub, filesystem, etc.)

Demo

Run a self-contained governance demo — no external dependencies:

sanna demo

This generates keys, creates a constitution, simulates a governed tool call, generates a receipt, and verifies it.

Remote HTTP endpoint with retry

cloud = CloudHTTPSink("https://governance.example.com/receipts", api_key="...")

CLI Reference

All commands are available as sanna <command> or sanna-<command>:

API Reference

The top-level sanna package exports 17 names:

from sanna import (
    __version__,          # Package version string
    sanna_observe,        # Decorator: governance wrapper for agent functions
    SannaResult,          # Return type from @sanna_observe-wrapped functions
    SannaHaltError,       # Raised when a halt-enforcement invariant fails
    generate_receipt,     # Generate a receipt from trace data
    SannaReceipt,         # Receipt dataclass
    verify_receipt,       # Offline receipt verification
    VerificationResult,   # Verification result dataclass
    ReceiptStore,         # SQLite-backed receipt persistence
    DriftAnalyzer,        # Per-agent failure-rate trending
    # Receipt sinks (v1.0.0)
    ReceiptSink,          # Abstract base class for receipt persistence
    NullSink,             # No-op sink (default)
    LocalSQLiteSink,      # SQLite-backed local persistence
    CloudHTTPSink,        # HTTP endpoint with retry and buffer-on-failure
    CompositeSink,        # Fan-out to multiple sinks
    SinkResult,           # Result from a sink.send() call
    FailurePolicy,        # Enum: LOG, BUFFER, RAISE
)

Everything else imports from submodules: sanna.constitution, sanna.crypto, sanna.enforcement, sanna.evaluators, sanna.verify, sanna.bundle, sanna.hashing, sanna.drift, sanna.sinks.