flowchart LR
    subgraph CLIENTS["👤 Client Layer"]
        LLM["🤖 LLM / AI Agent"]
        Browser["🌐 User Browser"]
    end

    subgraph MCP_SERVER["⚙️ MCP Server Pipeline"]
        direction TB
        Transport["Transport Layer<br/>/mcp · /sse · /http"]
        Middleware["Custom Middleware<br/>Session Injection · SSE Streams"]
        Core["FastMCP Core<br/>Protocol Handler · Tool Registry"]
        Tools["Tools Engine<br/>Modular Tool Execution"]
    end

    subgraph STATE["💾 State Layer"]
        Redis[("Redis<br/>Sessions · Auth · Tokens")]
    end

    subgraph EXTERNAL["🌍 External Services"]
        IDP["Identity Provider"]
        API["Upstream APIs"]
    end

    LLM -->|"MCP Request"| Transport
    Transport --> Middleware
    Middleware -->|"Read / Write"| Redis
    Middleware --> Core
    Core --> Tools
    Tools -->|"API Call"| API
    API -->|"Response"| Tools
    Tools -->|"Masked Data"| LLM
    Browser -->|"OAuth Login"| IDP
    IDP -->|"Callback + Token"| Middleware
    Middleware -->|"Store Credentials"| Redis

    style CLIENTS fill:#0d1b2a,stroke:#00b4d8,color:#e0e0e0
    style MCP_SERVER fill:#1a1a2e,stroke:#7b2ff7,color:#e0e0e0
    style STATE fill:#0d1b2a,stroke:#00c853,color:#e0e0e0
    style EXTERNAL fill:#0d1b2a,stroke:#ff6d00,color:#e0e0e0

flowchart TB
    subgraph ENTRY["🚪 Entry Points"]
        MCP_EP["/mcp<br/>Standard MCP Protocol"]
        SSE_EP["/sse<br/>Server-Sent Events"]
        HTTP_EP["/http<br/>Direct HTTP"]
    end

    subgraph MIDDLEWARE_LAYER["🛡️ Custom Middleware"]
        direction TB
        SessionInject["Session Context Injector<br/>Injects mcp_session_id into headers"]
        StreamTransport["StreamableHTTPServerTransport<br/>HTTP ↔ MCP message bridge"]
        SSEHandler["SSE Handler<br/>anyio memory streams for<br/>non-blocking read/write channels"]
    end

    subgraph CORE_LAYER["⚙️ FastMCP Core"]
        direction TB
        ProtocolHandler["Protocol Handler<br/>MCP message parsing & routing"]
        ToolRegistry["Tool Registry<br/>Dynamic tool discovery & dispatch"]
        TaskGroups["anyio Task Groups<br/>Bidirectional stream management"]
    end

    subgraph AUTH_LAYER["🔐 Security Layer"]
        direction TB
        OAuth["OAuth 2.1 Provider<br/>Authorization & Token endpoints"]
        PKCE["PKCE Enforcer<br/>S256 code challenge verification"]
        JWT["JWT Manager<br/>HS256 signed Bearer tokens"]
        Encryption["AES-CBC Encryption<br/>Sensitive config protection"]
    end

    subgraph TOOLS_LAYER["🧰 Tools Engine"]
        direction TB
        ServiceTool["Service Tool<br/>Generic modular tool"]
        Helpers["Helpers<br/>Context validation & utilities"]
    end

    subgraph STATE_LAYER["💾 Redis State"]
        direction TB
        SessionStore[("Session Store<br/>JSON objects via RedisJSON<br/>1-hour TTL")]
        AuthCodes[("Auth Codes<br/>Short-lived, 10-min TTL")]
        TokenMeta[("Token Metadata<br/>JTI for revocation checks")]
    end

    MCP_EP & SSE_EP & HTTP_EP --> SessionInject
    SessionInject --> StreamTransport
    StreamTransport --> SSEHandler
    SSEHandler --> ProtocolHandler
    ProtocolHandler --> ToolRegistry
    ToolRegistry --> TaskGroups
    TaskGroups --> ServiceTool
    ServiceTool --> Helpers

    SessionInject -.->|"Read/Write"| SessionStore
    OAuth -.->|"Store"| AuthCodes
    JWT -.->|"Store JTI"| TokenMeta
    StreamTransport -.-> OAuth
    OAuth --> PKCE
    PKCE --> JWT

    style ENTRY fill:#112240,stroke:#64ffda,color:#ccd6f6
    style MIDDLEWARE_LAYER fill:#112240,stroke:#7b2ff7,color:#ccd6f6
    style CORE_LAYER fill:#112240,stroke:#00b4d8,color:#ccd6f6
    style AUTH_LAYER fill:#112240,stroke:#f44336,color:#ccd6f6
    style TOOLS_LAYER fill:#112240,stroke:#ff9800,color:#ccd6f6
    style STATE_LAYER fill:#112240,stroke:#00c853,color:#ccd6f6

