sequenceDiagram
    autonumber
    actor User
    participant LLM as Claude Desktop / AI Client
    participant MCP as Pune Transit MCP Server (Python)
    participant Engine as Transit Services & SQLite Engine
    participant Metro as Metro JSON & OpenStreetMap

    User->>LLM: "Best way from Pimpri to Hinjewadi Phase 3 leaving at 8:30 AM?"
    Note over LLM: Model recognizes transit intent & inspects MCP tools
    LLM->>MCP: call_tool("plan_trip", {origin: "Pimpri", destination: "Hinjewadi Phase 3", depart_at: "08:30"})
    MCP->>Engine: resolve_place() & query SQLite GTFS schedules
    Engine->>Metro: check metro connections & walking distances
    Metro-->>Engine: itineraries calculated & ranked
    Engine-->>MCP: Structured itinerary JSON (legs, transfers, durations, fares)
    MCP-->>LLM: Return ToolResult JSON with provenance & timestamp
    LLM-->>User: Answers with concrete bus routes (e.g., Route 348), exact timings, stop names, and fare!

graph TB
    subgraph Clients["Clients & Consumers"]
        CD["Claude Desktop (Stdio)"]
        Browser["Modern Web UI (Browser)"]
        Agent["Autonomous AI Agent (HTTP /mcp)"]
    end

    subgraph TransportLayer["Transport & Security Layer"]
        STDIO["Stdio JSON-RPC Handler"]
        HTTP["Starlette / Uvicorn ASGI Server"]
        AUTH["Bearer Auth & Tenant Resolver<br/>(secrets.compare_digest)"]
        CORS["CORS Middleware"]
    end

    subgraph MCPLayer["MCP Protocol Engine (mcp SDK)"]
        TOOLS["Tools Registry (8 Tools)<br/>• plan_trip • resolve_place<br/>• next_departures • metro_info<br/>• find_nearby_stops • find_routes_between<br/>• save_place • list_saved_places"]
        RES["Resources (4 URI Schemes)<br/>• transit://pune/routes<br/>• transit://pune/stops/{id}<br/>• transit://pune/metro<br/>• transit://user/places"]
        PROMPTS["Prompts Engine<br/>• morning_commute<br/>• explore_area"]
    end

    subgraph ServiceLayer["Domain Services Layer"]
        P_SRV["Place Resolution Service (places.py)"]
        S_SRV["Nearby Stops Service (stops.py)"]
        D_SRV["Departures Engine (departures.py)"]
        TR_SRV["Multi-Modal Trip Planner (planner.py)"]
        M_ADAPT["Metro Adapter (metro_adapter.py)"]
    end

    subgraph DataLayer["Data & Persistence Layer"]
        SQLITE[("SQLite Database<br/>pune_transit.db<br/>• Stops • Routes • Trips<br/>• StopTimes • Calendar • SavedPlaces")]
        METRO_JSON["Maha-Metro Graph<br/>(data/metro.json)"]
        PLACES_JSON["Curated Landmarks Cache<br/>(data/pune_places.json)"]
        OSM["OpenStreetMap Nominatim API<br/>(Pune Viewbox Bounded)"]
    end

    CD --> STDIO
    Agent --> AUTH --> HTTP
    Browser --> CORS --> HTTP

    STDIO --> MCPLayer
    HTTP --> MCPLayer
    HTTP -->|REST API /api/...| ServiceLayer

    MCPLayer --> ServiceLayer

    P_SRV --> PLACES_JSON
    P_SRV --> OSM
    P_SRV --> SQLITE

    S_SRV --> SQLITE
    D_SRV --> SQLITE
    TR_SRV --> SQLITE
    TR_SRV --> M_ADAPT
    M_ADAPT --> METRO_JSON

