# Jana MCP Server
**MCP Server for Jana Environmental Data Platform**
A Model Context Protocol (MCP) server that provides natural language access to environmental data including air quality measurements, greenhouse gas emissions, and facility data.
## Features
- **Air Quality Data** — Query PM2.5, PM10, O3, NO2, SO2, CO measurements from OpenAQ
- **Emissions Data** — Access facility-level and national GHG emissions from Climate TRACE and EDGAR
- **Geographic Search** — Find environmental data by bounding box, point + radius, or country
- **Trend Analysis** — Analyze temporal patterns in environmental data
- **System Health** — Monitor platform status and data availability
## Architecture
This MCP server runs as a hosted HTTP service using FastAPI with SSE (Server-Sent Events) transport. It communicates with the Jana backend API for data access.
```
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ MCP Client │ │ Jana MCP Server │ │ Jana Backend │
│ (Cursor/Claude) │────▶│ (FastAPI + SSE) │────▶│ (Django + DRF) │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
```
## Quick Start
### Prerequisites
- Docker and Docker Compose
- Running Jana backend (see [Jana repository](../Jana))
### 1. Configure Environment
Copy the example environment file and configure:
```bash
cp dotenv.example .env
```
Edit `.env` with your Jana backend credentials:
```bash
JANA_BACKEND_URL=http://host.docker.internal:8000
JANA_USERNAME=your_username
JANA_PASSWORD=your_password
```
### 2. Start the Server
**Standalone mode** (Jana backend running on host):
```bash
docker-compose up --build
```
**With Jana stack** (same Docker network):
```bash
# First, start Jana backend
cd ../Jana
docker-compose up -d
# Then start MCP server with override
cd ../jana-mcp-server
docker-compose -f docker-compose.yml -f docker-compose.override.yml up --build
```
The MCP server will be available at `http://localhost:8080`.
### 3. Configure Your MCP Client
Add to your Cursor or Claude Code MCP configuration:
```json
{
"mcpServers": {
"jana": {
"url": "http://localhost:8080/sse"
}
}
}
```
## Available Tools
| Tool | Description | Priority |
|------|-------------|----------|
| `get_air_quality` | Query air quality measurements | P0 |
| `get_emissions` | Query GHG emissions data | P0 |
| `find_nearby` | Proximity-based search | P0 |
| `get_trends` | Temporal trend analysis | P1 |
| `get_data_summary` | Platform data summary | P1 |
| `get_system_health` | Service status check | P2 |
## Development
### Docker Development (Recommended)
The Docker setup includes **live code reload** - code changes are immediately reflected without rebuilding the container.
```bash
# Start with live reload (standalone mode)
docker-compose up
# Or with Jana stack
docker-compose -f docker-compose.yml -f docker-compose.override.yml up
```
**How it works:**
- Volume mount: `./src:/app/src` maps local code into container
- Uvicorn `--reload` flag watches for changes and auto-restarts
- No container rebuild needed for Python code changes
**When to rebuild:**
- Changes to `pyproject.toml` (new dependencies)
- Changes to `Dockerfile`
- System-level changes
```bash
docker-compose up --build
```
### Local Development (without Docker)
```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e ".[dev]"
# Run server with auto-reload
uvicorn jana_mcp.app:app --reload --port 8080
```
### Running Tests
```bash
pytest
# With coverage
pytest --cov=jana_mcp --cov-report=html
```
### Code Quality
```bash
# Linting
ruff check .
# Type checking
mypy src/
```
### Production Deployment
For production, use the production compose file (no live reload, optimized):
```bash
docker-compose -f docker-compose.prod.yml up -d
```
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Server information |
| `/health` | GET | Health check |
| `/sse` | GET | SSE connection for MCP |
| `/messages` | POST | MCP message handling |
## Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| `JANA_BACKEND_URL` | Jana backend URL | `http://web:8000` |
| `JANA_USERNAME` | Auth username | (required) |
| `JANA_PASSWORD` | Auth password | (required) |
| `JANA_TOKEN` | Pre-configured token | (optional) |
| `MCP_SERVER_PORT` | Server port | `8080` |
| `LOG_LEVEL` | Logging level | `INFO` |
## Known Limitations
- **`get_data_summary` may timeout** — The backend summary endpoint aggregates data across 300M+ records which can exceed timeout limits. The tool gracefully returns partial results with available source information when this occurs.
## Documentation
- [User Manual](docs/USER_MANUAL.md) — How to connect and use the MCP server
- [Architecture](docs/design/ARCHITECTURE.md)
- [Requirements](docs/design/REQUIREMENTS.md)
- [Architecture Decision Records](docs/design/adr/)
## License
MIT
