flowchart TD
    subgraph Clients["AI Clients & Interfaces"]
        C1["Claude Desktop"]
        C2["Claude Code CLI"]
        C3["Google Antigravity"]
        C4["ChatGPT / Custom App"]
    end

    subgraph Gateway["🛡️ MCP-Gatekeeper (FastMCP Cloud)"]
        direction TB
        S["FastMCP Server\nserver.py"]
        
        subgraph Engine["Security & Policy Engines"]
            B["Schema Baseline Manager\n(Rug-Pull Detector)"]
            SSRF["SSRF Validator\n(Private IP / Metadata Shield)"]
            POL["Policy Engine\n(Allow/Block/Confirm/Rate-Limit)"]
            CONF["Confirmation Manager\n(Auth-Gated Approval)"]
            
            subgraph Classifier["Two-Stage Response Classifier"]
                R1["Stage 1: Rule Prefilter\n(Fast Pattern Match)"]
                R2["Stage 2: LLM Classifier\n(OpenAI / Grok / DeepSeek / Ollama)"]
            end
        end

        UI["Admin Control Center UI\n/dashboard?admin_key=..."]
    end

    subgraph External["Upstream Services & AI APIs"]
        UP["Upstream MCP Servers\n(GitHub, SQL, Web Search, APIs)"]
        LLM["LLM Classifier API\n(Groq / OpenAI / DeepSeek / Ollama)"]
    end

    subgraph Storage["Datastore & Audit"]
        DB[("SQLite DB (tempdir dynamic)")]
        AUDIT[("Tamper-Evident Audit Log\n(SHA-256 Hash Chained)")]
    end

    Clients -->|MCP SSE / stdio / JSON-RPC| S
    S --> SSRF
    S --> B
    S --> POL
    POL -->|Held Action| CONF
    POL -->|Allowed| UP
    UP -->|Tool Response| Classifier
    Classifier --> R1
    R1 -->|Ambiguous / Suspicious| R2
    R2 -->|API Query| LLM
    Classifier -->|Clean / Safe| Clients
    Classifier -->|Malicious / Timeout| Block["Fail-Closed Block Response"]

    UI -->|Manage Policies & Baselines| DB
    Engine -->|Record Calls & Incidents| DB
    Engine -->|Write Chain Record| AUDIT

sequenceDiagram
    autonumber
    actor Client as AI Agent Client
    participant FastMCP as FastMCP Server (server.py)
    participant SSRF as SSRF & URL Shield
    participant Base as Schema Baseline Manager
    participant Policy as Policy Engine
    participant Gate as Human Confirmation Gate
    participant Admin as Admin Dashboard (/dashboard)
    participant Upstream as Upstream MCP Server
    participant Stage1 as Stage 1: Rule Prefilter
    participant Stage2 as Stage 2: LLM Classifier
    participant Audit as SHA-256 Audit Log

    Client->>FastMCP: 1. Request check_tool_security / register_upstream
    FastMCP->>SSRF: 2. Validate URL safety (Block Private/Metadata IPs)
    alt Invalid Scheme or SSRF IP Target
        SSRF-->>FastMCP: SSRF Risk Detected
        FastMCP-->>Client: Return Error: Upstream URL rejected
    end
    
    FastMCP->>Base: 3. Check tool baseline schema status
    alt Schema modified or unapproved (Rug-Pull)
        Base-->>FastMCP: Flagged schema mismatch
        FastMCP->>Audit: Log Rug-Pull Incident
        FastMCP-->>Client: Return Error: Tool schema unapproved
    else Approved Baseline
        Base-->>FastMCP: Baseline OK
    end

    FastMCP->>Policy: 4. Evaluate Call Policy
    alt Policy = Blocked / Rate-Limited
        Policy-->>FastMCP: Action Blocked
        FastMCP-->>Client: Return Error: Blocked by security policy
    else Policy = Held for Confirmation
        Policy->>Gate: 5. Create Pending Approval Request
        Gate->>Admin: Notify Admin on Dashboard
        Admin->>Gate: 6. Admin Approves / Denies (with admin_key)
        alt Denied, Missing Key, or Timed Out (Fail-Closed)
            Gate-->>FastMCP: Action Denied
            FastMCP-->>Client: Return Error: High-risk action denied
        else Approved
            Gate-->>FastMCP: Action Approved
        end
    end

    FastMCP->>Stage1: 7. Scan Response (Stage 1 Rule Prefilter)
    alt Stage 1 Matches Known Attack Vector
        Stage1-->>FastMCP: Verdict: Malicious
        FastMCP->>Audit: Record Security Incident & Audit Log
        FastMCP-->>Client: Return Safe Error: Response blocked
    else Stage 1 Suspicious / Ambiguous
        FastMCP->>Stage2: 8. Escalate to Stage 2 LLM Classifier
        Stage2-->>FastMCP: Verdict & Reason (or Fail-Closed on Error)
        alt Verdict = Malicious / Error
            FastMCP->>Audit: Record Security Incident & Audit Log
            FastMCP-->>Client: Return Safe Error: Response blocked
        else Verdict = Clean
            FastMCP->>Audit: Write Hash-Chained Audit Entry
            FastMCP-->>Client: 9. Return Verified Clean Response
        end
    else Stage 1 Clean
        FastMCP->>Audit: Write Hash-Chained Audit Entry
        FastMCP-->>Client: 9. Return Verified Clean Response
    end

# LLM Security Classifier API Key (Supports Groq, OpenAI, DeepSeek, Ollama)
LLM_API_KEY="your-llm-api-key-here"
LLM_API_URL="https://api.groq.com/openai/v1/chat/completions"
LLM_MODEL="allam-2-7b"

ADMIN_API_KEY="trust-gateway-admin-key-secret"
DATABASE_URL="sqlite+aiosqlite:///mcp_trust_gateway.db"
FAIL_CLOSED=true
CLASSIFIER_TIMEOUT_SECONDS=10.0
CONFIRMATION_TIMEOUT_SECONDS=60

{
  "mcpServers": {
    "mcp-gatekeeper": {
      "url": "https://mcp-gatekeeper-1.fastmcp.app/mcp"
    }
  }
}

claude mcp add mcp-gatekeeper --transport sse \
  https://mcp-gatekeeper-1.fastmcp.app/mcp

.venv/bin/pytest -v