# 1. Install dependencies with uv
uv sync

# 2. Seed deterministic synthetic database and generate an API key
uv run python scripts/seed_db.py --out data/claims.db && uv run python scripts/make_key.py --id analyst-1 --tools all

# 3. Start the MCP server (stdio transport for inspector / local agents)
CLAIMS_DB_PATH=data/claims.db uv run python -m claims_mcp --transport stdio

# Terminal 1: Launch the HTTP server on port 8765
CLAIMS_DB_PATH=data/claims.db CLAIMS_KEYS_FILE=keys.json uv run python -m claims_mcp --transport http

# Terminal 2: Run the comprehensive live demo client
uv run python scripts/demo_client.py --key <YOUR_GENERATED_RAW_KEY>

flowchart TB
    Client["MCP Client\n(Claude Desktop / Inspector / AI Agent / demo_client.py)"]
    
    subgraph Transport ["Transport Layer"]
        STDIO["stdio JSON-RPC Transport\n(Local Dev / Inspector)"]
        HTTP["Streamable HTTP Transport (127.0.0.1:8765)\nAuthorization: Bearer <key>"]
    end
    
    subgraph SecurityMiddleware ["Security & Policy Guardrails (T6)"]
        Auth["Bearer Key Verification\n(SHA-256 Hashed, Constant-Time hmac.compare_digest)"]
        RateLimit["Rate Limiter\n(In-Memory Fixed Window: 60 req/min)"]
        Allowlist["Tool Authorization Allowlist\n(Per-Key Tool Restrictions)"]
    end
    
    subgraph S13Pipeline ["Pipeline & Input Interceptor (T8 / S13)"]
        Interceptor["S13 Input Interceptor\n(Pre-SDK CallTool Hook)"]
        Validator["Strict Pydantic Input Validation\n(Regex Patterns, Strict Types, Extra Fields Forbidden)"]
    end
    
    subgraph DatabaseLayer ["Read-Only Database Engine (T4 / T5b)"]
        DBConn["SQLite Connection\n(One Connection Per Call)"]
        Authorizer["Triple-Layer Read Barrier\n1. URI mode=ro\n2. PRAGMA query_only=ON\n3. SQLite Read-Only Authorizer"]
        Queries["Strict Parameterized Queries\n(AST-Enforced ? Placeholders Only)"]
        ClaimsDB[("claims.db\n(Synthetic SQLite Database)")]
    end
    
    subgraph OutputSanitization ["Output Sanitization & Audit (T6 / T7)"]
        Sanitizer["Untrusted Text Sanitizer\n(Strip Control Chars, Unicode Cf, Cap 1000, Flag untrusted: true)"]
        AuditLogger["Fail-Closed Audit Logger\n(Append-Only JSONL + Stderr Log)"]
        AuditFile[("audit/audit.jsonl\n(Fail-Closed JSONL Log)")]
    end
    
    Client --> STDIO
    Client --> HTTP
    HTTP --> Auth
    Auth --> RateLimit
    STDIO --> RateLimit
    RateLimit --> Allowlist
    Allowlist --> Interceptor
    Interceptor --> Validator
    Validator --> DBConn
    DBConn --> Authorizer
    Authorizer --> Queries
    Queries --> ClaimsDB
    ClaimsDB --> Sanitizer
    Sanitizer --> AuditLogger
    AuditLogger --> AuditFile
    AuditLogger --> Client

sequenceDiagram
    autonumber
    actor Caller as MCP Client
    participant HTTP as ASGI Middleware
    participant Server as ClaimsMCPServer (Pipeline)
    participant Sec as Security Engine (T6)
    participant DB as SQLite Engine (T4)
    participant Audit as AuditLogger (T7)

    Caller->>HTTP: JSON-RPC tools/call (Bearer Key)
    HTTP->>Sec: Verify Bearer Key Hash (Constant-Time)
    alt Invalid Key
        HTTP-->>Caller: HTTP 401 Unauthorized (Empty Body)
    end
    HTTP->>Server: Forward Request with Caller Context
    
    Server->>Sec: Check Rate Limit (60 req/min)
    alt Rate Limit Exceeded
        Server->>Audit: Log rate_limited outcome
        Server-->>Caller: RATE_LIMITED: try again later (is_error=True)
    end
    
    Server->>Sec: Check Tool Allowlist
    alt Tool Not Permitted
        Server->>Audit: Log denied outcome (FORBIDDEN_TOOL)
        Server-->>Caller: FORBIDDEN_TOOL (is_error=True)
    end
    
    Server->>Server: Validate Input & Check S13
    alt Invalid Input or Extra Parameter
        Server->>Audit: Log invalid outcome (invalid_fields only, args=null)
        Server-->>Caller: INVALID_INPUT: <field> is invalid (is_error=True)
    end
    
    Server->>DB: Open Read-Only Connection (mode=ro, query_only=ON, Authorizer)
    DB->>DB: Execute Fixed SQL Query with ? Parameters
    DB-->>Server: Return Row Data
    Server->>DB: Close Connection
    
    alt Row Not Found
        Server->>Audit: Log not_found outcome
        Server-->>Caller: NOT_FOUND (is_error=True)
    end
    
    opt Tool is get_claim_notes
        Server->>Sec: Sanitize Note Text (Strip Cf, Cap 1000, untrusted: true)
    end
    
    Server->>Audit: Write JSONL Audit Record (ts, request_id, caller, tool, outcome)
    alt Audit Log Write Fails
        Server-->>Caller: INTERNAL: reference <request_id> (Fail Closed)
    else Audit Log Write Succeeds
        Server-->>Caller: CallToolResult JSON Response (is_error=False)
    end

