Unhcr Opendata Gateway

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

# 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:

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

Running the Server

# 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

# 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.