flowchart TD
    A[Client Request] --> B{Entrypoint}
    B -->|Command Line / Claude App| C[Stdio Server: src.server]
    B -->|Browser / Remote Agent| D[ASGI HTTP Server: src.http_server]
    
    D --> E{Route Matched?}
    E -->|/api/*| F[Direct REST Handlers]
    E -->|/mcp| G[MCP Auth Verification]
    E -->|/| H[Static Frontend HTML/CSS/JS]

    G -->|Valid Token| I[Streamable MCP Endpoint]
    G -->|Invalid Token| J[401 Unauthorized JSON]

    C --> K[MCP Server Instance]
    I --> K

    K --> L[Input Validation via Pydantic]
    L -->|Valid| M[Dispatch to Service Layer]
    L -->|Invalid| N[Return Structured INVALID_INPUT Error]

    M --> O[Haversine Math + SQL Range Queries]
    O --> P[Build Response Payload + Provenance Metadata]
    P --> Q[Return to Client]

git clone https://github.com/shreyashhiray16/MCP-.git
cd MCP-

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
.\venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

python scripts/ingest_gtfs.py

npm start
# or: python -m src.http_server

# Windows PowerShell:
$env:PORT=8720; npm start

# Linux/macOS:
PORT=8720 npm start

{
  "mcpServers": {
    "pune-transit": {
      "command": "python",
      "args": [
        "-m",
        "src.server"
      ],
      "cwd": "C:/Users/YOUR_USERNAME/Downloads/mcp projecty"
    }
  }
}

npx @modelcontextprotocol/inspector python -m src.server

# Build Docker image
docker build -t pune-transit-mcp .

# Run container
docker run -d -p 8000:8000 -e PORT=8000 --name pune-transit pune-transit-mcp

# Run full test suite
python -m pytest -v

# Or via npm shortcut
npm test

pune-transit-mcp/
├── .env.example                # Sample environment variables configuration
├── .gitignore                  # Git exclusions (venv, databases, caches)
├── Dockerfile                  # Container build recipe
├── LICENSE                     # MIT License
├── package.json                # npm scripts for running and testing
├── README.md                   # Comprehensive project documentation
├── requirements.txt            # Python dependencies (mcp, starlette, uvicorn, httpx, etc.)
├── data/
│   ├── metro.json              # Curated Pune Metro lines, stations, and fare rules
│   ├── pune_places.json        # Curated landmarks and aliases for instant resolution
│   ├── pune_transit.db         # SQLite database with indexed transit tables
│   └── gtfs/                   # Raw GTFS feed CSV files
├── docs/
│   ├── data-sources.md         # Data lineage, licenses, and catalog
│   ├── decisions.md            # Architecture Decision Records (ADRs)
│   └── learning-log.md         # Implementation notes and learnings
├── frontend/                   # Interactive Web UI
│   ├── index.html              # Modern dashboard layout
│   ├── style.css               # Premium CSS design system
│   └── app.js                  # Frontend logic & API client
├── scripts/
│   └── ingest_gtfs.py          # Seed GTFS generation and SQLite loader
├── src/
│   ├── __init__.py
│   ├── config.py               # Central environment and configuration settings
│   ├── http_server.py          # Unified Starlette ASGI server (Web UI + REST + /mcp)
│   ├── server.py               # Core MCP Server instance and stdio entrypoint
│   ├── adapters/
│   │   ├── geocoding.py        # Hybrid local + OSM Nominatim geocoding
│   │   ├── http_client.py      # Resilient HTTP client with retry logic
│   │   └── metro_adapter.py    # Maha-Metro operational and fare engine
│   ├── db/
│   │   ├── connection.py       # SQLite connection manager with thread safety
│   │   └── repository.py       # SQL queries for stops, routes, departures, places
│   ├── prompts/
│   │   └── transit_prompts.py  # MCP Prompts (morning_commute, explore_area)
│   ├── resources/
│   │   └── transit_resources.py# MCP Resources (transit://...)
│   ├── services/
│   │   ├── departures.py       # Timetable departure calculations
│   │   ├── places.py           # Landmark resolution and user bookmarks
│   │   ├── planner.py          # Multi-modal trip itinerary generation
│   │   └── stops.py            # Spatial stop discovery
│   └── tools/
│       └── transit_tools.py    # MCP Tool handler registrations
└── tests/
    ├── test_api.py             # REST API endpoint tests
    ├── test_departures.py      # Timetable departures tests
    ├── test_mcp_server.py      # MCP protocol contract tests
    ├── test_metro.py           # Metro fares and station tests
    ├── test_model_behaviour.py # Model guidance and structured error tests
    ├── test_places.py          # Geocoding and places tests
    ├── test_planner.py         # Multi-modal trip planning tests
    └── test_stops.py           # Nearby stops query tests