mcp-trust-annotations

SEP-1913 Trust & Sensitivity Annotations SDK for the Model Context Protocol

Annotate your MCP tools with data classification metadata, track sensitivity propagation across agent sessions, and enforce security policies — all with zero external dependencies.

---

Table of Contents

• Prerequisites
• Installation
• Running Tests
• Quick Start
• Progressive Adoption
• SEP-1913 Type Mapping
• License

---

Prerequisites

• Python 3.10 or later
• pip (included with Python)

---

Installation

From PyPI

pip install mcp-trust-annotations

From Source (Development)

git clone https://github.com/YOUR_HANDLE/mcp-trust-annotations.git
cd mcp-trust-annotations

Create and activate a virtual environment:

# Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate

Install in editable mode with dev dependencies:

cd packages/python
pip install -e ".[dev]"

Verify the installation:

python -c "import mcp_trust; print(f'mcp-trust-annotations v{mcp_trust.__version__} installed successfully')"

Expected output:

mcp-trust-annotations v0.1.0 installed successfully

---

Running Tests

Run All Tests

From the packages/python directory:

cd packages/python
pytest tests/ -v

Run a Specific Test File

# Core types
pytest tests/test_types.py -v

# Decorator & wire-format serialization
pytest tests/test_annotate.py -v

# Audit logging
pytest tests/test_emit.py -v

# Policy engine
pytest tests/test_policy.py -v

# Session propagation & sensitivity escalation
pytest tests/test_propagate.py -v

# SEP-1913 usability scenario oracle tests
pytest tests/test_usability_scenarios.py -v

Run a Single Test

pytest tests/test_usability_scenarios.py::TestScenario01_SimpleToolClassification -v

Test Suite Summary

Test File	Tests	Coverage Area
test_types.py	26	Core type construction, enum values, sensitivity ordering
test_annotate.py	27	@trust_annotated decorator, to_wire/from_wire roundtrip
test_emit.py	6	Structured JSON audit logging
test_policy.py	28	Policy rules, enforce/warn/audit modes, edge cases
test_propagate.py	16	SessionTracker, monotonic sensitivity escalation
test_usability_scenarios.py	35	10 real-world scenarios testing spec clarity
Total	138

---

Quick Start

1. Annotate a Tool

from mcp_trust import (
    trust_annotated,
    ReturnMetadata, Source, Regulated,
)

@trust_annotated(
    return_metadata=ReturnMetadata(
        source=Source.INTERNAL,
        sensitivity=Regulated.of("HIPAA"),
    ),
    attribution=("Epic-EHR",),
)
async def patient_lookup(patient_id: str) -> dict:
    """Look up a patient record from the EHR system."""
    return await ehr.get_patient(patient_id)

2. Serialize to MCP Wire Format

from mcp_trust import get_trust_annotations, to_wire

ann = get_trust_annotations(patient_lookup)
wire = to_wire(ann)

# Use in your MCP tools/list response:
tool_def = {
    "name": "patient_lookup",
    "description": "Look up a patient record",
    "inputSchema": { ... },
    "annotations": {
        "readOnlyHint": True,
        **wire,   # ← SEP-1913 fields injected here
    },
}

Output:

{
  "readOnlyHint": true,
  "attribution": ["Epic-EHR"],
  "returnMetadata": {
    "source": "internal",
    "sensitivity": { "regulated": { "scopes": ["HIPAA"] } }
  }
}

3. Track Session Propagation

from mcp_trust import SessionTracker, ResultAnnotations, SimpleDataClass, Regulated

tracker = SessionTracker(session_id="session-001")

# After calling health_check (no sensitive data)
tracker.merge(ResultAnnotations(sensitivity=SimpleDataClass.NONE), "health_check")
print(tracker.session.max_sensitivity)  # → none

# After calling patient_lookup (HIPAA-regulated)
tracker.merge(
    ResultAnnotations(sensitivity=Regulated.of("HIPAA"), attribution=("Epic-EHR",)),
    "patient_lookup",
)
print(tracker.session.max_sensitivity)  # → Regulated(HIPAA)

# Sensitivity never de-escalates
tracker.merge(ResultAnnotations(sensitivity=SimpleDataClass.NONE), "health_check")
print(tracker.session.max_sensitivity)  # → still Regulated(HIPAA)

4. Enforce Policies

from mcp_trust import PolicyEngine

engine = PolicyEngine(mode="enforce")  # "audit" | "warn" | "enforce"
engine.register_tool("patient_lookup", wire)

decision = engine.evaluate(
    "patient_lookup",
    action="call",
    target_destination="public",
)
print(decision.allowed)   # → False
print(decision.reason)    # → "Regulated data (HIPAA) cannot leave organization"

5. Enable Audit Logging

from mcp_trust import enable_logging

enable_logging(agent_id="urn:agent:my-app")   # JSON to stderr
# enable_logging(stream=sys.stdout)            # JSON to stdout
# enable_logging(callback=send_to_siem)        # custom handler

Every tool call emits structured JSON:

{
  "ts": "2026-02-26T10:30:00+00:00",
  "event": "tool.call",
  "tool": "patient_lookup",
  "agent": "urn:agent:my-app",
  "annotations": {
    "attribution": ["Epic-EHR"],
    "returnMetadata": { "source": "internal", "sensitivity": { "regulated": { "scopes": ["HIPAA"] } } }
  }
}

---

Progressive Adoption

You don't have to use everything at once. Adopt incrementally:

Level	What You Use	What You Get
Level 0	@trust_annotated() only	Metadata on functions — zero runtime overhead
Level 1	+ to_wire()	SEP-1913 annotations in MCP tools/list responses
Level 2	+ SessionTracker	Cross-tool sensitivity tracking within agent sessions
Level 3	+ PolicyEngine	Active enforcement (block/warn/escalate)
Level 4	+ enable_logging()	Full audit trail for compliance

---

SEP-1913 Type Mapping

Every type in this SDK maps 1:1 to SEP-1913's TypeScript schema:

SEP-1913 (TypeScript)	Python SDK	Wire Format
"ephemeral" | "system" | ...	Destination enum	"ephemeral"
"untrustedPublic" | ...	Source enum	"untrustedPublic"
"benign" | "consequential" | "irreversible"	Outcome enum	"benign"
"none" | "user" | "pii" | "financial" | "credentials"	SimpleDataClass enum	"pii"
{ regulated: { scopes: string[] } }	Regulated dataclass	{"regulated": {"scopes": ["HIPAA"]}}
DataClass	DataClass union type	string or object
InputMetadata	InputMetadata dataclass	{"destination": ..., "sensitivity": ..., "outcomes": ...}
ReturnMetadata	ReturnMetadata dataclass	{"source": ..., "sensitivity": ...}
ToolAnnotations extensions	TrustAnnotations dataclass	Spread into annotations dict

---

License

MIT