MCP Client (Claude Desktop, custom clients)
    │
    │ JSON-RPC 2.0 over stdio
    ▼
┌─────────────────────────────────────────────────┐
│  MCP Server (FastMCP)                           │
│  ├── query_dataset — NL query against dataset    │
│  ├── aggregate_data — count/sum/avg/min/max     │
│  ├── search_similar — vector similarity search   │
│  ├── list_collections — available data sources   │
│  ├── describe_collection — schema inspection      │
│  └── export_data — CSV/JSON export               │
│                                                 │
│  Agents: Query Understanding → Retrieval → NL    │
└─────────────────────────────────────────────────┘
    │
    │ httpx (mock in PoC, real API in production)
    ▼
Client Internal API

# 1. Clone and install
git clone https://github.com/9KMan/JOB-20260613144931-000091.git
cd JOB-20260613144931-000091
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Configure (edit config.yaml)
cp config.yaml config.local.yaml

# 3. Run
python -m mcp_server.main

# 4. Test
curl http://localhost:8000/health

# 5. Run tests
pytest tests/ -v

docker compose up --build
curl http://localhost:8000/health

src/mcp_server/
├── __init__.py          # Package entry
├── __version__.py       # Version
├── config.py            # Settings management
├── database.py          # ORM models (SQLAlchemy async)
├── cache.py             # In-memory TTL cache
├── main.py              # FastMCP server + REST endpoints
└── agents/
    ├── query_understanding.py   # Intent classification
    ├── data_retrieval.py        # API client (mock in PoC)
    └── response_synthesis.py    # NL response generation