# UNHCR Open Data Gateway MCP

A FastMCP-based gateway that aggregates and normalizes data from UNHCR's domain-specific MCP servers.

## 🎯 Purpose

The UNHCR Open Data Gateway MCP provides a unified interface for accessing UNHCR's open data across three independent MCP servers:

- **Statistics MCP**: Authoritative source for population and displacement data
- **RDF MCP**: Authoritative source for socio-economic indicators and contextual datasets  
- **IATI MCP**: Authoritative source for budget, contributions, and financial transparency data

## 🏗️ Architecture

The gateway follows a **Federated Gateway Pattern**:

```
                    AI Client
                         |
                         v

            +----------------------+
            |  Open Data Gateway   |
            |       FastMCP        |
            +----------------------+

                 /      |      \

                /       |       \

               v        v        v

        +---------+ +---------+ +---------+
        | Stat    | | RDF     | | IATI    |
        | MCP     | | MCP     | | MCP     |
        +---------+ +---------+ +---------+

                   ^
                   |
                   |
          Reference Layer
          (Canonical Entities)
```

### Core Principles

1. **Domain MCP Ownership**: Each domain MCP owns its data
2. **Gateway Owns Experience**: Gateway handles aggregation, composition, discovery, analytics
3. **Domain MCP Independence**: Domain MCPs never call each other directly
4. **Canonical Reference Layer**: Prevents duplication of country/operation definitions

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd unhcr-opendata-gateway-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Configuration

Create a `.env` file:

```env
STAT_MCP_ENDPOINT=http://localhost:8001
RDF_MCP_ENDPOINT=http://localhost:8002
IATI_MCP_ENDPOINT=http://localhost:8003
LOG_LEVEL=INFO
```

### Running the Server

```bash
# Run in STDIO mode
python -m src.unhcr_opendata_gateway.app
```

## 🛠️ Usage

### Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `country_snapshot` | Comprehensive snapshot for a country | `country`, `year` |
| `operation_snapshot` | Comprehensive snapshot for an operation | `operation`, `year` |
| `funding_gap_analysis` | Calculate funding gap and per-refugee metrics | `country`, `year` |
| `funding_per_refugee` | Calculate funding metrics per refugee | `country`, `year` |
| `compare_countries` | Compare two countries across all domains | `country_a`, `country_b`, `year` |
| `search_datasets` | Search datasets across all MCPs | `query`, `country`, `region`, `topic`, `dataset` |
| `list_all_datasets` | List all available datasets | - |
| `generate_country_brief` | Generate a comprehensive briefing note | `country`, `year` |

### Example Queries

```python
# Get a country snapshot
result = await country_snapshot(country="Uganda", year=2023)

# Calculate funding gap
result = await funding_gap_analysis(country="Chad", year=2023)

# Compare two countries
result = await compare_countries(country_a="Uganda", country_b="Kenya", year=2023)

# Generate a briefing note
result = await generate_country_brief(country="Sudan", year=2023)
```

## 📊 Features

- **Country Normalization**: Handles ISO3, ISO2, names, aliases, "Republic of X" variants
- **Cross-Domain Analytics**: Funding gap per refugee, budget per refugee, etc.
- **Graceful Degradation**: Returns partial data when some MCPs are unavailable
- **Caching**: TTL-based caching with configurable expiration
- **Observability**: Structured logging, metrics, OpenTelemetry tracing

## 📄 License

Apache License 2.0

## 🙏 Support

For issues or questions, please contact the UNHCR Data team.