sequenceDiagram
    participant LLM as 🤖 LLM / AI Agent
    participant MCP as ⚙️ MCP Server
    participant Redis as 💾 Redis
    participant Browser as 🌐 User Browser
    participant IDP as 🔑 Identity Provider
    participant API as 🌍 Upstream API

    Note over LLM,API: Phase 1 — Session Establishment
    LLM->>MCP: Connect via /mcp, /sse, or /http
    MCP->>Redis: Create session (JSON, 1hr TTL)
    Redis-->>MCP: session_id
    MCP-->>LLM: Connection established

    Note over LLM,API: Phase 2 — Authentication
    LLM->>MCP: Call "login" tool
    MCP-->>LLM: Return Auth URL
    LLM-->>Browser: Display Auth URL to user
    Browser->>IDP: User authenticates
    IDP->>MCP: Redirect callback with token
    MCP->>Redis: Store credentials → session_id
    Redis-->>MCP: OK
    MCP-->>Browser: "Login successful" page

    Note over LLM,API: Phase 3 — Authenticated Tool Execution
    LLM->>MCP: Call tool (e.g., "service")
    MCP->>Redis: Validate session + load credentials
    Redis-->>MCP: Session data + credentials
    MCP->>API: Authenticated API request
    API-->>MCP: Response data
    MCP-->>LLM: Masked / formatted result

model-context-protocol/
├── src/
│   ├── main.py                 # Application entry point & tool registration
│   ├── config.py               # Environment loading & configuration constants
│   ├── auth/
│   │   ├── oauth.py            # OAuth 2.1 authorization server (PKCE)
│   │   └── token.py            # JWT token issuance & validation
│   ├── conn/
│   │   └── redis_config.py     # Redis client initialization
│   ├── encryptdecrypt/
│   │   └── encrypt.py          # AES-CBC encryption / decryption utilities
│   ├── exception/
│   │   └── handler.py          # Global exception handling
│   ├── log/
│   │   └── logger.py           # Structured logging configuration
│   ├── middleware/
│   │   └── middleware.py        # Custom middleware (session injection, SSE, transport)
│   ├── server/
│   │   └── server.py           # Starlette app factory & route definitions
│   ├── session/
│   │   ├── manager.py          # Session lifecycle management (Redis)
│   │   └── session.py          # Session model & validation
│   ├── tools/
│   │   └── service.py          # Modular tool definitions
│   └── utils/
│       └── helpers.py          # Context validation & utility functions
├── docs/
│   └── architecture_diagram.png
├── test/                       # Unit & integration tests
├── .env                        # Environment variables (not committed)
├── Dockerfile                  # Container image definition
├── pyproject.toml              # Pytest & coverage configuration
├── requirements.txt            # Python dependencies
└── LICENSE                     # MIT License

git clone https://github.com/shubhamauti9/model-context-protocol.git
cd model-context-protocol

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows

pip install -r requirements.txt

# ── App ──────────────────────────────────
MASK_MCP_HOST=0.0.0.0
MASK_MCP_PORT=6901
APP_VERSION=1.0.0

# ── Redis ────────────────────────────────
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_P=                         # Redis password (leave blank for local)
REDIS_DB=0

# ── Encryption ───────────────────────────
ENCRYPTION_KEY=your-32-byte-key
ENCRYPTION_IV=your-16-byte-iv

# ── Logging ──────────────────────────────
LOG_FILE=logs/mcp.log

# Using Docker
docker run -d --name redis -p 6379:6379 redis:7-alpine

# Or install natively 
visit https://redis.io/docs/getting-started/

python src/main.py

curl http://localhost:6901/mcp

docker build -t mcp:1.0.0 .

docker run -d \
  --name mcp-server \
  -p 6901:6901 \
  --env-file .env \
  mcp:1.0.0

version: "3.9"
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  mcp:
    build: .
    ports:
      - "6901:6901"
    depends_on:
      - redis
    env_file:
      - .env

{
  "mcpServers": {
    "mcp": {
      "command": "python",
      "args": ["/path/to/model-context-protocol/src/main.py"]
    }
  }
}

# Connect over HTTP
curl -X POST http://localhost:6901/http \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "service"}}'

# Open an SSE stream
curl -N http://localhost:6901/sse?session_id=<your-session-id>

┌─────────────┐     ┌──────────────┐      ┌──────────────┐     ┌─────────────┐
│   CONNECT   │────▶│   ANONYMOUS  │────▶│ AUTHENTICATED│────▶│   EXPIRED   │
│             │     │  Session in  │      │ Credentials  │     │  TTL reached│
│  /mcp /sse  │     │  Redis (1hr) │      │ stored in    │     │  or manual  │
│  /http      │     │              │      │  Redis       │     │  logout     │
└─────────────┘     └──────────────┘      └──────────────┘     └─────────────┘