claims-mcp-server/
│
├── .dockerignore                     # Docker build exclusion rules
├── .env.example                      # Template for environment configuration
├── .gitattributes                    # Line ending LF normalizations
├── .gitignore                        # Git exclusion rules (keys, .env, DBs, logs)
├── .pre-commit-config.yaml           # Pre-commit linting and security hooks
├── .python-version                   # Pinned Python version (3.12)
├── Dockerfile                        # Multi-stage non-root container with health check
├── LICENSE                           # MIT open source license (Adwitiya Pandey)
├── PROGRESS.md                       # Task execution and milestone completion log
├── README.md                         # Enterprise documentation and operational manual
├── SPEC.md                           # Formal scope contract and requirements specification
├── TASKS.md                          # Sequential autonomous implementation task breakdown
├── THREAT_MODEL.md                   # STRIDE threat model and requirement-to-test verification matrix
├── pyproject.toml                    # Package metadata, dependencies, and test configurations
├── schema.sql                        # SQLite DDL schema contract with strict CHECK constraints
├── uv.lock                           # Deterministic cryptographic dependency lockfile
│
├── audit/
│   └── audit.jsonl                   # Append-only fail-closed structured JSONL audit trail
│
├── data/
│   ├── adversarial_note_ids.txt      # Line-delimited IDs of 18 synthetic adversarial test notes
│   └── claims.db                     # Deterministic synthetic claims SQLite database
│
├── docs/
│   ├── EXPLAIN-PLAIN-ENGLISH.md      # Plain-English guide for queries, architecture, and defenses
│   ├── decisions.md                  # Comprehensive architectural decision records (D1–D14)
│   └── mcp_sdk_notes.md              # Verified empirical probe results for MCP Python SDK v2
│
├── scripts/
│   ├── demo_client.py                # Live HTTP client testing all 5 tools and adversarial notes
│   ├── make_key.py                   # Secure CLI generating SHA-256 hashed API keys
│   ├── probe_sdk.py                  # Standalone probe verifying MCP SDK v2 capabilities
│   └── seed_db.py                    # Deterministic synthetic database seeder (Random seed 42)
│
├── src/
│   └── claims_mcp/
│       ├── __init__.py               # Package root exports
│       ├── __main__.py               # CLI entrypoint supporting --transport stdio|http
│       ├── audit.py                  # Fail-closed append-only JSONL & stderr audit logger
│       ├── config.py                 # Startup environment validation (S10)
│       ├── db.py                     # Read-only SQLite connection layer behind authorizer (S1)
│       ├── models.py                 # Pydantic input models, ID regex, and SPEC 8 error taxonomy
│       ├── queries.py                # 5 strictly parameterized SQL queries using ? placeholders
│       ├── security.py               # KeyStore, rate limiting, and untrusted text sanitization (S4-S7)
│       └── server.py                 # MCPServer pipeline, S13 interceptor, and tool registrations
│
└── tests/
    ├── __init__.py                   # Test suite package marker
    ├── fixtures.py                   # Tiny deterministic in-memory fixture database builder
    ├── test_audit.py                 # Tests verifying fail-closed audit logging and payload omission
    ├── test_config.py                # Tests verifying startup configuration refusals (S10)
    ├── test_db_readonly.py           # Tests proving write operations fail against SQLite authorizer (S1)
    ├── test_injection.py             # 40+ parameterized tests verifying hostile abuse rejection
    ├── test_queries.py               # Tests validating query outputs and AST check for ? placeholders
    ├── test_s13_server.py            # Tests verifying pre-SDK input interception and no input echo (S13)
    ├── test_security.py              # Tests verifying constant-time auth, allowlists, and sanitization
    ├── test_seed_fixture.py          # Tests verifying deterministic synthetic DB row counts and CHECKs
    ├── test_server_protocol.py       # Full protocol tests through real MCP Client (tools, errors, HTTP)
    ├── test_smoke.py                 # Basic package import smoke test
    └── test_validation.py            # Comprehensive parameter validation tables for scalars and limits