# Jana MCP Server - Requirements Document
**Version:** 1.0
**Date:** 2026-01-22
**Status:** Draft
---
## 1. Overview
### 1.1 Purpose
The Jana MCP Server provides a natural language interface to Jana's environmental data platform, enabling users to query air quality measurements, greenhouse gas emissions, and environmental analytics through MCP-compatible clients like Cursor and Claude Code.
### 1.2 Scope
This document defines requirements for the MVP release of the Jana MCP Server.
### 1.3 Target Users
- **Researchers** — Environmental scientists analyzing pollution and emissions data
- **Analysts** — ESG and sustainability analysts evaluating environmental metrics
- **Developers** — Engineers building applications that consume environmental data
---
## 2. Functional Requirements
### 2.1 Data Access
#### 2.1.1 Air Quality Queries
| ID | Requirement |
|----|-------------|
| DA-001 | The system shall retrieve air quality measurements from OpenAQ data |
| DA-002 | The system shall support filtering by pollutant parameters (PM2.5, PM10, O3, NO2, SO2, CO) |
| DA-003 | The system shall return measurement values with units, timestamps, and location information |
#### 2.1.2 Emissions Queries
| ID | Requirement |
|----|-------------|
| DA-004 | The system shall retrieve GHG emissions data from Climate TRACE |
| DA-005 | The system shall retrieve national emissions data from EDGAR |
| DA-006 | The system shall support filtering by sector (power, steel, cement, etc.) |
| DA-007 | The system shall support filtering by gas type (CO2, CH4, N2O) |
#### 2.1.3 Geographic Filtering
| ID | Requirement |
|----|-------------|
| DA-008 | The system shall support bounding box queries (min_lon, min_lat, max_lon, max_lat) |
| DA-009 | The system shall support point + radius queries (longitude, latitude, radius_km) |
| DA-010 | The system shall support country code filtering (ISO-3 codes) |
#### 2.1.4 Temporal Filtering
| ID | Requirement |
|----|-------------|
| DA-011 | The system shall support date range filtering (date_from, date_to) |
| DA-012 | The system shall support temporal aggregations (hourly, daily, monthly) |
#### 2.1.5 Cross-Source Queries
| ID | Requirement |
|----|-------------|
| DA-013 | The system shall support unified queries across multiple data sources |
| DA-014 | The system shall return data with proper source attribution |
### 2.2 Analytics
| ID | Requirement |
|----|-------------|
| AN-001 | The system shall provide trend analysis for time-series data |
| AN-002 | The system shall provide correlation analysis between air quality and emissions |
| AN-003 | The system shall provide data quality insights (freshness, coverage) |
### 2.3 Administrative
| ID | Requirement |
|----|-------------|
| AD-001 | The system shall provide platform summary information (data coverage, record counts) |
| AD-002 | The system shall provide system health status |
---
## 3. Non-Functional Requirements
### 3.1 Architecture
| ID | Requirement |
|----|-------------|
| NF-001 | The system shall be stateless (no server-side session storage) |
| NF-002 | The system shall delegate data operations to the Jana backend via eko-client-python |
| NF-003 | The system shall not generate or execute SQL queries directly |
| NF-004 | The system shall use SSE (Server-Sent Events) transport for MCP protocol |
| NF-005 | The system shall be implemented as a hosted HTTP service using FastAPI |
### 3.2 Infrastructure
| ID | Requirement |
|----|-------------|
| IF-001 | The system shall be containerized using Docker |
| IF-002 | The system shall be deployable via docker-compose alongside Jana backend |
| IF-003 | The system shall be deployable to AWS container services (ECS, Fargate) |
| IF-004 | The system shall expose an HTTP endpoint for SSE connections |
| IF-005 | The system shall expose a health check endpoint at `/health` |
| IF-006 | The system shall communicate with Jana backend via internal Docker/VPC network |
### 3.3 Integration
| ID | Requirement |
|----|-------------|
| IN-001 | The system shall implement the Model Context Protocol (MCP) specification |
| IN-002 | The system shall be compatible with Cursor IDE |
| IN-003 | The system shall be compatible with Claude Code |
| IN-004 | The system shall connect to Jana backend at configurable URL (default: `http://web:8000` in Docker) |
| IN-005 | The system shall expose MCP SSE endpoint at `/sse` |
| IN-006 | The system shall expose MCP messages endpoint at `/messages` |
### 3.4 Authentication
| ID | Requirement |
|----|-------------|
| AU-001 | The system shall authenticate with Jana backend using token-based authentication |
| AU-002 | The system shall support credential configuration via environment variables |
| AU-003 | The system shall support pre-configured auth tokens as alternative to username/password |
### 3.5 Performance
| ID | Requirement |
|----|-------------|
| PF-001 | The system shall respond to tool calls within backend API response time + 500ms overhead |
| PF-002 | The system shall handle backend rate limits gracefully (1000 requests/hour for authenticated users) |
| PF-003 | The system shall maintain SSE connections efficiently |
### 3.6 Error Handling
| ID | Requirement |
|----|-------------|
| EH-001 | The system shall return meaningful error messages for failed API calls |
| EH-002 | The system shall handle network errors and timeouts gracefully |
| EH-003 | The system shall handle authentication failures with clear error messages |
| EH-004 | The system shall handle SSE connection drops and support reconnection |
---
## 4. MCP Tools Specification
### 4.1 Tool Inventory
| Tool Name | Purpose | 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_correlations` | Cross-source correlation analysis | P1 |
| `get_data_summary` | Platform overview | P1 |
| `get_system_health` | Service status | P2 |
### 4.2 Tool Parameters
#### `get_air_quality`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `location_bbox` | array | No* | Bounding box [min_lon, min_lat, max_lon, max_lat] |
| `location_point` | array | No* | Point coordinates [lon, lat] |
| `radius_km` | number | No | Search radius (requires location_point) |
| `country_codes` | array | No* | ISO-3 country codes |
| `parameters` | array | No | Pollutant codes (pm25, o3, etc.) |
| `date_from` | string | No | Start date (ISO 8601) |
| `date_to` | string | No | End date (ISO 8601) |
| `limit` | integer | No | Max results (default: 100) |
*At least one location filter required
#### `get_emissions`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sources` | array | No | Data sources: climatetrace, edgar |
| `location_bbox` | array | No* | Bounding box |
| `location_point` | array | No* | Point coordinates |
| `radius_km` | number | No | Search radius |
| `country_codes` | array | No* | ISO-3 country codes |
| `sectors` | array | No | Sector filter |
| `date_from` | string | No | Start date |
| `date_to` | string | No | End date |
| `limit` | integer | No | Max results |
#### `find_nearby`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `location_point` | array | Yes | Point coordinates [lon, lat] |
| `radius_km` | number | Yes | Search radius |
| `sources` | array | No | Data sources to search |
| `limit` | integer | No | Max results |
#### `get_trends`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | string | Yes | Data source |
| `parameter` | string | Yes | Parameter to analyze |
| `location_bbox` | array | No | Geographic filter |
| `country_codes` | array | No | Country filter |
| `date_from` | string | No | Start date |
| `date_to` | string | No | End date |
| `temporal_resolution` | string | No | daily, weekly, monthly |
#### `get_correlations`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sources` | array | Yes | At least 2 sources required |
| `location_bbox` | array | No | Geographic filter |
| `date_from` | string | No | Start date |
| `date_to` | string | No | End date |
#### `get_data_summary`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | - | - | Returns platform-wide summary |
#### `get_system_health`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| (none) | - | - | Returns system health status |
---
## 5. Out of Scope (MVP)
The following capabilities are explicitly excluded from MVP:
| Capability | Reason | Reference |
|------------|--------|-----------|
| Server-side session/memory | Clients manage conversation context | ADR-0001 |
| SQL query generation | Security and complexity concerns | ADR-0002 |
| Regulatory thresholds/knowledge | Maintenance burden, scope creep | ADR-0003 |
| Data caching beyond backend | Keep MCP server stateless | ADR-0001 |
| Job management/admin tools | Focus on data access for MVP | Scope |
---
## 6. Dependencies
### 6.1 External Systems
| System | Purpose | Required |
|--------|---------|----------|
| Jana Backend | Data source | Yes |
| eko-client-python | API client library | Yes |
### 6.2 Development Dependencies
| Component | Purpose |
|-----------|---------|
| Python 3.11+ | Runtime |
| MCP Python SDK | Protocol implementation |
| FastAPI | HTTP framework |
| uvicorn | ASGI server |
| httpx | HTTP client (via eko-client) |
| pydantic | Data validation |
| starlette-sse | SSE support |
### 6.3 Infrastructure Dependencies
| Component | Purpose |
|-----------|---------|
| Docker | Containerization |
| docker-compose | Local orchestration |
| Jana backend stack | Data source (must be running) |
---
## 7. Configuration
### 7.1 Required Configuration
| Setting | Description | Default |
|---------|-------------|---------|
| `JANA_BACKEND_URL` | Backend API base URL | `http://web:8000` (Docker) |
| `JANA_USERNAME` | Authentication username | (none) |
| `JANA_PASSWORD` | Authentication password | (none) |
### 7.2 Server Configuration
| Setting | Description | Default |
|---------|-------------|---------|
| `MCP_SERVER_HOST` | Server bind address | `0.0.0.0` |
| `MCP_SERVER_PORT` | Server port | `8080` |
| `LOG_LEVEL` | Logging level | `INFO` |
### 7.3 Optional Configuration
| Setting | Description | Default |
|---------|-------------|---------|
| `JANA_TOKEN` | Pre-obtained auth token | (none) |
| `JANA_TIMEOUT` | Request timeout (seconds) | 30 |
### 7.4 Docker Deployment
| Environment | Backend URL | MCP Server URL |
|-------------|-------------|----------------|
| Local (docker-compose) | `http://web:8000` | `http://localhost:8080` |
| Production (AWS) | `http://jana-backend:8000` | `https://mcp.jana.example.com` |
---
## 8. Success Criteria
### 8.1 MVP Completion
- [ ] All P0 tools implemented and functional
- [ ] Docker container builds and runs successfully
- [ ] docker-compose integration with Jana backend works
- [ ] SSE transport functional with MCP clients
- [ ] Successful connection to Jana backend via Docker network
- [ ] Compatible with Cursor IDE
- [ ] Basic error handling implemented
- [ ] Health check endpoint operational
- [ ] Documentation complete
### 8.2 Acceptance Tests
| Test | Description |
|------|-------------|
| AT-001 | Query PM2.5 data for a specific city |
| AT-002 | Query emissions for a country |
| AT-003 | Find facilities near a geographic point |
| AT-004 | Get trend analysis for a parameter |
| AT-005 | Handle authentication failure gracefully |
| AT-006 | Handle network timeout gracefully |
---
## 9. Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-22 | Architecture Team | Initial draft |
| 1.1 | 2026-01-22 | Architecture Team | Added infrastructure, SSE transport, and Docker requirements (ADR-0004) |
