flowchart TB
    API["ShipSmart-API (agent / RAG / concierge)"] -->|"MCP over HTTP + X-MCP-Api-Key"| APP
    subgraph APP["FastAPI app (app/main.py)"]
        AUTH["require_api_key dependency"]
        EP["GET / · GET /health · POST /tools/list · POST /tools/call"]
        INV["_enforce_read_only(registry) at lifespan"]
    end
    subgraph REG["ToolRegistry (app/tools)"]
        T1[validate_address]
        T2[get_quote_preview]
        T3[calculate_dimensional_weight]
        T4[estimate_package_profile]
        T5[parse_address]
        T6[check_restricted_items]
    end
    subgraph CTL["Cross-cutting controls"]
        JS["JSON Schema 2020-12 validate_input (additionalProperties=false)"]
        TG["tool_guard: SSRF egress allowlist + per-caller scopes"]
        TA["tool_audit: append-only, args-hashed"]
        IN["integrity: sha256 descriptor checksums"]
    end
    subgraph PROV["Provider adapters (Strategy)"]
        P0["MockProvider (keyless default)"]
        P1[FedExProvider]
        P2[UPSProvider]
        P3[USPSProvider]
        P4[DHLProvider]
    end
    CARR["Carrier REST APIs (sandbox base URLs)"]
    APP --> REG
    REG --> CTL
    REG --> PROV
    PROV -->|"httpx, explicit timeouts"| CARR

Refusing to start: non-read-only tool(s) registered: [...].
ShipSmart-MCP serves read/preview tools only; writes, bookings, and
money movement belong to the Java Orchestrator.

flowchart TB
    S[Service starting] --> B["_build_registry()"]
    B --> E["_enforce_read_only(registry)"]
    E --> C{"served tools ⊆ READ_ONLY_TOOL_ALLOWLIST?"}
    C -->|yes| UP["App serves traffic"]
    C -->|no| X["raise RuntimeError — refuse to start"]
    X --> MSG["writes, bookings, money movement belong to the Java Orchestrator"]

sequenceDiagram
    participant C as Caller (ShipSmart-API)
    participant A as FastAPI (require_api_key)
    participant R as ToolRegistry
    participant G as tool_guard
    participant P as Provider adapter
    participant AU as tool_audit
    C->>A: POST /tools/call (X-MCP-Api-Key)
    A->>R: lookup(tool)
    R->>R: validate_input (JSON Schema 2020-12)
    R->>G: is_authorized(caller, tool)? egress allowed?
    G-->>R: allowed
    R->>P: execute(args)
    P->>P: httpx call, explicit timeout
    P-->>R: read-only result
    R->>AU: record(tool, caller, request_id, args_hash, status, latency_ms)
    R-->>C: typed result

sequenceDiagram
    participant T as Tool execution
    participant G as tool_guard
    T->>G: assert_egress_allowed("http://169.254.169.254/...")
    G->>G: _is_public? link-local IP literal detected
    G--xT: EgressDeniedError (no request ever leaves)

sequenceDiagram
    participant C as Caller
    participant R as Registry
    participant I as integrity
    C->>R: tools/call with unexpected field
    R--xC: validation error (additionalProperties=false, before execute())
    C->>I: verify_descriptors(registry, expected_checksums)
    I-->>C: drift list (changed / added / removed descriptors)
    Note over I: sha256 over name + description + input schema

stateDiagram-v2
    [*] --> Received: POST /tools/call
    Received --> Authenticated: X-MCP-Api-Key ok
    Received --> Rejected: bad or missing key (401)
    Authenticated --> Validated: JSON Schema ok
    Authenticated --> Rejected: unknown or invalid args
    Validated --> Guarded: caller in scope AND egress allowed
    Validated --> Denied: off-scope or EgressDenied
    Guarded --> Executing: adapter call (timeout armed)
    Executing --> Succeeded: carrier or pure result
    Executing --> Failed: timeout or carrier error
    Succeeded --> Audited: args-hashed record
    Failed --> Audited: error_class recorded
    Denied --> Audited
    Audited --> [*]

classDiagram
    class Tool {
        <<abstract>>
        +name
        +description
        +parameters
        +schema() JSONSchema2020_12
        +validate_input(args)
        +execute(args)
    }
    Tool <|-- ValidateAddress
    Tool <|-- GetQuotePreview
    Tool <|-- CalculateDimensionalWeight
    Tool <|-- EstimatePackageProfile
    Tool <|-- ParseAddress
    Tool <|-- CheckRestrictedItems
    class ToolRegistry {
        +list_tools()
        +get(name)
    }
    ToolRegistry o-- Tool
    class ShippingProvider {
        <<interface>>
        +validate_address()
        +quote_preview()
    }
    ShippingProvider <|.. MockProvider
    ShippingProvider <|.. FedExProvider
    ShippingProvider <|.. UPSProvider
    ShippingProvider <|.. USPSProvider
    ShippingProvider <|.. DHLProvider
    GetQuotePreview ..> ShippingProvider
    ValidateAddress ..> ShippingProvider
    class ToolGuard {
        +allowed_hosts()
        +check_egress(url)
        +is_authorized(caller, tool)
    }
    class ToolAudit {
        +args_hash(args) sha256
        +record(...)
    }

flowchart LR
    CALL["tools/call"] --> H["args_hash = sha256(args)"]
    H --> REC["record: tool · version · caller · request_id · args_hash · status · error_class · latency_ms"]
    REC --> LOG[("append-only tool audit")]
    LOG --> Q["what did the tool layer do, for whom, how fast = a query"]

xychart-beta
    title "Tool latency budget in ms (target)"
    x-axis ["pure-tools", "validate_address", "quote_preview"]
    y-axis "ms (target)" 0 --> 2000
    bar [10, 1200, 1800]

flowchart LR
    A["Render: shipsmart-api-python"] -->|X-MCP-Api-Key| M["Render: shipsmart-mcp (this)"]
    M --> C1["FedEx sandbox"]
    M --> C2["UPS sandbox"]
    M --> C3["USPS sandbox"]
    M --> C4["DHL sandbox"]
    OPS[Operator] -.->|"GET /health — tool count"| M

uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
curl localhost:8001/health        # {"service":"shipsmart-mcp","tools":N}

uv run pytest        # 94 tests — keyless (mock provider), fast
uv run ruff check .