flowchart TD
    subgraph Agents["Frontier Clinical AI Agents"]
        Claude[Claude Desktop / Claude Code]
        Cursor[Cursor IDE / Windsurf]
        Other[Enterprise LLM Gateway / Pi Agent]
    end

    subgraph Server["medplum-mcp-rs (Zero-Copy Engine)"]
        Gate["assert_write_permitted\n(Pillar 1: Safety Gate & NFKC)"]
        Vault["SecretString Enclave\n(Pillar 2: Zero-Leak Credentials)"]
        Distill["In-Situ SIMD Distillation\n(Pillar 3: 89-95% Token Diet)"]
        Audit["HMAC Flight Recorder\n(Pillar 4: Dual JSONL/120B Binary)"]
        Cache["Rkyv Snapshot Cache\n(10.3 ns Zero-Copy Lookups)"]
    end

    subgraph DataPlane["FHIR Data Plane"]
        Sandbox["St. Jude In-Memory Sandbox\n(--demo mode)"]
        Mock["OpenAPI 3.0 Mock Server\n(medplum-mcp-rs mock-server)"]
        Medplum["Medplum Cloud / On-Premise FHIR API"]
    end

    Agents -->|JSON-RPC via Linux Pipes / SSE| Gate
    Gate -->|403 Blocked| Audit
    Gate -->|Permitted Draft| Vault
    Vault --> Cache
    Vault --> Sandbox
    Vault --> Mock
    Vault --> Medplum
    Sandbox -->|Raw FHIR JSON| Distill
    Mock -->|Raw FHIR JSON| Distill
    Medplum -->|Raw FHIR JSON| Distill
    Distill -->|Distilled Payload| Audit
    Audit -->|Chained Response| Agents

+-----------------------------------------------------------------------------------------+
|                                SYSTEM ARCHITECTURE (ASCII)                              |
+-----------------------------------------------------------------------------------------+
|                                                                                         |
|   [ Clinical AI Agents ] (Claude Desktop, Claude Code, Cursor, Windsurf, Pi Agent)      |
|              |                                                                          |
|              | JSON-RPC 2.0 via anonymous Linux pipes (vmsplice/splice) or SSE/HTTP     |
|              v                                                                          |
|   +---------------------------------------------------------------------------------+   |
|   |                         MEDPLUM CLINICAL MCP SERVER                             |   |
|   |                                                                                 |   |
|   |   [ Pillar 1: Non-Bypassable Runtime Safety Gate ]                              |   |
|   |   - Blocks terminal states: active, completed, cancelled, final                |   |
|   |   - Unicode NFKC normalization + Cyrillic/Greek homoglyph evasion defense       |   |
|   |   - Affine Typestates: MedicationRequest<Draft> requires PhysicianWitness       |   |
|   |                                                                                 |   |
|   |   [ Pillar 2: Zero-Leak Credential & PHI Enclave ]                              |   |
|   |   - Multi-vault resolver (1Password, AWS Secrets Manager, HashiCorp Vault)      |   |
|   |   - SecretString wraps secrets; scrubs bearer tokens and sensitive URIs         |   |
|   |                                                                                 |   |
|   |   [ Pillar 3: Three-Tier In-Situ SIMD Distiller ]                               |   |
|   |   - distill_raw_slice(&mut [u8]) parses HTTP responses with 0 Serde heap allocs |   |
|   |   - 89% - 95% token diet: Compact (15KB), Standard (31KB), Executive (23KB)     |   |
|   |                                                                                 |   |
|   |   [ Pillar 4: Dual-Format Cryptographic Flight Recorder ]                       |   |
|   |   - Chained HMAC-SHA256 signatures: Seq : Time : Status : Hash : PrevSig        |   |
|   |   - Fixed 120-byte C-ABI binary frames (--audit-format binary, 75.2% savings)   |   |
|   |                                                                                 |   |
|   |   [ In-Memory Zero-Copy Rkyv Snapshot Cache ]                                   |   |
|   |   - 10.3 ns zero-deserialization lookups (392.8x faster than Serde Value)       |   |
|   +---------------------------------------------------------------------------------+   |
|         |                     |                            |                   |        |
|         | Outbound REST       | Zero-Copy Lookups          | Mock REST         | Append |
|         v                     v                            v                   v        |
|   [ Medplum Cloud ]   [ St. Jude Sandbox ]         [ OpenAPI Mock ]     [ Audit Ledger ]|
|   (FHIR R4 API)       (Pediatric Oncology)         (Axum Server)        (JSONL + Binary)|
+-----------------------------------------------------------------------------------------+

# Launch interactive demo console
xdg-open docs/demo/index.html || open docs/demo/index.html

# Clone repository
git clone https://github.com/medplum/medplum-mcp.git
cd medplum-mcp

# Install editable package with development and verification dependencies
pip install -e ".[dev,formal]"

# Launch stdio MCP server for Claude Desktop / Cursor / Windsurf
medplum-mcp --demo

# Launch SSE HTTP transport on port 8080
medplum-mcp --demo --transport sse --port 8080

# Launch 60 FPS Interactive Ratatui Terminal UI Dashboard (Rust Zero-Copy Engine)
medplum-mcp-rs tui --demo

# Run 90-minute soak & invariant stress test across 16 OS threads
medplum-mcp-rs soak --duration-secs 5400 --workers 16

# Run empirical microsecond performance benchmarks
medplum-mcp-rs bench

# Cryptographically verify HIPAA HMAC audit ledger & safety invariants
medplum-mcp-rs verify --strict

export MEDPLUM_BASE_URL="https://api.medplum.com"
export MEDPLUM_CLIENT_ID="your-client-id"
export MEDPLUM_CLIENT_SECRET="your-client-secret"

# Writes default to blocked (read-only mode)
medplum-mcp

# Allow draft mutations (enforces draft-only safety invariant)
medplum-mcp --allow-writes

{
  "mcpServers": {
    "medplum": {
      "command": "medplum-mcp",
      "args": ["--demo"],
      "env": {
        "MEDPLUM_CLIENT_ID": "op://Private/Medplum/client-id",
        "MEDPLUM_CLIENT_SECRET": "op://Private/Medplum/client-secret"
      }
    }
  }
}

# View configuration for Cursor, Windsurf, Claude Code, or all
medplum-mcp config --client cursor
medplum-mcp config --client windsurf
medplum-mcp config --all

# 1. Start mock server mimicking upstream Medplum HTTP API
medplum-mcp mock-server --port 8000

# 2. Verify cryptographic integrity of HMAC audit flight recorder
medplum-mcp audit verify --log-file audit.jsonl

# 3. Inspect recent audit entries
medplum-mcp audit inspect --limit 20

# 4. Run safety verification suite (Deterministic Invariants + Audit Check)
medplum-mcp verify --strict --output-format terminal

# 1. Run Python Quality Gate: Ruff lint/format, Mypy Strict, and Pytest (183 tests)
./run_checks.sh

# 2. Run Rust Quality Gate: rustfmt check, clippy with 0 warnings, and cargo test (209+ tests)
./run_rust_checks.sh