Deploy explorer to Hugging Face Spaces

Dockerfile

@@ -0,0 +1,58 @@
+FROM python:3.11-slim
+
+# Install system dependencies (needed for browser screenshot captures)
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    procps \
+    gnupg \
+    libnss3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libdrm2 \
+    libxkbcommon0 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libpango-1.0-0 \
+    libcairo2 \
+    libasound2 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast package management
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set working directory
+WORKDIR /app
+
+# Copy dependency configs
+COPY pyproject.toml uv.lock ./
+
+# Install python dependencies (exclude the project itself to cache dependencies)
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Install playwright browsers (for chart screenshot captures)
+RUN uv run playwright install chromium
+
+# Copy project source code
+COPY . .
+
+# Install the project itself
+RUN uv sync --frozen --no-dev
+
+# Ensure entrypoint is executable
+RUN chmod +x /app/entrypoint.sh
+
+# Expose the default Hugging Face Space port
+EXPOSE 7860
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PREFAB_BUNDLED_RENDERER=1
+
+# Run the entrypoint script
+CMD ["/app/entrypoint.sh"]

README.md

@@ -0,0 +1,39 @@
+---
+title: Data360-MCP Visualization Engine Explorer
+emoji: 📊
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Data360-MCP Visualization Engine Explorer
+
+This repository contains the deployment configuration for hosting the **Data360-MCP Visualization Engine Explorer** in Hugging Face Spaces.
+
+## 🚀 Deployment Instructions
+
+### 1. Create a Hugging Face Space
+- Go to [Hugging Face Spaces](https://huggingface.co/spaces) and click **Create new Space**.
+- Name the Space (e.g. `data360-mcp-explorer`).
+- Select **Docker** as the SDK.
+- Choose **Blank** template.
+
+### 2. Configure Repository Secrets & Environment Variables
+In your Space settings page, add the following under **Repository secrets**:
+- `OPENAI_API_KEY`: Required for natural query question framing and running vision-based chart audits.
+- `HF_TOKEN`: Your Hugging Face write access token (required to pull/push persistent data).
+
+Under **Variables**:
+- `HF_DATASET_ID`: Set to `rafmacalaba/data360-explorer-reports` (defaults to this if not set).
+
+### 3. Sync Repository Files
+Add the Hugging Face Space remote and push the branch:
+```bash
+# Add the remote and push
+git remote add space https://huggingface.co/spaces/rafmacalaba/data360-mcp-explorer
+git push space main
+```
+
+The Space will automatically build the container using the provided `Dockerfile` and boot the server on port `7860`.

deploy.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# Helper script to deploy the explorer to Hugging Face Spaces from evals/deepeval_visualization
+
+set -e
+
+# Colors for output
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+echo -e "${BLUE}=== Data360-MCP HF Space Deployment (from evals/deepeval_visualization) ===${NC}"
+
+# Navigate to the workspace root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Define paths relative to workspace root
+DEPLOY_DIR="$WORKSPACE_ROOT/evals/deepeval_visualization"
+
+# Copy source and dependency files to deploy dir to make it self-contained
+echo "Copying application files to deploy directory..."
+mkdir -p "$DEPLOY_DIR/evals"
+cp -r "$WORKSPACE_ROOT/src" "$DEPLOY_DIR/"
+cp "$WORKSPACE_ROOT/pyproject.toml" "$DEPLOY_DIR/"
+# Strip workspace and source references from the copied pyproject.toml
+python3 -c '
+with open("'"$DEPLOY_DIR"'/pyproject.toml", "r") as f:
+    lines = f.readlines()
+new_lines = []
+skip = False
+for line in lines:
+    if "[tool.uv.workspace]" in line:
+        skip = True
+        continue
+    if "[tool.uv.sources]" in line:
+        skip = True
+        continue
+    if skip and (line.startswith("[") or line.strip() == ""):
+        if line.strip().startswith("["):
+            skip = False
+        else:
+            skip = False
+            continue
+    if not skip:
+        new_lines.append(line)
+with open("'"$DEPLOY_DIR"'/pyproject.toml", "w") as f:
+    f.writelines(new_lines)
+'
+cp "$WORKSPACE_ROOT/uv.lock" "$DEPLOY_DIR/"
+cp "$WORKSPACE_ROOT/evals/interactive_explorer.py" "$DEPLOY_DIR/evals/"
+
+# Clean up any pycache or python build artifacts from the copied files
+echo "Cleaning up python build artifacts and pycache..."
+find "$DEPLOY_DIR" -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+find "$DEPLOY_DIR" -name "*.pyc" -delete 2>/dev/null || true
+find "$DEPLOY_DIR" -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+
+# Navigate to deploy directory
+cd "$DEPLOY_DIR"
+
+# Initialize git if not already a repo
+if [ ! -d ".git" ]; then
+    git init -b main
+    git config user.name "Hugging Face Deployer"
+    git config user.email "deploy@huggingface.co"
+fi
+
+# Get HF remote URL
+REMOTE_URL=$(git remote get-url space 2>/dev/null || true)
+if [ -z "$REMOTE_URL" ]; then
+    read -p "Enter your Hugging Face Space Git URL (default: https://huggingface.co/spaces/rafmacalaba/data360-mcp-explorer): " USER_URL
+    if [ -z "$USER_URL" ]; then
+        USER_URL="https://huggingface.co/spaces/rafmacalaba/data360-mcp-explorer"
+    fi
+    git remote add space "$USER_URL"
+    echo -e "${GREEN}Added git remote 'space' pointing to $USER_URL${NC}"
+else
+    echo -e "Found existing 'space' remote pointing to: $REMOTE_URL"
+fi
+
+# Stage and commit locally inside the deploy folder
+git add -A
+git commit -m "Deploy explorer to Hugging Face Spaces" || echo "No changes to commit"
+
+# Push to Hugging Face Space
+echo -e "${BLUE}Pushing code to Hugging Face Space remote...${NC}"
+git push --force space main
+
+# Clean up copied files to keep local workspace clean
+echo "Cleaning up copied files from deploy directory..."
+rm -rf src pyproject.toml uv.lock evals
+
+echo -e "${GREEN}Deployment complete! Your Space is building at: $REMOTE_URL${NC}"

entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -e
+
+# 1. Start the Data360 MCP server in the background
+echo "Starting Data360 MCP Server on port 8021..."
+PREFAB_BUNDLED_RENDERER=1 uv run uvicorn data360.server:app --port 8021 --host 127.0.0.1 &
+
+# 2. Give the MCP server a moment to boot
+sleep 3
+
+# 3. Start the Explorer in the foreground on HF Space's exposed port 7860
+echo "Starting Visualization Engine Explorer on port 7860..."
+uv run python evals/interactive_explorer.py --port 7860

pyproject.toml

@@ -0,0 +1,100 @@
+
+[project]
+name = "data360-mcp"
+version = "0.1.2"
+description = "Model Context Protocol (MCP) server that gives LLM agents and chatbots direct access to the World Bank's Data360 Platform. Search, validate, and retrieve development indicators—from GDP and poverty to gender equality and climate—with structured metadata and time-series data, without hallucinating values."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastmcp>=3.4.3",
+  "prefab-ui>=0.20.2",
+  "mcp>=1.18.0",
+  "fastapi>=0.115.0",
+  "uvicorn[standard]>=0.30.0",
+  "typer>=0.20.1",
+  "gunicorn>=23.0.0",
+  "pydantic-settings>=2.0.0",
+  "python-dotenv>=1.0.0",
+  "draco @ git+https://github.com/avsolatorio/draco2.git@data360-mcp",
+  "opencensus-ext-azure>=1.1.13",
+  "azure-monitor-opentelemetry>=1.6.0",
+  "pandas>=3.0.0",
+  "cachetools>=6.2.4",
+  "scikit-learn>=1.8.0",
+  "opentelemetry-instrumentation-httpx>=0.50b0",
+  "opentelemetry-sdk>=1.28.0",
+  "opentelemetry-exporter-otlp>=1.28.0",
+  "vl-convert-python>=1.9.0.post1",
+  "huggingface-hub",
+]
+
+[project.optional-dependencies]
+# LangChain / LangGraph client (workspace package); use: uv sync --extra agent
+agent = ["data360-mcp-agent"]
+
+[build-system]
+requires = ["setuptools>=42", 'setuptools-scm']
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+data360 = ["tool_contract_version.json", "databases.json", "ref_area_groups.json"]
+
+[dependency-groups]
+dev = [
+  "data360-mcp-agent",
+  "pre-commit>=4.5.0",
+  "pyright>=1.1.407",
+  "ruff>=0.14.8",
+  "poethepoet>=0.27.0",
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "pytest-httpx>=0.27.0",
+  "pytest-cov>=4.1.0",
+  "pip-licenses>=5.0.0",
+  "pip-audit>=2.10.0",
+  "requests>=2.32.0",
+  "deepeval>=4.1.0",
+]
+
+[tool.ruff.lint]
+select = ['I', 'UP', 'PL', 'F401']
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+default = true
+
+[tool.pyright]
+typeCheckingMode = "standard"
+extraPaths = ["packages/data360-mcp-agent/src"]
+
+[tool.poe.tasks.serve]
+help = "Run the Data360 MCP server"
+cmd = "uv run fastmcp run src/data360/server.py --transport ${transport} --port ${port}"
+args = [
+   {name = "transport", options = ["--transport", "-t"], default = "streamable-http"},
+   {name = "port", options = ["--port", "-p"], default = "8021"},
+]
+
+[tool.poe.tasks.test]
+help = "Run tests"
+cmd = "pytest"
+
+[tool.poe.tasks.test-cov]
+help = "Run tests with coverage"
+cmd = "pytest --cov=src/data360 --cov-report=term-missing"
+
+[tool.poe.tasks.licenses]
+help = "Regenerate THIRD_PARTY_LICENSES.md"
+cmd = "python scripts/generate_licenses.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

src/data360/__init__.py

@@ -0,0 +1,5 @@
+from data360.tool_contract import get_tool_contract_version
+
+__version__ = "0.1.2"
+
+__all__ = ["__version__", "get_tool_contract_version"]

src/data360/config.py

@@ -0,0 +1,227 @@
+import functools as ft
+import logging
+import os
+
+# Load environment variables from .env file at import time, but only when not
+# running under pytest.  Test sessions set env vars explicitly via conftest/fixtures;
+# unconditional load_dotenv() would stomp on those values with whatever is in a
+# local .env file, making tests environment-dependent.
+import os as _os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Skip .env during pytest (collection and execution) so tests control DATA360_* URLs.
+if not _os.environ.get("PYTEST_CURRENT_TEST") and not _os.environ.get("PYTEST_RUNNING"):
+    load_dotenv()
+del _os
+
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MCPServerSettings(BaseSettings):
+    """Configuration settings for MCP server."""
+
+    port: int = Field(
+        default=8000,
+        description="Port for the MCP server",
+    )
+    transport: str = Field(
+        default="http",
+        description="Transport for the MCP server",
+    )
+    log_file: str | None = Field(
+        default=None,
+        description="Path to log file. If None, logs go to stderr/stdout.",
+    )
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+    )
+    charts_api_url: str | None = Field(
+        default=None,
+        description="URL for external charts API to store Vega-Lite specs (e.g. https://.../api/v1/charts). When set, viz specs are POSTed here instead of saving to static.",
+    )
+    charts_api_token: str | None = Field(
+        default=None,
+        description="Optional bearer token for external charts API (Authorization header).",
+    )
+    env: str | None = Field(
+        default=None,
+        description="Deployment environment (e.g. local, dev, staging, prod). Azure App Insights "
+        "and OpenTelemetry export are disabled when set to 'local' unless you set "
+        "OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) and/or "
+        "MCP_OTEL_CONSOLE=1 for local trace export; see data360.otel_setup.",
+    )
+    azure_connection_string: str | None = Field(
+        default=None,
+        description="Azure Application Insights connection string. If unset, falls back to APPLICATIONINSIGHTS_CONNECTION_STRING env var.",
+    )
+    readiness_enabled: bool = Field(
+        default=True,
+        description="When false, GET /ready returns 200 with readiness_checks=disabled (no dependency probes).",
+    )
+    health_check_timeout: float = Field(
+        default=5.0,
+        description="Per-check timeout in seconds for GET /ready outbound probes.",
+    )
+
+
+    model_config = SettingsConfigDict(env_prefix="MCP_")
+
+
+class Data360Settings(BaseSettings):
+    """Configuration settings for Data360 API integration."""
+
+    api_base_url: str = Field(
+        ...,
+        description="Base URL for the Data360 API",
+    )
+    codelist_api_base_url: str = Field(
+        default="https://extdataportal.worldbank.org/api/data360/metadata/codelist",
+        description=(
+            "URL for the unified Data360 codelist API. Returns all dimension codelists "
+            "(COMP_BREAKDOWN, UNIT_MEASURE, SEX, AGE, URBANISATION, FREQ, REF_AREA, …) "
+            "in a single call. Used by scripts/build_extdataportal_codelists.py to regenerate "
+            "the bundled src/data360/extdataportal_codelists.json."
+        ),
+    )
+    search_url: str | None = Field(
+        default=None,
+        description="URL for search endpoint (defaults to {api_base_url}/data360/portal/v1/public_data360_search)",
+    )
+    metadata_url: str | None = Field(
+        default=None,
+        description="URL for metadata endpoint (defaults to {api_base_url}/data360/metadata)",
+    )
+    disaggregation_url: str | None = Field(
+        default=None,
+        description="URL for disaggregation endpoint (defaults to {api_base_url}/data360/disaggregation)",
+    )
+    dimensions_url: str | None = Field(
+        default=None,
+        description="URL for dimensions endpoint (defaults to {api_base_url}/data360/portal/v1/dimensions)",
+    )
+    data_url: str | None = Field(
+        default=None,
+        description="URL for data endpoint (defaults to {api_base_url}/data)",
+    )
+    metadata_search_fields: list[str] = Field(
+        default=[
+            "series_description/idno",
+            "series_description/name",
+            "series_description/database_id",
+            "series_description/definition_long",
+            "series_description/methodology",
+            "series_description/limitation",
+            "series_description/relevance",
+            "series_description/aggregation_method",
+        ]
+    )
+
+    # Limit the data observations to the following confidentiality levels
+    data_obs_confidentiality_levels: list[str] = Field(
+        default=[
+            "PU",  # Public
+            # "OU",  # Official Use
+            # "CO",  # Confidential
+            # "SC",  # Strictly Confidential
+        ],
+        description="Confidentiality levels to limit the data observations to",
+    )
+
+    model_config = SettingsConfigDict(env_prefix="DATA360_")
+
+    @property
+    def api_url(self) -> str:
+        """Base path for Data360 HTTP APIs: ``{api_base_url}/data360`` (no trailing slash)."""
+        return f"{self.api_base_url.rstrip('/')}/data360"
+
+
+@ft.cache
+def get_data360_settings() -> Data360Settings:
+    """Get cached Data360 settings instance."""
+    return Data360Settings()  # pyright: ignore[reportCallIssue]
+
+
+@ft.cache
+def get_mcp_server_settings() -> MCPServerSettings:
+    """Get cached MCP server settings instance."""
+    return MCPServerSettings()  # pyright: ignore[reportCallIssue]
+
+
+def setup_logging(
+    log_file: str | None = None,
+    log_level: str = "INFO",
+    env: str | None = None,
+    azure_connection_string: str | None = None,
+) -> None:
+    """Configure logging to write to a file and/or console, and optionally Azure App Insights.
+
+    Args:
+        log_file: Path to log file. If None, logs only go to stderr.
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        env: Deployment environment. Azure handler is skipped when 'local'.
+        azure_connection_string: Azure App Insights connection string. Falls back to
+            APPLICATIONINSIGHTS_CONNECTION_STRING env var if not provided.
+    """
+    # Convert string level to logging constant
+    numeric_level = getattr(logging, log_level.upper(), logging.INFO)
+
+    # Create formatter
+    formatter = logging.Formatter(
+        fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # Get root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+
+    # Remove existing handlers to avoid duplicates
+    root_logger.handlers.clear()
+
+    # Console handler (stderr)
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(numeric_level)
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+    # File handler (if log_file is specified)
+    if log_file:
+        log_path = Path(log_file)
+        # Create parent directories if they don't exist
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler = logging.FileHandler(log_path, encoding="utf-8")
+        file_handler.setLevel(numeric_level)
+        file_handler.setFormatter(formatter)
+        root_logger.addHandler(file_handler)
+
+    # Azure App Insights handler (skipped for local environment or when no key is configured)
+    effective_connection_string = azure_connection_string or os.environ.get(
+        "APPLICATIONINSIGHTS_CONNECTION_STRING"
+    )
+    if env != "local" and effective_connection_string:
+        try:
+            from opencensus.ext.azure.log_exporter import (
+                AzureLogHandler,  # type: ignore[import-untyped]
+            )
+
+            def _callback(_):
+                return True
+
+            azure_handler = AzureLogHandler(
+                connection_string=effective_connection_string
+            )
+            azure_handler.setLevel(numeric_level)
+            azure_handler.add_telemetry_processor(_callback)
+            root_logger.addHandler(azure_handler)
+            root_logger.info("Azure App Insights logging enabled (env=%s).", env)
+        except ImportError:
+            root_logger.warning(
+                "opencensus-ext-azure not installed; skipping Azure App Insights handler."
+            )

src/data360/databases.json

@@ -0,0 +1,163 @@
+{
+    "BS_BTI": "The Bertelsmann Stiftung\u2019s Transformation Index (BTI)",
+    "BS_SGI": "Sustainable Governance Indicators (SGI)",
+    "DRMKC_INFORM": "INFORM Risk Index",
+    "EIA_EIAOD": "U.S. Energy Information Administration",
+    "EIU_DI": "Democracy Index",
+    "EPC_AI": "Epoch AI",
+    "FAO_AS": "Aquastat",
+    "FAO_CAHD": "Cost and Affordability of a Healthy Diet (CoAHD)",
+    "FAO_CP": "Consumer Price Indices",
+    "FAO_EMS": "Emissions Database",
+    "FAO_EMSTOT": "Emissions Totals",
+    "FAO_FBS": "Food Balance Sheet",
+    "FAO_FDI": "Foreign Direct Investment (FDI)",
+    "FAO_FS": "Suite of Food Security Indicators",
+    "FAO_GFRA": "Global Forest Resources Assessment",
+    "FAO_IC": "Credit to Agriculture",
+    "FAO_MK": "Macro-Economic Indicators",
+    "FAO_RP": "Pesticides Use",
+    "FAO_SDGB": "SDG Indicators",
+    "FH_FIW": "Freedom in the World",
+    "FH_NIT": "Nations in Transit",
+    "FSIN_GRFC": "Global Report on Food Crises (GRFC) Database",
+    "GDIP_DVC": "The Price of the World in Your Pocket: A Price Only Some Can Afford.",
+    "GEM_APS": "Adult Population Survey (APS)",
+    "GEM_NES": "National Expert Survey (NES)",
+    "GI_AII": "Africa Integrity Indicators",
+    "IBP_OBS": "Open Budget Survey",
+    "IDB_INFRALATAM": "Infralatam",
+    "IFC_GB": "EM Thematic Bond Database",
+    "IFC_GEM": "Global Emerging Markets (GEMs) Risk Database",
+    "IFPRI_ASTI": "Agrifood Systems Technologies and Innovations (ASTI)",
+    "ILO_EMP": "Employment by economic activity",
+    "IMF_AI": "Artificial Intelligence (AI) Preparedness Index",
+    "IMF_BOP": "Balance of Payments (BOP) and International Investment Position (IIP)",
+    "IMF_BOPAGG": "Balance of Payments (BOP), World and Regional Aggregates",
+    "IMF_CDIR": "Climate-driven INFORM Risk",
+    "IMF_CDIS": "Coordinated Direct Investment Survey (CDIS)",
+    "IMF_CPIS": "Coordinated Portfolio Investment Survey (CPIS)",
+    "IMF_DOT": "Direction of Trade Statistics (DOTS)",
+    "IMF_ET": "Environmental Taxes",
+    "IMF_FAS": "Financial Access Survey (FAS)",
+    "IMF_FFS": "Fossil Fuel Subsidies",
+    "IMF_FISCALDECENTRALIZATION": "Fiscal Decentralization",
+    "IMF_FM": "Fiscal Monitor (FM)",
+    "IMF_FPR": "Country Fiscal Measures in Response to the COVID-19 Pandemic",
+    "IMF_FSI": "Financial Soundness Indicators (FSIs)",
+    "IMF_FSIRE": "Financial Soundness Indicators: Reporting entities",
+    "IMF_GENDER_EQUALITY": "Gender Equality",
+    "IMF_GFSCOFOG": "Government Finance Statistics (GFS), Expenditure by Function of Government (COFOG)",
+    "IMF_GFSE": "Government Finance Statistics (GFS), Expense",
+    "IMF_GFSFALCS": "Government Finance Statistics (GFS), Financial Assets and Liabilities by Counterpart Sector",
+    "IMF_GFSIBS": "Government Finance Statistics (GFS), Integrated Balance Sheet (Stock Positions and Flows in Assets and Liabilities)",
+    "IMF_GFSMAB": "Government Finance Statistics (GFS), Main Aggregates and Balances",
+    "IMF_GFSR": "Government Finance Statistics (GFS), Revenue",
+    "IMF_GFSSSUC": "Government Finance Statistics (GFS), Statement of Sources and Uses of Cash",
+    "IMF_GHW": "Global Housing Watch, House Price-to-Income Ratio Around the World",
+    "IMF_IFS": "International Financial Statistics (IFS)",
+    "IMF_IRFCL": "International Reserves and Foreign Currency Liquidity (IRFCL)",
+    "IMF_PCTOT": "Commodity Terms of Trade",
+    "IMF_WEO": "World Economic Outlook (WEO)",
+    "IMF_WORLD": "World Revenue Longitudinal Data (WoRLD)",
+    "IPC_IPC": "Integrated Food Security Phase Classification",
+    "ITU_DH": "ITU DataHub",
+    "ITU_GCI": "Global Cybersecurity Index",
+    "ITU_ICT": "ICT Regulatory Tracker",
+    "IUU_FRI": "IUU Fishing Risk Index",
+    "JRC_EDGAR": "Emissions Database for Global Atmospheric Research (EDGAR)",
+    "OECDWBG_PMR": "Product Market Regulation Database",
+    "OECD_AI": "OECD Artificial Intelligence",
+    "OECD_BROADBAND": "Broadband and Telecom Database",
+    "OECD_DSTRI": "Digital Services Trade Restrictive Index",
+    "OECD_IDD": "Income Distribution Database",
+    "OECD_PMR": "Product Market Regulation (PMR)",
+    "OECD_STRI": "Services Trade Restrictiveness Index Regulatory Database",
+    "OECD_TIVA": "Trade in Value Added (TiVA)",
+    "OHI_OHI": "Ocean Health Index (OHI)",
+    "OOKLA_ST": "Speed Test",
+    "OWID_CB": "CO2 and Greenhouse Gas Emissions",
+    "PCH_IXP": "Internet Exchange Directory",
+    "PEERING_DB": "Interconnection Database, Number of Connected Data Centers",
+    "POLITY5_PRC": "Political Regime Characteristics Database",
+    "RWB_PFI": "Press Freedom Index",
+    "T500_TL": "Top 500: The list",
+    "UNCTAD_DE": "Digital Economy and Technology",
+    "UNCTAD_LSC": "Liner Shipping Connectivity Index",
+    "UNCTAD_MT": "Maritime Transport",
+    "UNDRR_SFM": "Sendai Framework Monitor (SFM)",
+    "UND_NDGAIN": "Notre Dame Global Adaptation Initiative (ND-GAIN)",
+    "UNEP_OPH": "Ocean+ Habitats",
+    "UNESCO_UIS": "UNESCO Education Statistics",
+    "UNICEF_DW": "UNICEF Data Warehouse",
+    "UNSD_EI": "UNSD Environmental Indicators",
+    "UN_EGDI": "E-Government Development Index (EGDI)",
+    "UN_SDG": "Sustainable Development Goals (SDG) Database",
+    "VDEM_CORE": "V-Dem Core",
+    "WB_AGCI": "AgriConnect Indicators",
+    "WB_ASPD": "Global Productivity: A Cross-country Database of Productivity",
+    "WB_ASPIRE": "The Atlas of Social Protection Indicators of Resilience and Equity (ASPIRE)",
+    "WB_BID": "Benchmarking Infrastructure Development",
+    "WB_BOOST": "BOOST: Open Budget Portal",
+    "WB_BPS": "COVID-19 Business Pulse Surveys",
+    "WB_BREADY": "Business Ready",
+    "WB_CCDFS": "A Cross-Country Database of Fiscal Space",
+    "WB_CCKP": "CCKP ERA5 Dataset",
+    "WB_CLEAR": "Climate and Economic Analyses for Resilience in Water (CLEAR Water)",
+    "WB_CPIA": "Country Policy and Institutional Assessments (CPIA)",
+    "WB_CSC": "World Bank Group Corporate Scorecard",
+    "WB_CWON": "The Changing Wealth of Nations (CWON)",
+    "WB_EDSTATS": "Education Statistics",
+    "WB_EQOSOGI": "Equality of Opportunity for Sexual and Gender Minorities (EQOSOGI)",
+    "WB_ES": "Enterprise Surveys",
+    "WB_ESG": "Environment, Social & Governance (ESG)",
+    "WB_EWSA": "Europe and Central Asia (ECA) Water Security Assessment",
+    "WB_FINDEX": "Global Findex Database",
+    "WB_FSI": "Financial Sector Indicators",
+    "WB_GBIOD": "Global Biodiversity Data",
+    "WB_GEP": "Global Economic Prospects",
+    "WB_GIRG": "Global Indicators of Regulatory Governance",
+    "WB_GS": "Gender Statistics",
+    "WB_GTMI": "GovTech Maturity Index 2022",
+    "WB_GWA": "Global Wind Atlas (GWA)",
+    "WB_HCI": "Human Capital Index (HCI)",
+    "WB_HCIP": "Human Capital Index Plus (HCI+)",
+    "WB_HCP": "Human Capital Project (HCP)",
+    "WB_HLO": "Harmonized Learning Outcomes (HLO)",
+    "WB_HNP": "Health Nutrition and Population Statistics",
+    "WB_ID4D": "Identification for Development (ID4D) Global Dataset",
+    "WB_IDS": "International Debt Statistics (IDS)",
+    "WB_INFECDB": "Informal Economy Database",
+    "WB_KNOMAD": "The Global Knowledge Partnership on Migration and Development (KNOMAD) database",
+    "WB_LPGD": "Learning Poverty Global Database",
+    "WB_LPI": "Logistics Performance Index (LPI)",
+    "WB_LPI_20": "Logistic Performance Indicators (LPI) 2.0",
+    "WB_MPM": "Multidimensional Poverty Measure",
+    "WB_MPO": "Macro Poverty Outlook (MPO)",
+    "WB_PIP": "Poverty and Inequality Platform (PIP)",
+    "WB_PPI": "Private Participation in Infrastructure Database (PPI)",
+    "WB_RISE": "Regulatory Indicators for Sustainable Energy (RISE)",
+    "WB_SE4ALL": "Sustainable Energy For All (SE4ALL)",
+    "WB_SHP": "Global Database Of Shared Prosperity",
+    "WB_SOLAR_ATLAS": "Global Solar Atlas",
+    "WB_SPI": "Statistical Performance Indicators (SPI)",
+    "WB_SSGD": "Social sustainability global database",
+    "WB_THINK_HAZARD": "ThinkHazard!",
+    "WB_UHC": "Universal Health Coverage (UHC)",
+    "WB_WAW": "What a Waste (3.0)",
+    "WB_WBL": "Women, Business and the Law (WBL)",
+    "WB_WDI": "World Development Indicators (WDI)",
+    "WB_WGI": "Worldwide Governance Indicators (WGI)",
+    "WB_WITS": "World Integrated Trade Solution (WITS)",
+    "WB_WWBI": "Worldwide Bureaucracy Indicators (WWBI)",
+    "WEF_GCI": "Global Competitiveness Index (GCI) 4.0",
+    "WEF_GCIHH": "Global Competitiveness Index (GCI) - Historical Dataset",
+    "WEF_TTDI": "Travel & Tourism Development Index (TTDI)",
+    "WHO_GHO": "Global Health Observatory Indicators",
+    "WIPO_ICT": "Intellectual Property Statistics - Patent indicators",
+    "WI_GRT": "Green Recovery Tracker",
+    "WJP_ROL": "Rule of Law Index",
+    "WRI_AQDT": "Aqueduct 4.0 Current and Future Country Rankings",
+    "WRI_CLIMATEWATCH": "Climate Watch",
+    "WRI_GFW": "Global Forest Watch"
+}

src/data360/errors.py

@@ -0,0 +1,348 @@
+"""Centralized error management for the Data360 MCP server.
+
+Provides a unified error hierarchy for consistent, LLM-actionable error messages.
+Follows the pattern from https://github.com/avsolatorio/data-ai-chatbot/blob/dev/backend/app/core/errors.py
+
+Error codes follow the format: "<type>:<context>" (e.g. "http_error:search", "timeout:metadata").
+"""
+
+import logging
+from typing import Any
+
+_logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Message registry - maps error codes to user/LLM-friendly messages
+# ---------------------------------------------------------------------------
+_ERROR_MESSAGES: dict[str, str] = {
+    # HTTP / network errors
+    "http_error:search": "The search request failed with an HTTP error. Please try again.",
+    "http_error:dataset": "The dataset search request failed with an HTTP error. Please try again.",
+    "http_error:metadata": "Failed to fetch metadata due to an HTTP error. Verify the indicator_id and database_id are correct.",
+    "http_error:disaggregation": "Failed to fetch disaggregation options due to an HTTP error. Verify the indicator_id and database_id are correct.",
+    "http_error:data": "Failed to fetch data due to an HTTP error. Verify the indicator_id, database_id, and filters are correct.",
+    # Timeouts
+    "timeout:search": "The search request timed out. Please try again.",
+    "timeout:dataset": "The dataset search request timed out. Please try again.",
+    "timeout:metadata": "The metadata request timed out. Please try again.",
+    "timeout:disaggregation": "The disaggregation request timed out. Please try again.",
+    "timeout:data": "The data request timed out. Please try again.",
+    # Request errors (connection issues, DNS, etc.)
+    "request_error:search": "A network error occurred during search. Check connectivity and try again.",
+    "request_error:dataset": "A network error occurred searching datasets. Check connectivity and try again.",
+    "request_error:metadata": "A network error occurred fetching metadata. Check connectivity and try again.",
+    "request_error:disaggregation": "A network error occurred fetching disaggregation options. Check connectivity and try again.",
+    "request_error:data": "A network error occurred fetching data. Check connectivity and try again.",
+    # Parse errors
+    "parse_error:search": "Failed to parse the search API response. The upstream API may be returning unexpected data.",
+    "parse_error:dataset": "Failed to parse the dataset search response.",
+    "parse_error:metadata": "Failed to parse the metadata API response.",
+    "parse_error:disaggregation": "Failed to parse the disaggregation API response.",
+    "parse_error:data": "Failed to parse the data API response.",
+    # Validation errors
+    "validation_error:search": "Invalid search parameters. Please check your query and filters.",
+    "validation_error:dataset": "Invalid dataset search parameters.",
+    "validation_error:metadata": "Invalid metadata request parameters. Check the indicator_id and database_id.",
+    "validation_error:data": "Invalid data request parameters. Check the indicator_id, database_id, and filters.",
+    "validation_error:api_response": "The API response failed validation. The data format may have changed.",
+    # Not found
+    "not_found:indicator": "No indicators found matching your query. Try broadening your search terms.",
+    "not_found:metadata": "No metadata found for the specified indicator. Verify the indicator_id is correct.",
+    # Unexpected
+    "unexpected:search": "An unexpected error occurred during search.",
+    "unexpected:dataset": "An unexpected error occurred searching datasets.",
+    "unexpected:metadata": "An unexpected error occurred fetching metadata.",
+    "unexpected:disaggregation": "An unexpected error occurred fetching disaggregation options.",
+    "unexpected:data": "An unexpected error occurred fetching data.",
+}
+
+
+class Data360MCPError(Exception):
+    """Base exception for all Data360 MCP errors.
+
+    Attributes:
+        error_code: Structured code like "http_error:search".
+        detail: Human/LLM-readable error message.
+        original_error: The original exception that caused this error, if any.
+        log_level: logging level used when this error is constructed. Subclasses
+            may override (e.g. NotFoundError uses WARNING).
+    """
+
+    log_level: int = logging.ERROR
+
+    def __init__(
+        self,
+        error_code: str,
+        detail: str | None = None,
+        original_error: Exception | None = None,
+    ):
+        self.error_code = error_code
+        self.detail = detail or self._get_message(error_code)
+        self.original_error = original_error
+        super().__init__(self.detail)
+        exc_info = (
+            (type(original_error), original_error, original_error.__traceback__)
+            if original_error is not None
+            else None
+        )
+        _logger.log(
+            self.log_level,
+            "[%s] %s",
+            self.error_code,
+            self.detail,
+            exc_info=exc_info,
+        )
+
+    def _get_message(self, error_code: str) -> str:
+        return _ERROR_MESSAGES.get(
+            error_code, "Something went wrong. Please try again."
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize error for structured responses."""
+        result: dict[str, Any] = {
+            "error_code": self.error_code,
+            "detail": self.detail,
+        }
+        if self.original_error:
+            result["original_error"] = str(self.original_error)
+        return result
+
+
+class APIError(Data360MCPError):
+    """HTTP errors from the Data360 API (4xx, 5xx responses)."""
+
+    def __init__(
+        self,
+        context: str,
+        status_code: int,
+        response_text: str = "",
+        original_error: Exception | None = None,
+    ):
+        self.status_code = status_code
+        self.response_text = response_text
+
+        # Sanitize response text - avoid leaking WAF HTML into error messages
+        sanitized_response = self._sanitize_error_response(response_text, status_code)
+        detail = f"HTTP {status_code}: {sanitized_response}"
+
+        super().__init__(
+            error_code=f"http_error:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+    @staticmethod
+    def _sanitize_error_response(response_text: str, status_code: int) -> str:
+        """Sanitize error responses to avoid leaking HTML/WAF content.
+
+        Args:
+            response_text: Raw response body from the backend
+            status_code: HTTP status code
+
+        Returns:
+            Clean, user-friendly error message
+        """
+        # Empty or whitespace-only response
+        if not response_text or not response_text.strip():
+            return _get_status_message(status_code)
+
+        # If response looks like HTML (WAF error pages), don't include it
+        # Check both raw and after stripping common whitespace/newlines
+        text_to_check = response_text.lstrip()
+        if text_to_check.startswith(
+            ("<html", "<!DOCTYPE", "<HTML", "<!doctype", "<!Doctype")
+        ):
+            return _get_status_message(status_code)
+
+        # For JSON error responses, try to extract the error message
+        if text_to_check.startswith("{"):
+            try:
+                import json
+
+                error_data = json.loads(response_text)
+                # Common error message fields
+                for key in ["error", "message", "detail", "error_description", "code"]:
+                    if key in error_data:
+                        msg = error_data[key]
+                        # Skip if the JSON error field itself contains HTML
+                        msg_str = str(msg)
+                        if msg_str.lstrip().startswith(
+                            ("<html", "<!DOCTYPE", "<HTML", "<!doctype")
+                        ):
+                            return _get_status_message(status_code)
+                        # Limit length to avoid verbose error dumps
+                        return (
+                            msg_str[:200]
+                            if len(msg_str) <= 200
+                            else msg_str[:200] + "..."
+                        )
+            except Exception:
+                pass  # Fall through to default message
+
+        # Check if response contains HTML tags anywhere (not just at start)
+        # Common WAF patterns: <html, <body, <head, <title
+        lower_text = response_text.lower()
+        if any(
+            tag in lower_text
+            for tag in ["<html", "<body", "<head", "<title", "<!doctype"]
+        ):
+            return _get_status_message(status_code)
+
+        # For other responses, truncate and sanitize
+        # Remove excessive whitespace and newlines
+        cleaned = " ".join(response_text.split())
+        if len(cleaned) > 200:
+            return cleaned[:200] + "..."
+
+        return cleaned if cleaned else _get_status_message(status_code)
+
+
+def _get_status_message(status_code: int) -> str:
+    """Get a user-friendly message for common HTTP status codes."""
+    status_messages = {
+        400: "Bad Request - Invalid parameters",
+        401: "Unauthorized - Authentication required",
+        403: "Forbidden - Access denied",
+        404: "Not Found - Resource does not exist",
+        408: "Request Timeout - Session expired",
+        413: "Payload Too Large - Request exceeds size limit",
+        429: "Too Many Requests - Rate limit exceeded",
+        500: "Internal Server Error - Backend service error",
+        502: "Bad Gateway - Backend service unavailable",
+        503: "Service Unavailable - Backend temporarily down",
+        504: "Gateway Timeout - Backend did not respond in time",
+    }
+    return status_messages.get(
+        status_code, f"The request failed with status {status_code}"
+    )
+
+
+class Data360TimeoutError(Data360MCPError):
+    """Timeout errors when calling the Data360 API."""
+
+    def __init__(
+        self,
+        context: str,
+        original_error: Exception | None = None,
+    ):
+        detail = _ERROR_MESSAGES.get(
+            f"timeout:{context}", f"Request timed out: {context}"
+        )
+        super().__init__(
+            error_code=f"timeout:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+
+class RequestError(Data360MCPError):
+    """Network-level errors (DNS, connection refused, etc.)."""
+
+    def __init__(
+        self,
+        context: str,
+        original_error: Exception | None = None,
+    ):
+        detail = _ERROR_MESSAGES.get(
+            f"request_error:{context}", f"Request error: {context}"
+        )
+        super().__init__(
+            error_code=f"request_error:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+
+class ParseError(Data360MCPError):
+    """JSON parsing or response validation errors."""
+
+    def __init__(
+        self,
+        context: str,
+        detail: str | None = None,
+        original_error: Exception | None = None,
+    ):
+        detail = detail or _ERROR_MESSAGES.get(
+            f"parse_error:{context}", f"Failed to parse response: {context}"
+        )
+        super().__init__(
+            error_code=f"parse_error:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+
+class ValidationError(Data360MCPError):
+    """Invalid input parameters or failed response validation."""
+
+    def __init__(
+        self,
+        context: str,
+        detail: str | None = None,
+        original_error: Exception | None = None,
+    ):
+        detail = detail or _ERROR_MESSAGES.get(
+            f"validation_error:{context}", f"Validation error: {context}"
+        )
+        super().__init__(
+            error_code=f"validation_error:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+
+class NotFoundError(Data360MCPError):
+    """Resource not found errors."""
+
+    log_level: int = logging.WARNING
+
+    def __init__(
+        self,
+        context: str,
+        detail: str | None = None,
+        original_error: Exception | None = None,
+    ):
+        detail = detail or _ERROR_MESSAGES.get(
+            f"not_found:{context}", f"Not found: {context}"
+        )
+        super().__init__(
+            error_code=f"not_found:{context}",
+            detail=detail,
+            original_error=original_error,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Helper to convert exceptions into Data360MCPError
+# ---------------------------------------------------------------------------
+def classify_error(exc: Exception, context: str) -> Data360MCPError:
+    """Convert an exception into the appropriate Data360MCPError subclass.
+
+    Args:
+        exc: The original httpx exception.
+        context: The operation context (e.g. "search", "metadata", "data").
+
+    Returns:
+        The appropriate Data360MCPError subclass instance.
+    """
+    import httpx
+
+    if isinstance(exc, httpx.HTTPStatusError):
+        return APIError(
+            context=context,
+            status_code=exc.response.status_code,
+            response_text=exc.response.text,
+            original_error=exc,
+        )
+    elif isinstance(exc, httpx.TimeoutException):
+        return Data360TimeoutError(context=context, original_error=exc)
+    elif isinstance(exc, httpx.RequestError):
+        return RequestError(context=context, original_error=exc)
+    else:
+        return Data360MCPError(
+            error_code=f"unexpected:{context}",
+            detail=f"Unexpected error: {str(exc)}",
+            original_error=exc,
+        )

src/data360/health.py

@@ -0,0 +1,278 @@
+"""Liveness and readiness checks for the Data360 MCP HTTP server."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from datetime import UTC, datetime
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from data360.config import get_data360_settings, get_mcp_server_settings
+from data360.http_client import get_shared_httpx_client
+from data360.providers import get_database_mapping
+
+_SERVICE_NAME = "data360-mcp"
+_PROBE_FILENAME = ".health_probe"
+_CHARTS_UP_STATUS_CODES = frozenset({401, 403, 405, 422})
+
+
+def _package_version() -> str:
+    try:
+        return version("data360")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def get_liveness_body() -> dict[str, Any]:
+    """Return the JSON body for GET /health (no outbound I/O)."""
+    settings = get_mcp_server_settings()
+    return {
+        "status": "ok",
+        "service": _SERVICE_NAME,
+        "version": _package_version(),
+        "env": settings.env,
+    }
+
+
+def _static_viz_specs_dir() -> Path:
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return Path(os.getcwd()) / "static" / "viz_specs"
+    server_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.abspath(os.path.join(server_dir, "..", ".."))
+    return Path(project_root) / "static" / "viz_specs"
+
+
+async def _check_data360_api(timeout: float) -> dict[str, Any]:
+    """Probe Data360 search API with a minimal dataset query."""
+    data360 = get_data360_settings()
+    url = data360.search_url or f"{data360.api_url}/searchv2"
+    started = time.perf_counter()
+
+    async def _probe() -> dict[str, Any]:
+        client = get_shared_httpx_client()
+        response = await client.post(
+            url,
+            headers={"accept": "*/*", "Content-Type": "application/json"},
+            json={
+                "filter": "type eq 'dataset'",
+                "select": "series_description/database_id",
+                "top": 1,
+                "skip": 0,
+            },
+        )
+        response.raise_for_status()
+        response.json()
+        return {
+            "ok": True,
+            "latency_ms": round((time.perf_counter() - started) * 1000),
+        }
+
+    try:
+        return await asyncio.wait_for(_probe(), timeout=timeout)
+    except TimeoutError:
+        return {"ok": False, "detail": "timeout"}
+    except httpx.HTTPStatusError as e:
+        return {"ok": False, "detail": f"http_{e.response.status_code}"}
+    except httpx.RequestError:
+        return {"ok": False, "detail": "connection_error"}
+    except Exception:
+        return {"ok": False, "detail": "probe_failed"}
+
+
+async def _check_database_mapping() -> dict[str, Any]:
+    """Verify the in-memory database_id → name cache is usable."""
+    try:
+        mapping = await get_database_mapping()
+    except Exception:
+        return {"ok": False, "detail": "mapping_unavailable", "count": 0}
+
+    valid = [
+        (k, v)
+        for k, v in mapping.items()
+        if isinstance(k, str) and k.strip() and isinstance(v, str) and v.strip()
+    ]
+    count = len(mapping)
+    if count == 0:
+        return {"ok": False, "detail": "empty_cache", "count": 0, "source": "cache"}
+    if not valid:
+        return {
+            "ok": False,
+            "detail": "invalid_entries",
+            "count": count,
+            "source": "cache",
+        }
+    return {"ok": True, "count": count, "source": "cache"}
+
+
+async def _check_static_writable() -> dict[str, Any]:
+    """Verify static/viz_specs exists and accepts writes."""
+    specs_dir = _static_viz_specs_dir()
+    try:
+        specs_dir.mkdir(parents=True, exist_ok=True)
+        probe_path = specs_dir / _PROBE_FILENAME
+        probe_path.write_text("ok", encoding="utf-8")
+        probe_path.unlink(missing_ok=True)
+        return {"ok": True}
+    except OSError:
+        return {"ok": False, "detail": "not_writable"}
+
+
+async def _check_charts_api_reachable(timeout: float) -> dict[str, Any]:
+    """Probe Charts API reachability without creating a chart."""
+    charts_url = get_mcp_server_settings().charts_api_url
+    if not charts_url:
+        return {"ok": False, "detail": "not_configured"}
+
+    started = time.perf_counter()
+
+    async def _probe() -> dict[str, Any]:
+        client = get_shared_httpx_client()
+        response = await client.head(charts_url)
+        if response.status_code >= 500:
+            response.raise_for_status()
+        if (
+            response.status_code < 400
+            or response.status_code in _CHARTS_UP_STATUS_CODES
+        ):
+            return {
+                "ok": True,
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+            }
+        response.raise_for_status()
+        return {"ok": True}
+
+    try:
+        return await asyncio.wait_for(_probe(), timeout=timeout)
+    except TimeoutError:
+        return {"ok": False, "detail": "timeout"}
+    except httpx.HTTPStatusError as e:
+        status = e.response.status_code
+        if status in _CHARTS_UP_STATUS_CODES:
+            return {
+                "ok": True,
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+            }
+        return {"ok": False, "detail": f"http_{status}"}
+    except httpx.RequestError:
+        return {"ok": False, "detail": "connection_error"}
+    except Exception:
+        return {"ok": False, "detail": "probe_failed"}
+
+
+async def _check_viz_storage(timeout: float) -> dict[str, Any]:
+    """Check viz spec persistence: Charts API and/or static fallback."""
+    settings = get_mcp_server_settings()
+    static_result = await _check_static_writable()
+    static_ok = static_result.get("ok", False)
+
+    if settings.charts_api_url:
+        charts_result = await _check_charts_api_reachable(timeout)
+        charts_ok = charts_result.get("ok", False)
+        ok = charts_ok or static_ok
+        entry: dict[str, Any] = {
+            "ok": ok,
+            "primary": "charts_api",
+            "fallback": "static",
+            "charts_api": charts_result,
+            "static": static_result,
+        }
+        if charts_ok:
+            entry["backend"] = "charts_api"
+        elif static_ok:
+            entry["backend"] = "static"
+        else:
+            entry["detail"] = "charts_and_static_unavailable"
+        return entry
+
+    entry = {
+        "ok": static_ok,
+        "backend": "static",
+        "primary": "static",
+        "static": static_result,
+    }
+    if not static_ok:
+        entry["detail"] = static_result.get("detail", "not_writable")
+    return entry
+
+
+async def _check_codelist_api(timeout: float) -> dict[str, Any]:
+    """Optional probe for REF_AREA codelist API (non-blocking for readiness)."""
+    data360 = get_data360_settings()
+    url = f"{data360.api_url}/codelist"
+    started = time.perf_counter()
+
+    async def _probe() -> dict[str, Any]:
+        client = get_shared_httpx_client()
+        response = await client.get(url, params={"type": "REF_AREA"})
+        response.raise_for_status()
+        response.json()
+        return {
+            "ok": True,
+            "latency_ms": round((time.perf_counter() - started) * 1000),
+        }
+
+    try:
+        result = await asyncio.wait_for(_probe(), timeout=timeout)
+        return result
+    except TimeoutError:
+        return {"ok": False, "detail": "timeout", "degraded": True}
+    except httpx.HTTPStatusError as e:
+        return {
+            "ok": False,
+            "detail": f"http_{e.response.status_code}",
+            "degraded": True,
+        }
+    except httpx.RequestError:
+        return {"ok": False, "detail": "connection_error", "degraded": True}
+    except Exception:
+        return {"ok": False, "detail": "probe_failed", "degraded": True}
+
+
+def _critical_checks_ok(checks: dict[str, Any]) -> bool:
+    for name in ("data360_api", "database_mapping", "viz_storage"):
+        entry = checks.get(name)
+        if not entry or not entry.get("ok"):
+            return False
+    return True
+
+
+async def run_readiness() -> tuple[int, dict[str, Any]]:
+    """Run dependency probes; return (HTTP status code, JSON body)."""
+    settings = get_mcp_server_settings()
+    if not settings.readiness_enabled:
+        return 200, {
+            "status": "ready",
+            "checks": {},
+            "readiness_checks": "disabled",
+        }
+
+    timeout = settings.health_check_timeout
+    timestamp = datetime.now(UTC).isoformat()
+
+    (
+        data360_result,
+        mapping_result,
+        viz_result,
+        codelist_result,
+    ) = await asyncio.gather(
+        _check_data360_api(timeout),
+        _check_database_mapping(),
+        _check_viz_storage(timeout),
+        _check_codelist_api(timeout),
+    )
+
+    checks: dict[str, Any] = {
+        "data360_api": data360_result,
+        "database_mapping": mapping_result,
+        "viz_storage": viz_result,
+        "codelist_api": codelist_result,
+    }
+
+    if _critical_checks_ok(checks):
+        return 200, {"status": "ready", "timestamp": timestamp, "checks": checks}
+    return 503, {"status": "not_ready", "timestamp": timestamp, "checks": checks}

src/data360/http_client.py

@@ -0,0 +1,39 @@
+"""Shared httpx.AsyncClient for connection reuse and consistent outbound behavior."""
+
+from __future__ import annotations
+
+import threading
+
+import httpx
+
+_DEFAULT_TIMEOUT = 30.0
+
+_client: httpx.AsyncClient | None = None
+_client_lock = threading.Lock()
+
+
+def get_shared_httpx_client() -> httpx.AsyncClient:
+    """Return a process-wide async HTTP client (lazy singleton)."""
+    global _client  # noqa: PLW0603
+    client = _client
+    if client is not None and not client.is_closed:
+        return client
+
+    with _client_lock:
+        client = _client
+        if client is None or client.is_closed:
+            client = httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT)
+            _client = client
+        return client
+
+
+async def aclose_shared_httpx_client() -> None:
+    """Close the shared client (call from ASGI shutdown)."""
+    global _client  # noqa: PLW0603
+    with _client_lock:
+        client = _client
+        _client = None
+
+    if client is not None and not client.is_closed:
+        await client.aclose()
+

src/data360/mcp_server/__init__.py

@@ -0,0 +1,13 @@
+from . import (
+    prompts,
+    resources,
+    tools,
+)
+from ._server_definition import mcp
+
+__all__ = [
+    "mcp",
+    "tools",
+    "resources",
+    "prompts",
+]

src/data360/mcp_server/__main__.py

@@ -0,0 +1,32 @@
+import dotenv
+import typer
+from fastmcp.server.server import Transport
+
+from data360.config import get_mcp_server_settings, setup_logging
+from data360.mcp_server import mcp
+
+
+def main(
+    transport: Transport = typer.Option(
+        "streamable-http", "-t", "--transport", help="Transport to use."
+    ),
+    port: int = typer.Option(8021, "-p", "--port", help="Port to bind the server to."),
+):
+    """Run the MCP server with configurable transport and port."""
+    dotenv.load_dotenv()
+
+    # Setup logging from configuration
+    mcp_settings = get_mcp_server_settings()
+    setup_logging(
+        log_file=mcp_settings.log_file,
+        log_level=mcp_settings.log_level,
+        env=mcp_settings.env,
+        azure_connection_string=mcp_settings.azure_connection_string,
+    )
+
+    kwargs = {"port": port} if transport != "stdio" else {}
+    mcp.run(transport=transport, **kwargs)
+
+
+if __name__ == "__main__":
+    typer.run(main)

src/data360/mcp_server/_server_definition.py

@@ -0,0 +1,7 @@
+from fastmcp import FastMCP
+
+# NOTE: base definition to allow for mounting of resources, prompts, tools, independently
+mcp = FastMCP(
+    "Data360 MCP Server",
+    version="0.1.0",
+)

src/data360/mcp_server/agent_recipe.py

@@ -0,0 +1,80 @@
+"""Integration recipe text for hosts using ``data360-mcp-agent`` or custom LangGraph clients.
+
+Published as MCP resource ``data360://agent-recipe`` so the server remains the
+single catalog of: resources, named prompts, and how to compose them.
+"""
+
+from __future__ import annotations
+
+# Keep in sync with module docstrings in prompts.py and the data360-mcp-agent README.
+AGENT_RECIPE_MARKDOWN = """# Data360 MCP — host integration recipe
+
+Use this with **LangGraph**, **LangChain**, or any client that loads MCP resources
+and optional **MCP prompts** before the user message.
+
+## 1. What to read from this server
+
+| URI | Load | Role |
+|-----|------|------|
+| `data360://system-prompt` | **Required** | Search → codes → disaggregation → `get_data` → viz decision tree. |
+| `data360://context` | **Recommended** | JSON: `current_date`, `current_year` (for “last N years”). |
+| `data360://k360-narrative-style` | Optional | Markdown response contract for staged K360 narrative renderers. |
+| `data360://agent-recipe` | Optional | This page; wire-up only (no extra tool semantics). |
+
+**On-demand reference** (larger): `metadata-fields`, `data-schema`, `data-filters`, `search-usage`, `codelists`, `databases`.
+
+## 2. MCP named prompts (`prompts/list` + `prompts/get`)
+
+Call by name when the user turn matches the scenario; prepend the returned **string**
+to the conversation as a **system** or **user** block (your host convention).
+
+| Prompt | Arguments | When to use |
+|--------|-----------|-------------|
+| `indicator_search` | `query`, optional `country`, `required_dimensions` | Pick one indicator among many search hits. |
+| `indicator_details` | `indicator_id`, `database_id`, optional `question` | Methodology / definition questions. |
+| `country_data` | `query`, `country`, optional `start_year`, `end_year` | One country (or small list) + indicator theme → data + chart. |
+| `gate_classifier` | _(none)_ | Decide in/out of scope for WB/Data360 **before** tool loop (mirrors gated agent). |
+| `thematic_to_data` | `user_message` | Turn a broad development-economics question into economies, terms, years, peers. |
+| `k360_research_compiler` | `user_question`, optional `data_question`, `tool_calls_json` | Build a stable JSON content packet from tool trace. |
+| `k360_narrative` | `user_question`, `content_packet_json`, optional `raw_tool_results_json`, `include_claim_tags` | Convert packet + evidence into polished narrative markdown. |
+
+**Typical composed turn (thematic question):**
+
+1. (Optional) `prompts/get` → `gate_classifier` — run a small classifier; if out of scope, skip tools.
+2. (Optional) `prompts/get` → `thematic_to_data` with the user text — paste result into `HumanMessage` or augment the last user turn.
+3. Run the tool-using assistant with **`data360://system-prompt`** (plus `context`) as system instructions.
+
+**Typical composed turn (country + theme):**
+
+1. `prompts/get` → `country_data` with `query` + `country` (+ years).
+2. Run the assistant with the same system stack as above.
+
+## 3. Python: ``data360-mcp-agent`` package
+
+- **Env:** `DATA360_MCP_URL` (e.g. `http://127.0.0.1:8000/mcp`), LLM key or inject `llm=`.
+- **`create_data360_mcp_agent()`** — fetches tools + `system-prompt` and `context`, builds a LangChain agent.
+- **`create_data360_gated_langgraph_node()`** — adds a **local** gate + reform step (same *intent* as `gate_classifier` + `thematic_to_data`; you can later replace those steps with `prompts/get` for a single source of truth).
+- **Extra resources in the system stack:** `DATA360_AGENT_EXTRA_RESOURCES=data360://agent-recipe` (comma-separated URIs).
+
+## 4. Composition order (recommended)
+
+1. **System text:** `system-prompt` + `context` + any extra resource bodies + optional tool-name summary (as your client does).
+2. **Optional prompt blocks:** from `prompts/get` (`country_data`, `thematic_to_data`, …).
+3. **User:** current user message (optionally rewritten using `thematic_to_data` output).
+4. **Assistant:** tool calls until done, then natural-language answer.
+
+### Staged K360 flow
+
+`Gate -> Rewriter -> Compile -> Narrative`
+
+1. `gate_classifier` decides relevance.
+2. `thematic_to_data` rewrites broad questions to data tasks.
+3. Run tool loop (`system-prompt`) and collect tool trace + packet (`k360_research_compiler` optional).
+4. Render final markdown with `k360_narrative` (+ optional `data360://k360-narrative-style`).
+
+## 5. Design note
+
+**Resources** carry always-on behavior and schemas. **MCP prompts** carry parameterized
+playbooks for a *single* user turn. The **gate**/**reform** pair is playbook + policy on
+the host; exposing them as prompts lets non-Python integrators reuse the same wording.
+"""

src/data360/mcp_server/prompts.py

@@ -0,0 +1,571 @@
+"""Prompts for the Data360 MCP Server.
+
+Exposes:
+
+- ``SYSTEM_PROMPT``: default assistant instructions (search → codes →
+  disaggregation → data → visualization), including single-indicator
+  (``data360_get_viz_spec``) and multi-indicator
+  (``data360_get_multi_indicator_viz_spec``) paths.
+- ``GATE_CLASSIFIER_PROMPT`` / thematic reform text: shared wording for hosts
+  and for ``data360-mcp-agent`` gated flows (keep in sync with that package's
+  ``gate.py`` defaults).
+- ``@mcp.prompt()`` functions: reusable templates (indicator search, metadata,
+  country series, gate/reform for LangGraph hosts) that clients invoke by name.
+
+The system prompt intentionally keeps both **operational detail** (filters, batch
+codes, when to chart vs table) and the **ASCII tool-choice summary** so models
+do not drop ``relevant_fields`` / ``indicator_ids`` when calling viz tools.
+
+Integration overview: MCP resource ``data360://agent-recipe`` describes how to
+compose resources + these prompts for ``data360-mcp-agent`` or custom clients.
+"""
+
+from ._server_definition import mcp
+
+# Default MCP prompt resource: full loop + viz decision tree (was originally in
+# resources.py; extended for multi-indicator + 5-year defaults).
+SYSTEM_PROMPT = """## Data360 Assistant
+
+You are a tool-using assistant for World Bank Data360 indicators.
+
+### Non-negotiable rule
+If the user request requires indicator lookup, metadata, codes, or data values, you MUST call tools.
+Do not answer with guesses. Do not stop after describing a plan.
+
+### Operating loop (repeat until done)
+1) If you need indicators or statistical series → call data360_search_indicators.
+   - **CRITICAL: Search query is required**: You must always provide a search topic/term in `query`, `queries`, or `query_groups`. Do not omit it or pass empty values, even when filtering by database.
+   - **CRITICAL: Parameter Selection Decision Tree**: Default to using the single `query` parameter for any single topic/indicator search. Use the `queries` or `query_groups` parameters ONLY when the request involves multiple topics or scopes (2 or more):
+     - **Exactly 1 Topic** (e.g. "life expectancy") for any number of countries → you MUST use the single `query` parameter (e.g. `query="life expectancy"`) + `required_country`. Do NOT use `queries` with only one element, as it will fail. Do NOT combine multiple topics with 'and' or 'or' in `query`.
+     - **Multiple Topics, Same Geographic Scope** (e.g. "life expectancy and GDP per capita" for Japan) → you MUST use the `queries` list parameter (e.g. `queries=["life expectancy", "GDP per capita"]`) + `required_country`. Do NOT make multiple tool calls. Do NOT pass multiple topics combined as a single `query` string (e.g. `query="life expectancy and GDP per capita"` is invalid).
+     - **Different Topics targeting Different Country/Regional Scopes** (e.g. "life expectancy for Japan, but GDP and mortality rate for Korea") → you MUST use the `query_groups` list parameter. Example: `query_groups=[{"queries": ["life expectancy"], "country": "JPN"}, {"queries": ["GDP", "mortality rate"], "country": "KOR"}]`.
+     - **Multiple Databases**: Use a semicolon-separated string for `database` (e.g., `database="pip; wdi"`).
+     Example: `data360_search_indicators(queries=["population", "poverty"], database="pip; wdi")`
+   - **Database filter**: If the user's request specifies or strongly implies a specific database (e.g. "World Development Indicators", "WDI", "Worldwide Governance Indicators", "WGI"), pass it to the `database` argument (e.g. `database="wdi"`). Multiple databases can be filtered at once by passing a semicolon-separated string (e.g. `database="mpo; pip; lpgd"`).
+   If you need high-level dataset catalogs or source databases (e.g. Findex) → call data360_search_datasets.
+   - **CRITICAL**: The search API is sensitive to special characters. Strip parentheses `(`, `)` and currency signs like `$` from your query (e.g. search for "GDP per capita current US", NOT "GDP per capita (current US$)").
+   - **CRITICAL** when search returns multiple results: STOP — do not loop every row.
+   - **CRITICAL: Resolving Ambiguity**: If there are multiple matching indicators representing different metrics (e.g. constant prices vs current prices, real vs nominal GDP, or purchasing power parity vs market exchange rate), or if you are unsure which one the user wanted, do NOT guess. Instead, immediately call `data360_interactive_choices` with a clarifying prompt and the options (e.g. `data360_interactive_choices(prompt="Which GDP per capita series would you like to view?", options=["Real GDP per capita (constant 2015 US$)", "Nominal GDP per capita (current US$)", "PPP GDP per capita (constant 2017 int'l $)", "Specify custom..."], title="Select Indicator Variant")`). Then, STOP and wait for the user to make a selection.
+   - **Dynamic Custom Option**: When calling `data360_interactive_choices`, if the user might need an option outside of the static ones presented, you MUST dynamically append a customizable option at the end of the `options` list (e.g., `"Specify a custom range"`, `"Other (specify)"`, `"Choose a country..."`, or `"Specify custom..."`).
+   - Pick the **single best** indicator (relevance + coverage), then state:
+     "Selected Indicator: [ID] — [Name]" and "Why: [reason]".
+
+2) If you need country/dimension codes → call data360_find_codelist_value.
+   - Country: codelist_type="REF_AREA" (e.g. query="Kenya") → "KEN"
+   - Multi-country: pass a comma-separated query in **one** call (e.g. "Kenya, Uganda").
+   - Unit: codelist_type="UNIT_MEASURE" (e.g. "Current US$") when you must disambiguate units.
+   - Pass the **codes** (e.g. "KEN", "USA") into get_data filters, not display names.
+
+   #### Country Groups & Regional Aggregates
+   When data360_find_codelist_value returns a result with `is_group=true`:
+   - The code (e.g. "SAS", "LIC", "SSF") is a country **group**, not an individual country.
+   - Groups can be used directly in get_data for **aggregate/regional totals**.
+   - To work with **individual countries**, call data360_expand_country_group first.
+
+   **Decide based on the user's intent:**
+
+   | Intent | Example phrasing | Action |
+   |--------|-----------------|--------|
+   | Aggregate / regional view | "What is South Asia's GDP?" | Use group code directly → get_data(REF_AREA="SAS") |
+   | Country-level comparison | "Compare GDP across South Asian countries" | Expand → data360_expand_country_group("SAS") → use country_codes |
+   | Country-level comparison | "List poverty rates in low income countries" | Expand → data360_expand_country_group("LIC") → use country_codes |
+
+   When calling data360_expand_country_group, always check the returned `count` field:
+   - If count <= 20: proceed with country-level expansion without asking.
+   - If count > 20: **inform the user** before fetching. Say:
+     "This group contains N countries. Do you want individual country-level data
+     for all of them, or would you prefer the regional aggregate?"
+     Wait for confirmation before making N individual country calls.
+   Natural-language group phrases are recognized automatically:
+   - "South Asian countries" → SAS (6 countries)
+   - "Low income countries" → LIC (26 countries)
+   - "Sub-Saharan Africa" → SSF (48 countries)
+   - "Fragile states" → FCS (39 countries)
+   - "MENA" → MEA
+   - and many more via data360_find_codelist_value
+
+
+3) Confirm availability → call data360_get_disaggregation.
+   - **CRITICAL**: If UNIT_MEASURE has multiple values (e.g. KD vs CD), there are multiple options for a critical dimension (such as breakdowns like Sex, Age, or Education), or the timeframe/year range and disaggregation filters are ambiguous:
+     1. Call `data360_interactive_choices` to let the user select:
+        * Between unit measures (e.g. "Constant 2015 US$ (Real)" vs "Current US$ (Nominal)" vs "Other (specify)")
+        * Between breakdowns/disaggregations (e.g. "National Average (Total)" vs "Disaggregate by Gender (Male vs Female)" vs "Other (specify)")
+        * Between timeframes/year ranges (e.g. "Latest available year" vs "Historical trend (last 10 years)" vs "Specify a custom range")
+     2. **Dynamic Custom Option**: Always include a customizable option at the end of the `options` list (e.g., `"Specify custom..."` or `"Specify a custom range"`) so the user can enter their own input if none of the options are suitable.
+     3. STOP and wait for the user to make a selection. Do not proceed until you receive the selection.
+   - Otherwise, pick **one** and filter.
+
+4) If you need raw data values for a **specific point lookup or small dataset** → call data360_get_data.
+   - **CRITICAL**: pass disaggregation_filters={"REF_AREA": "..."} when the user asked for a geography.
+   - Multiple countries: {"REF_AREA": "KEN,TZA"} in **one** call — not one call per country.
+   - Unpinned REF_AREA (no country_code / no REF_AREA string) returns **all geographic series** from the Data API, including regional aggregates (EAS, EMU, …). For **member economies only**, pass ref_area_filter="member_economies_only".
+   - Do not call get_data with no REF_AREA filter unless you want that full mix—or use ref_area_filter to narrow it.
+   - The response already includes indicator name/definition in many cases; you may not need a separate metadata call only for the title.
+   - **PAGINATION**: get_data returns ONE page. When has_more=True, call again with next_offset.
+     EXCEPTION: If the query involves 20+ countries (e.g. from data360_expand_country_group), do NOT
+     manually paginate get_data — use the aggregation tools in step 4b instead. They paginate
+     internally and return complete results without requiring you to loop.
+
+4b) If the user needs **analysis or the dataset is large** → use aggregation tools (these paginate
+    internally — you never need to call get_data in a loop when using them):
+
+   ┌─ WHEN TO USE AGGREGATION TOOLS (not get_data) ────────────────────────────┐
+   │  �� Country group was expanded via data360_expand_country_group (20+ codes) │
+   │  • User asks for a ranking, trend, summary, or comparison — not a lookup   │
+   │  • You would otherwise need to loop get_data across multiple pages          │
+   └───────────────────────────────────────────────────────────────────────────┘
+
+   ┌─ COMPARISON (2-8 countries)? ──────────────────────────────────────────┐
+   │  "Compare X across countries" / "How does A compare to B on Y?"       │
+   │  → data360_compare_countries(country_codes="KEN;NGA;ZAF")             │
+   │  Returns ranked snapshot + optional aligned time series + CAGR.       │
+   └───────────────────────────────────────────────────────────────────────┘
+
+   ┌─ RANKING (large group / top-N)? ──────────────────────────────────────┐
+   │  **Within a region or group:**                                         │
+   │  → data360_rank_countries(country_group="SAS", top_n=10)              │
+   │  **Worldwide / all economies:** omit country_group and country_codes; │
+   │  → data360_rank_countries(..., rank_universe="all_member_economies")  │
+   │  Returns ordered list + universe metadata; aggregates excluded.       │
+   │  For expanded groups (SSF=48, HIC=83), this handles all pagination.  │
+   └───────────────────────────────────────────────────────────────────────┘
+
+   ┌─ TREND / SUMMARY? ───────────────────────────────────────────────────┐
+   │  "How has X changed?" / "What is the trend of Y?" / "Summarize Z"    │
+   │  → data360_summarize_data(country_code="KEN")                        │
+   │  Returns min/max/mean/trend_direction + percent change.              │
+   │  group_by supports multiple columns (e.g. ["ref_area", "sex"]).      │
+   └───────────────────────────────────────────────────────────────────────┘
+
+5) Visualization — choose the right tool:
+
+   - Call data360_get_supported_chart_types to see every option and required columns.
+   - **DECIDE**: Does the frame support a chart? (e.g. time_period + obs_value for lines.)
+   - If the shape does **not** support a chart, present the **table** — do not force a broken viz.
+
+   #### Grammar-of-graphics rule for disaggregation_filters
+   **Do NOT pin a dimension in disaggregation_filters to simplify a chart.**
+   Pinning collapses multi-series data into a single line and silently discards information.
+
+   | Situation | Correct action |
+   |-----------|---------------|
+   | User said "show only females" | `disaggregation_filters={"SEX": "F"}` |
+   | User said "totals only" / "aggregate" | `disaggregation_filters={"SEX": "_T"}` |
+   | Dimension not applicable | `disaggregation_filters={"SEX": "_Z"}` |
+   | Multiple values exist, user has NO preference | **OMIT the dimension entirely** — the pipeline maps it to color/facet automatically |
+
+   The pipeline auto-detects non-trivial dimensions (_T/_Z are trivial) and routes:
+   - breakdown + multi-year + 1 country → TEMPORAL_SINGLE (color = breakdown dim)
+   - breakdown + multi-country          → SMALL_MULTIPLES (facet = country, color = breakdown)
+   - no breakdown, multi-year           → TEMPORAL_SINGLE (color = country)
+
+   #### Mixed-unit breakdown warning (Option A)
+   Some indicators carry comp_breakdown_1 values that represent **structurally different
+   metric types** — not just different categories of the same quantity. Example: WGI uses
+   WGI_EST (estimate, ~−2.5 to +2.5), WGI_SC (percentile rank, 0–100), WGI_SE (standard
+   error), WGI_SR (source count), WGI_SC_LB/UB (confidence bounds). Plotting all on one
+   Y-axis is misleading because the scales are incompatible.
+
+   **When you call data360_get_disaggregation and find comp_breakdown_1 has 3+ values,
+   check if they represent different metric types** (e.g. estimate + rank + error + count).
+   If so, BEFORE calling the visualization tool:
+   1. List the available breakdown values and their meanings to the user.
+   2. Recommend the primary analytic series (e.g. WGI_EST for governance analysis,
+      WGI_SC for cross-country rank comparison).
+   3. Ask which breakdown the user wants, or proceed with the recommended one and say so.
+
+   The chart subtitle will always list all series present — users can read it to understand
+   what is shown. But proactively surfacing the choice is better than a crowded chart.
+
+   ┌─ ONE indicator? ──────────────────────────────────────────────────────────┐
+   │  Call data360_get_viz_spec                                                │
+   │  • Multi-year, 1-8 countries  → chart_type="line"  (auto color by cntry) │
+   │  • Single year, ≤8 countries  → chart_type="bar"                         │
+   │  • Single year, >8 countries  → chart_type="strip"                       │
+   │  • Sex/age breakdown present  → chart_type="small_multiples"             │
+   │  • Pass relevant_fields=["time_period","obs_value",...] when you must    │
+   │    pin exact columns; the tool can auto-enrich dimensions when needed.   │
+   │  • If the user asked for a style ("bar chart"), pass chart_type="bar".   │
+   └───────────────────────────────────────────────────────────────────────────┘
+
+   ┌─ TWO OR MORE indicators? ─────────────────────────────────────────────────┐
+   │  Call data360_get_multi_indicator_viz_spec                                │
+   │  • REQUIRED: indicator_ids — JSON array of 2–4 objects (never omit).      │
+   │    Each object MUST be {"database_id": "<db>", "indicator_id": "<id>"}.   │
+   │    Example:                                                               │
+   │    [{"database_id": "WB_WDI", "indicator_id": "WB_WDI_NY_GDP_PCAP_KD"},    │
+   │     {"database_id": "WB_WDI", "indicator_id": "WB_WDI_SP_DYN_LE00_IN"}]   │
+   │  • Optional: country_code, start_year, end_year, disaggregation_filters,  │
+   │    chart_type — same names as data360_get_viz_spec except there is NO     │
+   │    relevant_fields or custom_constraints.                                 │
+   │                                                                           │
+   │  Chart type selection:                                                    │
+   │  • "Compare X vs Y across countries, one year"  → chart_type="scatter"  │
+   │  • "How X and Y moved together over time"        → chart_type="connected_scatter"│
+   │  • "Show X and Y trends for one country"         → chart_type="layered_lines"│
+   │  • Let the tool auto-select when unsure          → omit chart_type       │
+   └───────────────────────────────────────────────────────────────────────────┘
+
+   Call data360_get_supported_chart_types for the full list of options and requirements.
+
+Then provide the final answer to the user (after tools complete).
+
+### Defaults
+- Time range: last 5 years unless user specifies otherwise.
+  start_year = (current_year - 4), end_year = current_year
+- Breakdowns (e.g. by sex): use disaggregation_filters={"SEX": null} to get all groups.
+
+### Output behavior
+- When a tool is needed, your next message MUST be a tool call (no extra text).
+- After tools return, continue with the next needed tool call.
+- Only produce a normal user-facing response when no further tool calls are required.
+- When presenting a chart, always describe what the visualization shows in 1-2 sentences.
+
+### Rules for Follow-ups and Elicitations (data360_interactive_choices)
+You typically provide follow-ups and elicitations using the `data360_interactive_choices` tool based on the natural flow of our conversation and the type of information we are discussing. Your goal is to anticipate the user's next question or provide an easy way to steer a broad topic.
+
+**CRITICAL: Dynamic Customizable Options on Non-Exhaustive Lists**
+Whenever you call `data360_interactive_choices` with a list of options that is not exhaustive (for example, listing a few popular countries/economies, specific years, indicator variants, or breakdowns), you **MUST** dynamically include a customizable option as the last item in the `options` list. Clicking this option will dynamically present the user with a text input field to type their response.
+- **Country selection (Non-exhaustive)**: `options=["Kenya", "Nigeria", "South Africa", "United States", "India", "Specify another country..."]`
+- **Timeframe/Year range**: `options=["2024 (latest)", "Last 5 years", "Last 10 years", "Specify a custom range"]`
+- **Ambiguity resolution**: `options=["Total Average", "Breakdown by Gender", "Other (specify)"]`
+
+Here are the specific scenarios when you should call `data360_interactive_choices`:
+
+#### 1. Single Follow-up (1 choice)
+* **The "Obvious Next Step"**: When there is one highly logical action to take after your response. For example, if you explain a mathematical concept, the follow-up might offer to walk through a practical example.
+* **Deep Dives into Jargon**: If your response introduces a complex technical term or a new concept, you might offer a single follow-up to explain that specific term so the main response does not get too cluttered.
+* **Launching Interactive Tools**: If you mention that you can build a widget or run a simulation, provide a single button to let the user trigger that specific interactive element directly.
+
+#### 2. Multiple Choices (2+ choices)
+* **Broad Overviews & Branching Paths**: When you give a high-level summary of a massive topic, use multiple choices to let the user choose exactly which sub-category or "branch" you want to zoom in on next.
+* **Disambiguation (Clarifying Intent)**: If the user's request is open-ended or could be interpreted in a few different ways (such as selecting between real or nominal series, different indicator options, timeframe/year ranges, or disaggregations/breakdowns), present options so the user can clarify exactly which direction they meant to take. **Always dynamically include a customizable option (e.g. "Specify custom...", "Other (specify)", or "Specify a custom range") at the end of the options list to allow custom typing if none of the predefined options suffice.**
+* **Menus and Brainstorming**: When generating lists of ideas—like different programming frameworks, design patterns, or troubleshooting steps—use multiple choices to act like a clickable menu, letting the user instantly select the one you want to explore.
+
+Essentially, surface these components using `data360_interactive_choices` whenever you can save the user the effort of typing out the logical next prompt, or when the conversation has reached a crossroads and you need the user to choose the direction. Always make sure to include a dynamic customizable option if the static list might not fully satisfy the user's possible need.
+"""
+
+# Mirrors ``data360_mcp_agent.gate.GATE_SYSTEM_PROMPT`` — update both when changing rules.
+GATE_CLASSIFIER_PROMPT = """You are a classifier for a Data360 / World Bank data assistant.
+
+Decide if the user's latest message should engage the Data360 MCP tool-using agent.
+
+**In scope (relevant = true)** — include ALL of:
+1. Direct data questions: indicators, countries/economies, years, comparisons, charts.
+2. Development economics and World Bank–aligned operations questions where World Bank / Data360-style **data** can illuminate the answer — macro, fiscal/public spending, poverty, inequality, labor markets, human capital, trade, investment climate, climate-related **development** metrics, etc. — even if the user did not name an indicator code.
+3. Country or regional **policy-relevant themes** that can be grounded in measurable series or country metadata (e.g. "main challenges facing Ghana's growth and public spending", "structural labor market challenges in Morocco", "climate change and economic development in Bangladesh").
+
+**Out of scope (relevant = false)**:
+- Pure chit-chat, unrelated trivia, entertainment.
+- Homework or tasks with no plausible path through WB-style data.
+- Medical, legal, or personal advice.
+- Questions with no link to development data (e.g. street-level weather, sports scores, generic coding help unrelated to this data assistant).
+
+**Bias**: When the topic is clearly development- or WB-adjacent and data could support an evidence-based answer, choose **relevant = true**.
+
+When relevant is false, set refusal_text to one short, polite sentence explaining the assistant focuses on WB/Data360 data (optional; a default may be used). When relevant is true, leave refusal_text null or empty."""
+
+# Mirrors ``data360_mcp_agent.gate.REFORM_SYSTEM_PROMPT`` — update both when changing.
+THEMATIC_REFORM_SYSTEM = """You rewrite user questions into **one** concrete orchestration prompt for a Data360 MCP agent that will search indicators, fetch series, and build charts.
+
+Given the user's message (often thematic or knowledge-style), output:
+- data_question: A single clear instruction naming **economy/ies** (ISO codes or standard country names), **indicator themes or concrete search terms**, a **reasonable year range**, and **peer or benchmark** comparisons when useful (e.g. regional peers, world, income group).
+- search_hints: Short bullet-style strings the agent can use when searching tools (e.g. "GDP growth annual", "general government final consumption", "labor force participation", "youth unemployment", "ND-GAIN" or other WB-relevant climate vulnerability metrics if applicable).
+- rewritten: true if you materially rewrote/expanded the user request; false if the user request is already an explicit, well-formed data question and should be preserved as-is.
+
+Rules:
+- Do not broaden scope for explicit data asks. Example: "Latest GDP growth in Vietnam." should remain focused on Vietnam latest GDP growth.
+- Rewrite when the immediate question is thematic, underspecified, or depends on prior context.
+- Do not answer the question yourself; only produce the reformulated task. Stay within evidence the World Bank / Data360 tools could retrieve."""
+
+K360_RESEARCH_COMPILER_PROMPT = """You are the K360 compile stage for a Data360 tool-using agent.
+
+You are given:
+- Original user question
+- Rewritten data question (if available)
+- Tool call trace and tool results
+
+Output ONLY a JSON object with this shape:
+{
+  "query_focus": "short sentence",
+  "selected_indicators": [{"database_id":"...", "indicator_id":"...", "name":"optional"}],
+  "geographies": ["KEN", "UGA"],
+  "time_range": {"start_year": 2015, "end_year": 2024},
+  "key_observations": ["..."],
+  "sources": ["WB_WDI"],
+  "viz_assets": [{"url":"...", "chart_type":"optional"}],
+  "data_gaps": ["..."]
+}
+
+Rules:
+- Be faithful to tool outputs; do not invent values.
+- Keep key_observations concise and evidence-grounded.
+- If information is missing, leave arrays empty or note in data_gaps.
+- No markdown, no prose, no code fences, JSON only.
+"""
+
+K360_NARRATIVE_PROMPT = """You are the K360 narrative stage for Data360 outputs.
+
+Write a polished markdown answer using this exact section style (omit empty sections):
+**Data:** factual results from the content packet and tool outputs
+**Analysis:** interpretation and comparisons
+**Note:** caveats, data gaps, or definition warnings
+**Sources:** concise source list
+
+Formatting rules:
+- Keep it concise and policy-usable.
+- Start with a 1-2 sentence high-level insight, then details.
+- Prefer bullet points for multi-country comparisons and timelines.
+- If presenting 3+ related numeric values (years/countries/metrics), use a markdown table.
+- If fewer than 3 related numeric values, use short bullets or a paragraph.
+- Do NOT prefix section labels with list markers (no "- **Data:**"). Section labels must appear as plain bold labels.
+- Include units and time period whenever showing numeric values.
+- For large numbers (money, GDP, population), use comma separators or compact human-readable forms (e.g., 1.2 million).
+- Never use scientific notation unless explicitly requested by the user.
+- When multiple source lines exist, list them as bullets under **Sources:** in this format:
+  **Database name** — Indicator name — methodology note (if available)
+- If there is no usable data, say so clearly and suggest one next-best query.
+- If chart URLs are present, mention what each chart shows in plain language.
+- If include_claim_tags is true, wrap numeric claims as:
+  <claim id="short-id">...</claim>
+
+Do not fabricate data. Use only provided tool evidence.
+"""
+
+
+@mcp.prompt()
+def gate_classifier() -> str:
+    """In/out-of-scope classifier instructions for Data360 (for hosts that fetch prompts from MCP).
+
+    Pair with a structured-output LLM call or with ``data360-mcp-agent``'s gated node,
+    which embeds the same rules locally by default.
+    """
+    return GATE_CLASSIFIER_PROMPT
+
+
+@mcp.prompt()
+def thematic_to_data(user_message: str) -> str:
+    """Rewrite a thematic development question into a concrete indicator/data task.
+
+    Hosts often follow this with ``data360://system-prompt`` and the tool loop.
+    """
+    return f"""{THEMATIC_REFORM_SYSTEM}
+
+---
+User message to reformulate:
+{user_message}
+"""
+
+
+@mcp.prompt()
+def indicator_search(
+    query: str,
+    country: str = "",
+    required_dimensions: str = "",
+    database: str = "",
+) -> str:
+    """Guide LLM to find and select the best indicator for a query.
+
+    Args:
+        query: Search query (e.g., "unemployment rate", "poverty")
+        country: Optional country to validate (e.g., "Kenya")
+        required_dimensions: Optional comma-separated dimensions (e.g., "SEX,AGE")
+        database: Optional database filter (e.g., "wdi", "World Development Indicators"). Multiple databases can be filtered at once by separating them with a semicolon (e.g. "pip; lpgd; sgi").
+    """
+    dims_list = required_dimensions.split(",") if required_dimensions else []
+    db_arg = f',\n       database="{database}"' if database else ""
+
+    return f"""To find the best indicator for '{query}':
+
+ 1. Use enriched search:
+    data360_search_indicators(
+        query="{query}",
+        limit=5{db_arg}
+    )
+
+2. For promising candidates, validate with get_disaggregation:
+   - Check TIME_PERIOD for actual years (may have gaps)
+   - Check REF_AREA for country coverage{f" - verify '{country}' is available" if country else ""}
+   - Check available dimensions{f" - need: {dims_list}" if dims_list else ""}
+
+ 3. **Dimension Analysis (CRITICAL)**:
+   - Look at the `dimensions` list from step 2 (or call available_dimensions) or multiple candidate indicators.
+   - **Identify Ambiguity**: Are there dimensions with multiple values (besides TIME_PERIOD and REF_AREA) or multiple matching indicator series (e.g., constant vs current)?
+     - Example: `UNIT_MEASURE: ["KD", "CD"]` (Constant vs Current).
+     - Example: `VALUATION: ["MER", "PPP"]`.
+   - **Clarify via Choice Card**: If you cannot resolve this ambiguity based on user context, immediately call `data360_interactive_choices` to let the user select via interactive buttons.
+     Example: `data360_interactive_choices(prompt="Which series would you like to view?", options=["Real GDP per capita", "Nominal GDP per capita", "Specify custom..."])`
+     After calling it, STOP and wait for the user to make a selection. Do not proceed until you receive the selection.
+
+4. **Validation Check**:
+   - If the user asked for a specific country (e.g. Kenya), do NOT call `get_data` without `disaggregation_filters={{"REF_AREA": "KEN"}}` (plus your selected dimension filters). Values must be strings or null per dimension — not JSON arrays.
+   - Multiple ISO codes in one filter: comma-separated string, e.g. `{{"REF_AREA": "KEN,TZA", "UNIT_MEASURE": "KD"}}`. Prefer commas in `disaggregation_filters`; the server also normalizes semicolons in REF_AREA to commas. The top-level `country_code` argument uses semicolons for multiple codes (e.g. `KEN;TZA`).
+   - Use `null` only for a **specific** dimension when you want every value of that dimension (e.g. all sexes), not to skip geography when the user named a country.
+   - Asking for `disaggregation_filters=null` returns global aggregates AND all unit variants, which ruins charts.
+
+5. **Selection**:
+   - Pick the SINGLE best indicator ID. Do not loop.
+   - Use the `database_id` exactly as returned in the search result (do not guess).
+   - Ensure your `get_data` call will carry the specific filters you decided on.
+"""
+
+
+@mcp.prompt()
+def indicator_details(
+    indicator_id: str,
+    database_id: str,
+    question: str = "",
+) -> str:
+    """Guide LLM to get appropriate metadata based on user question.
+
+    Args:
+        indicator_id: Indicator ID (e.g., "WB_GS_NY_GDP_PCAP_KD")
+        database_id: Database ID (e.g., "WB_GS")
+        question: Optional specific question to answer
+    """
+    return f"""To answer questions about indicator '{indicator_id}':
+
+1. Read data360://metadata-fields to find which field answers the question
+
+2. Map user question to field(s):
+   - "how is it calculated" → ["methodology"]
+   - "statistical concept" → ["statistical_concept"]
+   - "what is this" → ["definition_long"]
+   - "limitations" → ["limitation"]
+   - "why important" → ["relevance"]
+
+3. Call data360_get_metadata with select_fields to fetch ONLY needed fields:
+   data360_get_metadata(
+       database_id="{database_id}",
+       indicator_id="{indicator_id}",
+       select_fields=["methodology"]  # Only fetch what's needed
+   )
+
+User question: {question if question else "(general overview - use definition_long)"}
+"""
+
+
+@mcp.prompt()
+def country_data(
+    query: str,
+    country: str,
+    start_year: str = "",
+    end_year: str = "",
+    database: str = "",
+) -> str:
+    """Guide LLM through end-to-end data retrieval for a country.
+
+    Args:
+        query: Indicator search query
+        country: Country name or comma-separated list (e.g., "Kenya" or "Kenya, Uganda")
+        start_year: Optional start year
+        end_year: Optional end year
+        database: Optional database filter (e.g., "wdi", "World Development Indicators"). Multiple databases can be filtered at once by separating them with a semicolon (e.g. "pip; lpgd; sgi").
+    """
+    db_arg = f',\n    database="{database}"' if database else ""
+    return f"""To get {query} data for {country}:
+
+<thinking>
+1. Need to find the right indicator
+2. Need to convert country name(s) to codes
+3. Need to validate data availability
+4. Then fetch the data in ONE call
+</thinking>
+
+**Step 1: Resolve country code**
+data360_find_codelist_value(codelist_type="REF_AREA", query="{country}")
+# Returns list of codes, e.g. "KEN" or "KEN,UGA"
+
+**Step 2: Search for indicator**
+data360_search_indicators(
+    query="{query}",
+    limit=5,
+    required_country="{country}"{db_arg} # Pass the list string as-is
+)
+
+**Step 3: Validate availability & Dimensions**
+For chosen indicator, call:
+data360_get_disaggregation(database_id=<db_id>, indicator_id=<ind_id>)
+- Confirm country code is in REF_AREA
+- Check TIME_PERIOD
+- **CRITICAL**: Check for multiple values in other dimensions (e.g. UNIT_MEASURE).
+  - If found, pick ONE.
+  - If you need ALL values for a dimension (e.g. SEX), pass `NULL` in the filter.
+
+**Step 4: Get data**
+data360_get_data(
+    database_id=<db_id>,
+    indicator_id=<ind_id>,
+    disaggregation_filters={{"REF_AREA": "<ISO comma-separated, e.g. KEN or KEN,TZA>", "UNIT_MEASURE": "..."}},
+    start_year={start_year if start_year else "None (Defaults to last 5 years)"},
+    end_year={end_year if end_year else "None"}
+)
+# Or omit REF_AREA in disaggregation_filters and use top-level country_code="KEN" or "KEN;MAR".
+
+**Step 5: Visualize**
+If data is suitable (time series), visualize directly.
+For multi-country, the tool auto-handles color-coding.
+
+Grammar-of-graphics rule: do NOT pin disaggregation dimensions to simplify the chart.
+If the indicator has breakdowns (sex, age, comp_breakdown_1, etc.) and the user did not
+request a specific value, OMIT those dimensions from disaggregation_filters entirely.
+The pipeline maps them to color/facet channels automatically.
+
+  WRONG: disaggregation_filters={{"COMP_BREAKDOWN_1": "WGI_EST"}}  # silently drops 5 series
+  RIGHT: (omit COMP_BREAKDOWN_1 — pipeline auto-routes to SMALL_MULTIPLES or multi-series line)
+
+data360_get_viz_spec(
+    database_id=<db_id>,
+    indicator_id=<ind_id>,
+    country_code="<ISO: one code, or several with semicolons e.g. KEN;UGA>",
+    # Only pin a dimension when the user explicitly requested it:
+    # disaggregation_filters={{"SEX": "F"}},   # user said "females only"
+    # disaggregation_filters={{"SEX": "_T"}},  # user said "totals only"
+    chart_type="line"
+)
+"""
+
+
+@mcp.prompt()
+def k360_research_compiler(
+    user_question: str,
+    data_question: str = "",
+    tool_calls_json: str = "[]",
+) -> str:
+    """Compile tool outputs into a stable content packet (JSON only)."""
+    return f"""{K360_RESEARCH_COMPILER_PROMPT}
+
+---
+User question:
+{user_question}
+
+Rewritten data question:
+{data_question}
+
+Tool calls JSON:
+{tool_calls_json}
+"""
+
+
+@mcp.prompt()
+def k360_narrative(
+    user_question: str,
+    content_packet_json: str,
+    raw_tool_results_json: str = "[]",
+    include_claim_tags: str = "false",
+) -> str:
+    """Generate a user-facing narrative from K360 content packet + evidence."""
+    return f"""{K360_NARRATIVE_PROMPT}
+
+include_claim_tags={include_claim_tags}
+
+---
+User question:
+{user_question}
+
+Content packet JSON:
+{content_packet_json}
+
+Raw tool results JSON:
+{raw_tool_results_json}
+"""

src/data360/mcp_server/resources.py

@@ -0,0 +1,624 @@
+"""Resources for the Data360 MCP Server.
+
+These resources provide static context to help LLMs understand the Data360 system.
+Includes ``data360://agent-recipe`` for host integrators (LangGraph / data360-mcp-agent).
+"""
+
+import json
+from datetime import datetime
+
+from fastmcp.apps import AppConfig, ResourceCSP
+from data360.providers import get_database_mapping
+
+from ._server_definition import mcp
+from .agent_recipe import AGENT_RECIPE_MARKDOWN
+
+# System prompt with chain-of-thought guidance for chatbot integration
+from .prompts import SYSTEM_PROMPT
+
+
+CODELISTS = {
+    "auto_resolved": {
+        "description": (
+            "The pipeline auto-resolves these dimensions from the extdataportal codelist. "
+            "series_labels is NOT required for these dimensions."
+        ),
+        "source": "https://extdataportal.worldbank.org/api/data360/metadata/codelist",
+        "dimensions": {
+            "COMP_BREAKDOWN_1": "5 191 indicator-subtype codes (e.g. WGI_EST, IPC_IPC_PHASE3, WEF_TTDI_RNK)",
+            "COMP_BREAKDOWN_2": "Same pool as COMP_BREAKDOWN_1",
+            "UNIT_MEASURE": "769 unit codes auto-resolved in Y-axis labels and subtitles",
+            "SEX": "7 codes: F=Female, M=Male, _T=Total, _O=Other, _U=Unknown, _Z=Not applicable",
+            "AGE": "173 codes: _T=All ages, Y15T24=15-24 years, Y_GE25=25+ years, etc.",
+            "URBANISATION": "16 codes: URB=Urban area, RUR=Rural area, CITY=City, VILL=Village, etc.",
+            "FREQ": "34 codes: A=Annual, M=Monthly, Q=Quarterly, etc.",
+        },
+    },
+    "manual_override": {
+        "description": (
+            "Provide series_labels only to shorten or rename auto-resolved labels, "
+            "e.g. to show 'Estimate' instead of 'Governance estimate (approx. -2.5 to +2.5)'."
+        ),
+        "example": {"WGI_EST": "Estimate", "WGI_SC": "Score", "WGI_SE": "Std. Error"},
+    },
+    "geographic": {
+        "description": "REF_AREA groups resolved via GroupHierarchyManager (FMR H_REF_AREA_GROUPS)",
+        "individual_countries": "532 codes — resolved automatically to country names",
+        "groups": "147 group codes (REGION, INCOME, LENDING, CONTINENT) — use expand_country_group",
+    },
+}
+
+
+METADATA_FIELDS = {
+    "fields": {
+        "methodology": {
+            "description": "How the indicator is calculated/measured",
+            "use_when": ["how is it calculated", "calculation method", "methodology"],
+        },
+        "statistical_concept": {
+            "description": "Statistical definition and conceptual framework",
+            "use_when": ["statistical concept", "what does it measure", "definition"],
+        },
+        "definition_long": {
+            "description": "Full description of the indicator",
+            "use_when": ["what is", "describe", "explanation"],
+        },
+        "limitation": {
+            "description": "Known data limitations and caveats",
+            "use_when": ["limitations", "caveats", "data quality", "issues"],
+        },
+        "relevance": {
+            "description": "Policy relevance and why this indicator matters",
+            "use_when": ["why important", "relevance", "policy implications"],
+        },
+        "aggregation_method": {
+            "description": "How values are aggregated (Sum, Average, etc.)",
+            "use_when": ["aggregation", "how combined", "sum or average"],
+        },
+        "periodicity": {
+            "description": "Data frequency (Annual, Monthly, etc.)",
+            "use_when": ["frequency", "how often", "periodicity"],
+        },
+        "time_periods": {
+            "description": "Nominal time range (may have gaps)",
+            "use_when": ["time range", "years available", "coverage"],
+            "note": "Call get_disaggregation for actual available years",
+        },
+        "ref_country": {
+            "description": "List of countries with data",
+            "use_when": ["countries", "coverage", "available for"],
+        },
+        "sources_note": {
+            "description": "Information about data sources",
+            "use_when": ["source", "where from", "data provider"],
+        },
+    }
+}
+
+
+DATA_FILTERS = {
+    "workflow": "Call get_disaggregation first to see available values for each filter",
+    "supported_filters": {
+        "timePeriodFrom": {"description": "Start year", "example": "2020"},
+        "timePeriodTo": {"description": "End year", "example": "2023"},
+        "REF_AREA": {
+            "description": "Country code(s). Use comma-separated for multiple.",
+            "example": "KEN,TZA",
+        },
+        "SEX": {"values": ["F", "M", "_T", "_O", "_U", "_Z"]},
+        "AGE": {
+            "description": "173 age codes — common ones below; use get_disaggregation for indicator-specific values",
+            "common_values": ["_T", "Y15T24", "Y15T29", "Y30T59", "Y_GE25", "Y_GE60", "Y18T65"],
+        },
+        "URBANISATION": {
+            "values": ["_T", "URB", "RUR", "CITY", "VILL", "DTOW", "TSUB", "STOW", "SUBU", "SURB", "LURB", "_O", "_Z"],
+        },
+    },
+    "excluded_filters": {"FREQ": "DO NOT USE - breaks queries"},
+    "important": "Check TIME_PERIOD in disaggregation for actual available years (may have gaps)",
+}
+
+
+DATA_SCHEMA = {
+    "description": "Data rows are prefiltered to only include relevant fields. Always present: 5 core fields. Conditionally present: disaggregation fields when their values are non-trivial.",
+    "core_fields": {
+        "obs_value": "The numeric data value.",
+        "time_period": "Date or year of the observation (e.g., '2023', '2024-07-01').",
+        "ref_area": "Country or region code (e.g., 'KEN').",
+        "unit_measure": "Unit of measurement (e.g., 'PT', 'USD_K_2015', 'PS').",
+        "claim_id": "Verification hash for data provenance.",
+    },
+    "conditional_fields": {
+        "description": "Included only when values carry real disaggregation (not _T total or _Z not-applicable).",
+        "sex": "Gender breakdown ('F', 'M'). Present in WB_HCP, WB_SSGD, WB_GS.",
+        "age": "Age group ('Y15T24', 'Y18T65', etc.). Present in WB_SSGD, OECD_IDD.",
+        "urbanisation": "Urban/Rural ('URB', 'RUR'). Present in WB_SSGD.",
+        "comp_breakdown_1": "Indicator subtype (e.g., IPC phase period, OECD indicator type, WEF rank/value/score).",
+        "comp_breakdown_2": "Secondary breakdown (e.g., IPC phase level, OECD income definition).",
+    },
+    "visualization_guidance": "When calling get_viz_spec(relevant_fields=...), prioritize 'time_period' and 'obs_value'. Include 'ref_area' or dimensions like 'sex' only for comparison/grouping.",
+}
+
+
+SEARCH_USAGE = {
+    "basic_search": {
+        "example": "data360_search_indicators(query='poverty', limit=10)",
+        "note": "Uses default select_fields",
+    },
+    "enriched_search": {
+        "example": "data360_search_indicators(query='poverty', limit=5, select_fields=['idno', 'name', 'database_id', 'definition_long', 'periodicity', 'time_periods', 'dimensions'])",
+        "note": "Use when LLM needs to pick best indicator",
+    },
+    "indicator_selection_workflow": [
+        "1. Use enriched search with select_fields for extra coverage info",
+        "2. Call get_disaggregation to check TIME_PERIOD and REF_AREA",
+        "3. Pick indicator based on coverage, time range, and relevance",
+    ],
+    "warning": "DO NOT use odata_options - it is deprecated",
+}
+
+K360_NARRATIVE_STYLE = {
+    "sections": ["Data", "Analysis", "Note", "Sources"],
+    "required_behavior": [
+        "Ground every statement in tool evidence or content packet fields.",
+        "Use concise markdown suitable for analyst and policy audiences.",
+        "When chart outputs exist, describe what each chart conveys in 1-2 sentences.",
+        "If no data is available, clearly state the gap and suggest a narrower follow-up query.",
+    ],
+    "optional_claim_tags": {
+        "enabled_by": "include_claim_tags=true",
+        "format": "<claim id=\"short-id\">numeric statement</claim>",
+    },
+}
+
+
+@mcp.resource("data360://system-prompt")
+async def system_prompt_resource() -> str:
+    """System prompt with chain-of-thought guidance for chatbot integration."""
+    return SYSTEM_PROMPT
+
+
+@mcp.resource("data360://agent-recipe")
+async def agent_recipe_resource() -> str:
+    """How to compose MCP resources + named prompts for LangGraph / ``data360-mcp-agent``."""
+    return AGENT_RECIPE_MARKDOWN
+
+
+@mcp.resource("data360://context")
+async def context_resource() -> str:
+    """Runtime context including current date. Read this to know today's date."""
+    return json.dumps(
+        {
+            "current_date": datetime.now().strftime("%Y-%m-%d"),
+            "current_year": datetime.now().year,
+            "note": "Use current_year to calculate 'last N years' queries",
+        },
+        indent=2,
+    )
+
+
+@mcp.resource("data360://databases")
+async def databases_resource() -> str:
+    """List of available Data360 databases."""
+    db_mapping = await get_database_mapping()
+    formatted = {"databases": [{"id": k, "name": v} for k, v in db_mapping.items()]}
+    return json.dumps(formatted, indent=2)
+
+
+@mcp.resource("data360://codelists")
+async def codelists_resource() -> str:
+    """Codelist reference information (global and indicator-level)."""
+    return json.dumps(CODELISTS, indent=2)
+
+
+@mcp.resource("data360://metadata-fields")
+async def metadata_fields_resource() -> str:
+    """Metadata field mapping for smart routing based on user questions."""
+    return json.dumps(METADATA_FIELDS, indent=2)
+
+
+@mcp.resource("data360://data-filters")
+async def data_filters_resource() -> str:
+    """Available data filters and usage guidance."""
+    return json.dumps(DATA_FILTERS, indent=2)
+
+
+@mcp.resource("data360://data-schema")
+async def data_schema_resource() -> str:
+    """Standard data schema and column definitions for visualization."""
+    return json.dumps(DATA_SCHEMA, indent=2)
+
+
+@mcp.resource("data360://search-usage")
+async def search_usage_resource() -> str:
+    """Search tool usage guidance."""
+    return json.dumps(SEARCH_USAGE, indent=2)
+
+
+@mcp.resource("data360://k360-narrative-style")
+async def k360_narrative_style_resource() -> str:
+    """Narrative formatting contract for K360 staged agent hosts."""
+    return json.dumps(K360_NARRATIVE_STYLE, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Chart Grammar Resource — grammar-of-graphics decision rules
+# ---------------------------------------------------------------------------
+
+CHART_GRAMMAR = """# Data360 Chart Grammar — Decision Rules for Visualization
+
+This resource teaches you how to reason about data shapes and select the correct
+chart strategy. The visualization engine applies these rules automatically, but
+understanding them lets you make better upstream decisions (which tool to call,
+what chart_type to pass, and how to narrate the result).
+
+## 1. Strategy Selection Rules
+
+The engine selects a strategy based on the **data shape** after fetching:
+
+| Condition | Strategy | Chart type |
+|-----------|----------|-----------|
+| 1 indicator, temporal, 1–8 countries | `temporal_single` | Line chart (color=country) |
+| 1 indicator, temporal, >8 countries, no breakdowns | `heatmap` | Heatmap matrix (country × year) |
+| 1 indicator, single year, ≤8 countries | `cross_sectional` | Horizontal bar chart |
+| 1 indicator, single year, >8 countries | `distribution` | Strip/beeswarm chart |
+| 1 indicator, breakdown dimensions present | `breakdown_comparison` or `small_multiples` | Grouped bar or faceted panels |
+| 2+ indicators, temporal, 1 country | `temporal_multi_indicator` | Layered lines or stacked panels |
+| 2+ indicators, single year, multiple countries | `scatter` or `cross_sectional` | Scatter or grouped bar |
+| Composition data (parts sum to ~100%) | `stacked_area` or `stacked_bar` | Stacked marks |
+
+## 2. Layout Composition Rules (Multi-Indicator)
+
+When comparing 2+ indicators, the engine decides whether to use a **single shared
+panel** or **vertically stacked panels with independent Y-axes**.
+
+The decision is based on the `data_profile.scale_compatibility` in the tool response:
+
+| Condition | Layout | Reason |
+|-----------|--------|--------|
+| Same scale type AND value ratio ≤ 10× | Single panel, shared Y-axis | Values are comparable |
+| Same scale type BUT value ratio > 10× | vconcat panels, independent Y-axes | Large magnitude difference distorts one series |
+| Different scale types (e.g. % vs USD) | vconcat panels, independent Y-axes | Incomparable units |
+| All values are percentages in [0, 100] | Single panel | Natural shared range |
+
+**How to use**: After calling `data360_get_multi_indicator_viz_spec`, read
+`data_profile.scale_compatibility.can_share_axis` and `data_profile.indicators`
+to understand the layout decision and narrate it to the user.
+
+## 3. Encoding Grammar
+
+The engine maps data dimensions to visual channels:
+
+| Data dimension | Vega-Lite encoding | When used |
+|---|---|---|
+| year / time_period | `x` (temporal) | Time-series charts |
+| country | `color` (nominal) | Multi-country lines; `y` for cross-sectional bars |
+| value / obs_value | `y` (quantitative) | Always the measurement axis |
+| indicator | `color` (nominal) | Multi-indicator overlays |
+| breakdown dim (sex, age, etc.) | `color` or `facet` | Disaggregation present |
+
+## 4. Data Profile Fields
+
+Every viz tool response now includes a `data_profile` with these sections:
+
+- **indicators**: Per-indicator value ranges (min/max/median), unit codes, scale
+  types (percentage/currency/persons/index), and whether values are proportions.
+- **scale_compatibility** (multi-indicator): Whether indicators can share a Y-axis.
+- **structure**: Country list, year range, temporal density (dense/moderate/sparse).
+- **breakdowns**: Available disaggregation dimensions with actual values and meanings.
+- **composition_hint**: Whether data looks like parts-of-a-whole (suitable for stacked).
+
+Use these fields to:
+1. **Narrate accurately**: "GDP ranges from $1,200 to $63,000" instead of guessing.
+2. **Assess chart quality**: If `temporal_density` is "sparse", note potential gaps.
+3. **Suggest alternatives**: If `composition_hint.suitable_for_stacked` is true,
+   suggest a stacked area view.
+
+## 5. When NOT to Pass chart_type
+
+Let the engine auto-select when:
+- The data shape is unambiguous (single indicator, clear temporal or cross-sectional)
+- You are unsure which chart fits the data
+
+Only override chart_type when:
+- The user explicitly asked for a style ("show me a bar chart")
+- You need a specific multi-indicator layout ("scatter", "connected_scatter")
+
+## 6. Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| 1 indicator | `data360_get_viz_spec` |
+| 2–4 indicators to compare | `data360_get_multi_indicator_viz_spec` |
+| Need to summarize without a chart | `data360_summarize_data` |
+"""
+
+
+@mcp.resource("data360://viz/chart-grammar")
+async def chart_grammar_resource() -> str:
+    """Grammar-of-graphics decision rules for Data360 visualization.
+
+    Teaches the LLM how to reason about data shapes, scale compatibility,
+    encoding rules, and layout decisions. Read this resource to understand
+    how the visualization engine selects strategies and how to interpret
+    the data_profile in tool responses.
+    """
+    return CHART_GRAMMAR
+
+
+VEGA_LITE_RENDERER_HTML = """<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Data360 Vega-Lite Renderer</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 8px;
+        background: transparent;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      }
+      #vis {
+        width: 100%;
+        height: 100%;
+        min-height: 400px;
+      }
+      #error-display {
+        display: none;
+        color: #721c24;
+        background-color: #f8d7da;
+        border: 1px solid #f5c6cb;
+        padding: 15px;
+        margin: 10px;
+        border-radius: 4px;
+      }
+      #error-display h3 {
+        margin-top: 0;
+        margin-bottom: 8px;
+      }
+      #error-display pre {
+        white-space: pre-wrap;
+        font-size: 11px;
+        margin-top: 10px;
+        background: #fff;
+        padding: 8px;
+        border: 1px solid #ddd;
+        font-family: monospace;
+      }
+    </style>
+    <script src="<<<SERVER_BASE>>>/static/libs/vega.js"></script>
+    <script src="<<<SERVER_BASE>>>/static/libs/vega-lite.js"></script>
+    <script src="<<<SERVER_BASE>>>/static/libs/vega-embed.js"></script>
+  </head>
+  <body>
+    <div id="vis"></div>
+    <div id="error-display">
+      <h3>Renderer Error</h3>
+      <p id="error-message"></p>
+      <pre id="error-stack"></pre>
+    </div>
+    <script type="module">
+      const serverBaseUrl = "<<<SERVER_BASE>>>";
+
+      function showError(message, stack) {
+        document.getElementById('vis').style.display = 'none';
+        const display = document.getElementById('error-display');
+        display.style.display = 'block';
+        document.getElementById('error-message').textContent = message;
+        document.getElementById('error-stack').textContent = stack || 'No stack trace available';
+      }
+
+      async function logToServer(msg, detail) {
+        try {
+          await fetch(`${serverBaseUrl}/debug-log`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ message: msg, detail: detail })
+          });
+        } catch (e) {
+          console.error("Failed to log to server:", e);
+        }
+      }
+
+      window.addEventListener('error', (event) => {
+        const msg = event.message || event.error?.message || 'Unknown error';
+        const stack = event.error?.stack || '';
+        showError(msg, stack);
+        logToServer("Unhandled error", { message: msg, stack: stack });
+      });
+
+      window.addEventListener('unhandledrejection', (event) => {
+        const msg = event.reason?.message || String(event.reason);
+        const stack = event.reason?.stack || '';
+        showError("Promise Rejection: " + msg, stack);
+        logToServer("Unhandled promise rejection", { message: msg, stack: stack });
+      });
+
+      import { App } from "<<<SERVER_BASE>>>/static/libs/ext-apps.js";
+
+      if (window.PRE_LOADED_SPEC) {
+        vegaEmbed("#vis", window.PRE_LOADED_SPEC, {
+          actions: false,
+          theme: "default"
+        }).catch(err => {
+          console.error(err);
+          showError(`Failed to render chart spec: ${err.message}`, err.stack);
+        });
+      } else {
+        const app = new App({ name: "Data360 Vega-Lite Renderer", version: "1.0.0" });
+
+        app.ontoolresult = async (result) => {
+          if (result.isError) {
+            document.getElementById('vis').innerHTML = `<p style="color:red;">Error: ${result.content || "Failed to render chart"}</p>`;
+            return;
+          }
+
+          // 1. Try to get spec from structuredContent (default)
+          let spec = result.structuredContent?.spec;
+          let fetchError = null;
+
+          // 2. Fallback: Parse the spec URL from text content and fetch it
+          if (!spec && result.content) {
+            try {
+              const textBlock = result.content.find(
+                (block) => block.type === "text" && block.text && block.text.includes("View spec:")
+              );
+              if (textBlock) {
+                const match = textBlock.text.match(/View spec:\s*(https?:\/\/[^\s\n]+)/);
+                if (match && match[1]) {
+                  const specUrl = match[1];
+                  const response = await fetch(specUrl);
+                  if (response.ok) {
+                    spec = await response.json();
+                  } else {
+                    fetchError = `HTTP ${response.status}: ${response.statusText}`;
+                  }
+                }
+              }
+            } catch (e) {
+              fetchError = e.message;
+              console.error("Failed to fetch spec fallback:", e);
+            }
+          }
+
+          if (spec) {
+            vegaEmbed("#vis", spec, {
+              actions: false,
+              theme: "default"
+            }).catch(err => {
+              console.error(err);
+              showError(`Failed to render chart spec: ${err.message}`, err.stack);
+            });
+          } else {
+            document.getElementById('vis').innerHTML = `
+              <div>
+                <p>No visualization spec available.</p>
+                <pre style="white-space: pre-wrap; font-size: 11px; background: #fee; padding: 8px; border: 1px solid #fcc; font-family: monospace;">
+Result Keys: ${result ? Object.keys(result).join(', ') : 'null'}
+Fetch Error: ${fetchError || 'none'}
+Result JSON: ${result ? JSON.stringify(result, null, 2) : 'null'}
+                </pre>
+              </div>
+            `;
+          }
+        };
+
+        await app.connect();
+      }
+    </script>
+  </body>
+</html>
+"""
+
+
+@mcp.resource(
+    "ui://data360/vega-lite-renderer.html{?spec}",
+    app=AppConfig(
+        csp=ResourceCSP(
+            connect_domains=["*"],
+            resource_domains=[
+                "http://localhost:*",
+                "http://127.0.0.1:*",
+                "https://unpkg.com",
+                "https://cdn.jsdelivr.net",
+                "'unsafe-eval'",
+            ],
+        )
+    ),
+)
+async def vega_lite_renderer(spec: str | None = None) -> str:
+    """HTML renderer template for Vega-Lite v6 charts."""
+    from data360.config import get_mcp_server_settings
+
+    settings = get_mcp_server_settings()
+    port = settings.port or 8021
+    server_base = f"http://localhost:{port}"
+    # Use an explicit sentinel that cannot appear in real HTML/JS content.
+    # All occurrences in VEGA_LITE_RENDERER_HTML are replaced in one pass.
+    html = VEGA_LITE_RENDERER_HTML.replace("<<<SERVER_BASE>>>", server_base)
+    if spec:
+        injection = f"\n      window.PRE_LOADED_SPEC = {spec};\n"
+        html = html.replace("<body>", f"<body>\n    <script>{injection}</script>")
+    return html
+
+
+import os
+from fastapi.staticfiles import StaticFiles
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from starlette.exceptions import HTTPException
+
+class CORSStaticFiles(StaticFiles):
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http":
+            await super().__call__(scope, receive, send)
+            return
+
+        if scope["method"] == "OPTIONS":
+            response = Response(
+                "OK",
+                status_code=200,
+                headers={
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS",
+                    "Access-Control-Allow-Headers": "*",
+                }
+            )
+            await response(scope, receive, send)
+            return
+
+        async def cors_send(message) -> None:
+            if message["type"] == "http.response.start":
+                headers = list(message.get("headers", []))
+                has_origin = any(h[0].lower() == b"access-control-allow-origin" for h in headers)
+                if not has_origin:
+                    headers.append((b"access-control-allow-origin", b"*"))
+                    headers.append((b"access-control-allow-methods", b"GET, HEAD, OPTIONS"))
+                    headers.append((b"access-control-allow-headers", b"*"))
+                message["headers"] = headers
+            await send(message)
+
+        await super().__call__(scope, receive, cors_send)
+
+    async def get_response(self, path: str, scope) -> Response:
+        try:
+            return await super().get_response(path, scope)
+        except HTTPException as exc:
+            return JSONResponse(
+                {"detail": exc.detail},
+                status_code=exc.status_code,
+                headers=exc.headers
+            )
+
+
+
+
+@mcp.custom_route("/debug-log", methods=["POST", "OPTIONS"])
+async def debug_log(request: Request) -> Response:
+    if request.method == "OPTIONS":
+        return Response(
+            "OK",
+            status_code=200,
+            headers={
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": "POST, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type",
+            }
+        )
+
+    try:
+        body = await request.json()
+        print(f"\n[IFRAME DEBUG LOG] {body}\n", flush=True)
+        return JSONResponse(
+            {"status": "ok"},
+            headers={"Access-Control-Allow-Origin": "*"}
+        )
+    except Exception as e:
+        print(f"Error reading debug log: {e}", flush=True)
+        return JSONResponse(
+            {"error": str(e)},
+            status_code=400,
+            headers={"Access-Control-Allow-Origin": "*"}
+        )

src/data360/mcp_server/security_validator.py

@@ -0,0 +1,228 @@
+"""Security validation for MCP tool calls to prevent prompt injection attacks."""
+
+import logging
+import re
+from typing import Any
+
+_logger = logging.getLogger(__name__)
+
+# Prompt injection patterns that indicate malicious intent
+PROMPT_INJECTION_PATTERNS = [
+    # Tool enumeration attempts
+    r"list\s+(all\s+)?(available\s+)?tools",
+    r"show\s+me\s+(all\s+)?(available\s+)?tools",
+    r"what\s+tools\s+(do\s+you\s+have|are\s+available)",
+    r"enumerate\s+tools",
+    r"get\s+all\s+tools",
+    # Instruction override attempts
+    r"ignore\s+(previous|all|your)\s+instructions",
+    r"disregard\s+(previous|all|your)\s+instructions",
+    r"forget\s+(previous|all|your)\s+instructions",
+    r"new\s+instructions?:",
+    r"system\s+prompt:",
+    r"\byou\s+are\s+now\s+(?:a|an|the)\b",
+    # Role manipulation
+    r"^\s*act\s+as\s+(?:a|an|the)\b",
+    r"pretend\s+to\s+be",
+    r"you\s+are\s+(a\s+)?developer",
+    r"you\s+are\s+(a\s+)?admin",
+    # Multi-tool chaining attempts
+    r"\bthen\s+(call|execute|run)\b",
+    r"after\s+that,?\s+(call|execute|run)",
+    r"next,?\s+(call|execute|run)",
+    r"and\s+then\s+(call|execute|run)",
+    # System/internal method access
+    r"__\w+__",  # Dunder methods
+    r"(?:^|[^\w])\.system\b",
+    r"(?:^|[^\w])\.internal\b",
+    r"(?:^|[^\w])\.admin\b",
+]
+
+# Compile patterns for performance
+_INJECTION_REGEX = [
+    re.compile(pattern, re.IGNORECASE) for pattern in PROMPT_INJECTION_PATTERNS
+]
+
+MIN_SEARCH_QUERY_LENGTH = 3
+MAX_TOOL_PARAM_LENGTH = 5000
+MAX_SEARCH_QUERY_LENGTH = 100
+
+
+def validate_tool_call(
+    tool_name: str, arguments: dict[str, Any]
+) -> tuple[bool, str | None]:
+    """
+    Validate a tool call for security issues.
+
+    Returns:
+        (is_valid, error_message)
+        - (True, None) if valid
+        - (False, "error message") if invalid
+    """
+
+    # Check tool name for suspicious patterns
+    if not tool_name or not isinstance(tool_name, str):
+        return (False, "Invalid tool name")
+
+    # Only allow data360 tools
+    if not tool_name.startswith("data360_"):
+        return (
+            False,
+            f"Unauthorized tool: {tool_name}. Only data360_* tools are allowed.",
+        )
+
+    # Check arguments for prompt injection
+    if arguments:
+        for param_name, value in arguments.items():
+            if isinstance(value, str):
+                # Check for prompt injection patterns
+                for pattern in _INJECTION_REGEX:
+                    if pattern.search(value):
+                        _logger.warning(
+                            f"Prompt injection detected in {param_name}: {value[:100]}"
+                        )
+                        return (
+                            False,
+                            f"Security violation: Suspicious pattern detected in '{param_name}'. "
+                            "Please use specific, factual queries only.",
+                        )
+
+                # Check for excessive length (potential attack)
+                if len(value) > MAX_TOOL_PARAM_LENGTH:
+                    return (
+                        False,
+                        f"Parameter '{param_name}' exceeds maximum length of "
+                        f"{MAX_TOOL_PARAM_LENGTH} characters.",
+                    )
+
+    return (True, None)
+
+
+def validate_search_query(query: str) -> tuple[bool, str | None]:
+    """
+    Validate a single search term to prevent enumeration attacks.
+
+    Returns:
+        (is_valid, error_message)
+    """
+    if not query or not isinstance(query, str):
+        return (False, "Search query must be a non-empty string")
+
+    stripped = query.strip()
+    if not stripped:
+        return (False, "Search query must be a non-empty string")
+
+    # Minimum query length to prevent enumeration
+    if len(stripped) < MIN_SEARCH_QUERY_LENGTH:
+        return (
+            False,
+            f"Search query must be at least {MIN_SEARCH_QUERY_LENGTH} characters. "
+            "Use specific, meaningful search terms (e.g., 'GDP growth', 'unemployment rate').",
+        )
+
+    # Block single character or wildcard queries
+    if stripped in ["*", "?", "%", "_", ".", ".*"]:
+        return (
+            False,
+            "Wildcard-only queries are not allowed. Please use specific search terms.",
+        )
+
+    # Check for prompt injection in query
+    for pattern in _INJECTION_REGEX:
+        if pattern.search(stripped):
+            _logger.warning(
+                f"Prompt injection detected in search query: {stripped[:MAX_SEARCH_QUERY_LENGTH]}"
+            )
+            return (
+                False,
+                "Security violation: Suspicious pattern detected in query. "
+                "Please use specific, factual search terms only.",
+            )
+
+    return (True, None)
+
+
+def _collect_search_query_strings(arguments: dict[str, Any]) -> list[str]:
+    """
+    Collect non-empty search terms from data360_search_indicators arguments.
+
+    Mirrors search() input modes: ``query``, ``queries``, and ``query_groups``.
+    Empty or whitespace-only entries are skipped (same as api.search normalisation).
+    """
+    terms: list[str] = []
+
+    query = arguments.get("query")
+    if isinstance(query, str) and query.strip():
+        terms.append(query)
+
+    queries = arguments.get("queries")
+    if isinstance(queries, list):
+        for item in queries:
+            if isinstance(item, str) and item.strip():
+                terms.append(item)
+
+    query_groups = arguments.get("query_groups")
+    if isinstance(query_groups, list):
+        for group in query_groups:
+            if not isinstance(group, dict):
+                continue
+            group_queries = group.get("queries")
+            if not isinstance(group_queries, list):
+                continue
+            for item in group_queries:
+                if isinstance(item, str) and item.strip():
+                    terms.append(item)
+
+    return terms
+
+
+def validate_search_arguments(arguments: dict[str, Any]) -> tuple[bool, str | None]:
+    """
+    Validate all search terms for data360_search_indicators.
+
+    Applies per-term checks for ``query``, each entry in ``queries``, and each
+    nested term in ``query_groups[].queries``.
+
+    Returns:
+        (is_valid, error_message)
+    """
+    terms = _collect_search_query_strings(arguments)
+    if not terms:
+        return (
+            False,
+            "One of 'query', 'queries', or 'query_groups' must include at least "
+            "one non-empty search term.",
+        )
+
+    for term in terms:
+        is_valid, error_msg = validate_search_query(term)
+        if not is_valid:
+            return (False, error_msg)
+
+    return (True, None)
+
+
+def sanitize_string(value: str, max_length: int = 1000) -> str:
+    """
+    Sanitize string input by removing potentially dangerous characters.
+
+    Args:
+        value: Input string
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized string
+    """
+    if not isinstance(value, str):
+        return str(value)
+
+    # Truncate to max length
+    sanitized = value[:max_length]
+
+    # Remove null bytes and other dangerous characters
+    sanitized = sanitized.replace("\x00", "")
+
+    # Remove excessive whitespace
+    sanitized = " ".join(sanitized.split())
+
+    return sanitized

src/data360/mcp_server/tool_spans.py

@@ -0,0 +1,40 @@
+"""OpenTelemetry parent spans for each MCP tool invocation (nests httpx child spans)."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, cast
+
+from opentelemetry import trace
+
+_tracer = trace.get_tracer("data360.mcp.tools")
+
+
+def instrument_mcp_tool(fn: Callable[..., Any], *, tool_name: str) -> Callable[..., Any]:
+    """Wrap a tool function so each call runs under ``mcp.tool.<name>`` span."""
+    if inspect.iscoroutinefunction(fn):
+        fn_async = cast("Callable[..., Any]", fn)
+
+        @functools.wraps(fn_async)
+        async def _async_impl(*args: Any, **kwargs: Any) -> Any:
+            with _tracer.start_as_current_span(
+                f"mcp.tool.{tool_name}",
+                attributes={"mcp.tool.name": tool_name},
+            ):
+                return await fn_async(*args, **kwargs)
+
+        return _async_impl
+
+    fn_sync = cast("Callable[..., Any]", fn)
+
+    @functools.wraps(fn_sync)
+    def _sync_impl(*args: Any, **kwargs: Any) -> Any:
+        with _tracer.start_as_current_span(
+            f"mcp.tool.{tool_name}",
+            attributes={"mcp.tool.name": tool_name},
+        ):
+            return fn_sync(*args, **kwargs)
+
+    return _sync_impl

src/data360/mcp_server/tools.py

@@ -0,0 +1,1605 @@
+"""MCP Tools for the Data360 server.
+
+Thin wrapper layer that registers API functions as MCP tools with optimized signatures,
+concise docstrings to reduce token context bloat, and validation schemas.
+"""
+
+import json
+import os
+import threading
+from typing import Any, Literal, Optional
+
+import pydantic_core
+from fastmcp.apps import AppConfig
+from fastmcp.exceptions import ToolError
+from fastmcp.tools import ToolResult
+from fastmcp.tools.tool import Tool
+from mcp.types import TextContent
+
+from data360 import api as data360_api
+from data360 import providers as data360_providers
+from data360 import visualization as data360_viz
+from data360 import viz_config as data360_viz_config
+
+from ._server_definition import mcp
+from .tool_spans import instrument_mcp_tool
+
+# ---------------------------------------------------------------------------
+# Serializer for aggregation tools
+# ---------------------------------------------------------------------------
+
+
+def _compact_aggregation_serializer(data: Any) -> str:
+    """Compact serializer for aggregation tool responses.
+
+    Calls ``to_compact()`` on the response model if available, producing a
+    token-efficient JSON representation while preserving all PCN claim_ids
+    for data provenance verification.
+    """
+    if hasattr(data, "to_compact"):
+        return json.dumps(data.to_compact(), separators=(",", ":"))
+    return pydantic_core.to_json(data, fallback=str).decode()
+
+
+def _normalize_disaggregation_filters(filters: dict[str, Any] | None) -> dict[str, str | None] | None:
+    """Normalize user-provided disaggregation filters.
+    Converts list values (e.g., ["F", "M"]) to comma-separated strings (e.g., "F,M")
+    to conform to the underlying API support while remaining type-flexible for LLM callers.
+    """
+    if filters is None:
+        return None
+    normalized = {}
+    for k, v in filters.items():
+        if v is None:
+            normalized[k] = None
+        elif isinstance(v, list):
+            normalized[k] = ",".join(str(item).strip() for item in v if item is not None)
+        else:
+            normalized[k] = str(v)
+    return normalized
+
+
+# ---------------------------------------------------------------------------
+# Tool Wrapper Functions
+# ---------------------------------------------------------------------------
+
+
+async def _search_indicators(
+    query: str | None = None,
+    required_country: str | None = None,
+    limit: int = 5,
+    offset: int = 0,
+    queries: list[str] | None = None,
+    query_groups: list[dict[str, Any]] | None = None,
+    result_layout: str = "merged",
+    dedupe: bool = True,
+    database: str | None = None,
+) -> Any:
+    """Search for Data360 indicators with enriched metadata for selection.
+
+    Use when the user asks for data on a development topic (e.g. GDP, poverty, education).
+    Default to using the single `query` parameter for any single topic/indicator search. Use the `queries` or `query_groups` parameters ONLY when the request involves multiple topics or scopes (2 or more).
+    Provide exactly one of `query`, `queries`, or `query_groups`. One of these is strictly required.
+
+    ### Parameter Selection Decision Tree (CRITICAL):
+    1. **Exactly 1 Topic** (e.g., "life expectancy" or "mortality rate") for any number of countries → you MUST use the single `query` parameter + `required_country`. Do NOT use `queries` with only one element, as it will fail. Do NOT combine multiple topics with 'and' or 'or' in `query` (e.g. do NOT use query="GDP and inflation").
+    2. **Multiple Topics, Same Country/Countries** (e.g., "life expectancy and GDP per capita" for Japan) → you MUST use the `queries` list parameter (e.g. `queries=["life expectancy", "GDP per capita"]`) + `required_country`. Do NOT make multiple tool calls. Do NOT pass multiple topics as a single query string (e.g., query="life expectancy and GDP per capita" is invalid).
+    3. **Different Topics targeting Different Countries** (e.g., "life expectancy for Japan, but GDP and mortality rate for Korea") → you MUST use the `query_groups` parameter. Do NOT use `queries`.
+
+    Args:
+        query: Single topic query (e.g. "unemployment"). Use ONLY for a single topic. Do NOT combine multiple topics with 'and' or 'or' (e.g. do NOT use query="population and life expectancy"). Avoid special characters like parentheses () or dollar signs $. Example: 'GDP per capita'.
+        required_country: Semicolon-separated ISO country codes (e.g. "KEN;USA"). Shared across all queries in 'query' or 'queries'. Consider calling `data360_expand_country_group` to find country codes in regional/income groups, or `data360_find_codelist_value` to resolve country names.
+        limit: Max indicators per query (default 5).
+        offset: Offset for pagination.
+        queries: List of topics for multi-topic search (must contain at least 2 non-empty search strings). Use ONLY when 2 or more topics target the SAME countries/geographic scope (e.g. ['GDP per capita', 'inflation rate']).
+        query_groups: Grouped queries with specific country scopes. Use ONLY when different topics/queries target different country scopes. Example: [{'queries': ['life expectancy'], 'country': 'JPN'}, {'queries': ['GDP per capita'], 'country': 'KOR'}].
+        result_layout: Mode to return results: "merged" (flat, deduped list of indicators) or "by_query" (indicators grouped by search query).
+        dedupe: De-duplicate indicators across query results.
+        database: Optional database name or ID to filter search results (e.g. "wdi", "wgi", "World Development Indicators"). Multiple databases can be queried at once by separating them with a semicolon (e.g. "pip; lpgd; sgi").
+    """
+    # Robustness fallback: if queries is passed as a list of exactly 1 item,
+    # normalize it to a single query parameter to prevent validation failure.
+    if queries is not None:
+        clean_queries = [q.strip() for q in queries if q and q.strip()]
+        if len(clean_queries) == 1:
+            if not query:
+                query = clean_queries[0]
+            queries = None
+
+    return await data360_api.search(
+        query=query,
+        required_country=required_country,
+        limit=limit,
+        offset=offset,
+        queries=queries,
+        query_groups=query_groups,
+        result_layout=result_layout,
+        dedupe=dedupe,
+        database=database,
+    )
+
+
+async def _search_datasets(
+    query: str,
+    limit: int = 10,
+    offset: int = 0,
+) -> Any:
+    """Search for Data360 datasets matching a query.
+
+    Use when the user asks for dataset details, catalogs, or source databases (e.g. "Findex", "WDI").
+
+    Args:
+        query: Topic or dataset search term (e.g. "findex"). Avoid special characters like parentheses () or dollar signs $ as they cause search failures.
+        limit: Max datasets to return (default 10).
+        offset: Offset for pagination.
+    """
+    return await data360_api.search_datasets(
+        query=query,
+        limit=limit,
+        offset=offset,
+    )
+
+
+async def _get_metadata(
+    database_id: str,
+    indicator_id: str,
+    select_fields: list[str] | None = None,
+    fetch_disaggregation: bool = True,
+    required_country: str | None = None,
+) -> Any:
+    """Get metadata and disaggregation options for a Data360 indicator.
+
+    Use when you need detailed methodology, source notes, or limitations for an indicator.
+    Ensure the database ID and the indicator ID are already in context (e.g., from `data360_search_indicators`) before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        database_id: Database identifier (e.g., "WB_WDI").
+        indicator_id: Indicator ID (e.g., "WB_WDI_NY_GDP_PCAP_KD").
+        select_fields: Optional metadata fields to return (e.g., ["methodology", "relevance"]).
+        fetch_disaggregation: Whether to include disaggregation options.
+        required_country: Semicolon-separated ISO country codes to check coverage.
+    """
+    return await data360_api.get_metadata(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        select_fields=select_fields,
+        fetch_disaggregation=fetch_disaggregation,
+        required_country=required_country,
+    )
+
+
+async def _get_data(
+    database_id: str,
+    indicator_id: str,
+    country_code: str | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    ref_area_filter: Literal["none", "member_economies_only"] = "member_economies_only",
+    year: int | None = None,
+) -> Any:
+    """Retrieve indicator observations from the Data360 API.
+
+    Use when you need actual numeric values (OBS_VALUE) for specific countries and years.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+    Call `data360_get_disaggregation` first to find available years and breakdowns for the `disaggregation_filters`.
+
+    Args:
+        database_id: Database identifier (e.g., "WB_WDI").
+        indicator_id: Indicator ID (e.g., "WB_WDI_NY_GDP_PCAP_KD").
+        country_code: Semicolon-separated ISO country codes (e.g. "KEN;USA").
+        disaggregation_filters: Optional dimension filters. Values must be strings or null. Call `data360_get_disaggregation` first to find valid options.
+        start_year: Start year (inclusive). Defaults to last 5 years if both bounds omitted;
+            if only end_year is set, defaults to a 5-year window ending at end_year.
+        end_year: End year (inclusive). See start_year for partial-bound defaults.
+        limit: Max records per page (default 50, max 100).
+        offset: Number of records to skip for pagination.
+        ref_area_filter: Filter mode: "member_economies_only" (default) or "none".
+        year: Specific single year to retrieve data for. Maps internally to start_year and end_year.
+    """
+    if year is not None:
+        if start_year is None:
+            start_year = year
+        if end_year is None:
+            end_year = year
+
+
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    return await data360_api.get_data(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_code=country_code,
+        disaggregation_filters=norm_filters,
+        start_year=start_year,
+        end_year=end_year,
+        limit=limit,
+        offset=offset,
+        ref_area_filter=ref_area_filter,
+    )
+
+
+async def _get_disaggregation(
+    database_id: str,
+    indicator_id: str,
+    required_country: str | None = None,
+) -> dict[str, Any]:
+    """Get valid filter values and disaggregation options for an indicator.
+
+    Use to find available dimensions (e.g., SEX, AGE) and years before querying data or charts.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        database_id: Database identifier (e.g., "WB_WDI").
+        indicator_id: Indicator ID (e.g., "WB_WDI_NY_GDP_PCAP_KD").
+        required_country: Semicolon-separated ISO country codes to check coverage.
+    """
+    return await data360_api.get_disaggregation(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        required_country=required_country,
+    )
+
+
+async def _find_codelist_value(
+    codelist_type: str, query: str, limit: int = 5
+) -> list[dict[str, Any]]:
+    """Resolve user-friendly names to API dimension codes.
+
+    Use when you need to find codes for country names, sex, age, urbanisation, etc.
+
+    Args:
+        codelist_type: Dimension name (e.g. "REF_AREA", "SEX", "AGE", "URBANISATION").
+        query: Search term (e.g. "Kenya", "female").
+        limit: Max results to return (default 5).
+    """
+    return await data360_providers.find_codelist_value(
+        codelist_type=codelist_type, query=query, limit=limit
+    )
+
+
+async def _list_indicators(database_id: str) -> list[str]:
+    """Get all indicator IDs for a specific database.
+
+    Use when you need the full list of indicator IDs for a dataset.
+
+    Args:
+        database_id: The database identifier (e.g., "WB_WDI").
+    """
+    return await data360_api.get_indicators(database_id=database_id)
+
+
+async def _get_data_api_url(
+    database_id: str,
+    indicator_id: str,
+    country_code: str | None = None,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+    year: int | None = None,
+) -> str:
+    """Generate the raw Data360 API URL for an indicator request.
+
+    Low-level tool: use only when the caller specifically asks for the URL.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        database_id: Database identifier (e.g. "WB_WDI").
+        indicator_id: Indicator ID (e.g. "WB_WDI_NY_GDP_PCAP_KD").
+        country_code: Semicolon-separated ISO country codes.
+        start_year: Start year (inclusive). Defaults to last 5 years if omitted.
+        end_year: End year (inclusive). Defaults to current year if omitted.
+        disaggregation_filters: Optional dimension filters.
+        year: Specific single year to generate the URL for. Maps internally to start_year and end_year.
+    """
+    if year is not None:
+        if start_year is None:
+            start_year = year
+        if end_year is None:
+            end_year = year
+
+
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    return await data360_api.get_data_api_url(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_code=country_code,
+        start_year=start_year,
+        end_year=end_year,
+        disaggregation_filters=norm_filters,
+    )
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Bundled Vega library cache (thread-safe, loaded once on first use)
+# ---------------------------------------------------------------------------
+
+_vega_libs_lock = threading.Lock()
+_vega_libs_cache: tuple[str, str, str, str] | None = None
+
+
+def get_cached_vega_libs() -> tuple[str, str, str, str]:
+    """Load and cache local Vega library scripts from static/libs (thread-safe)."""
+    global _vega_libs_cache
+    if _vega_libs_cache is not None:
+        return _vega_libs_cache
+    with _vega_libs_lock:
+        if _vega_libs_cache is not None:  # double-check after acquiring lock
+            return _vega_libs_cache
+        from pathlib import Path
+        import logging
+
+        libs_dir = (
+            Path(__file__).resolve().parent.parent.parent.parent / "static" / "libs"
+        )
+        try:
+            vega_js = (libs_dir / "vega.js").read_text(encoding="utf-8")
+            vega_lite_js = (libs_dir / "vega-lite.js").read_text(encoding="utf-8")
+            vega_embed_js = (libs_dir / "vega-embed.js").read_text(encoding="utf-8")
+            vega_interp_js = (libs_dir / "vega-interpreter.js").read_text(
+                encoding="utf-8"
+            )
+        except Exception as e:
+            logging.getLogger("data360").warning(
+                "Failed to load local Vega library scripts: %s", e
+            )
+            vega_js = vega_lite_js = vega_embed_js = vega_interp_js = ""
+        _vega_libs_cache = (vega_js, vega_lite_js, vega_embed_js, vega_interp_js)
+        return _vega_libs_cache
+
+
+# ---------------------------------------------------------------------------
+# Markdown summary helper (text content block for viz ToolResults)
+# ---------------------------------------------------------------------------
+
+
+def _make_text_summary(
+    spec: "dict[str, Any] | None",
+    strategy: str,
+    reason: str,
+    warning: str | None = None,
+    subtitle_line: str | None = None,
+    source_line: str | None = None,
+    url: str | None = None,
+) -> str:
+    """Build a markdown summary table from a Vega-Lite spec for the text content block."""
+    import pandas as pd
+
+    lines: list[str] = []
+
+    if warning:
+        lines.append(f"### Warning\n{warning}\n")
+
+    lines.append(f"### Data Summary ({strategy})")
+    lines.append(reason)
+    if subtitle_line:
+        lines.append(f"*{subtitle_line}*")
+    lines.append("")
+
+    data_rows: list[dict] = []
+    if isinstance(spec, dict):
+        data_rows = spec.get("data", {}).get("values", [])
+
+    if data_rows:
+        try:
+            df = pd.DataFrame(data_rows)
+            # Reorder: put time/area columns first
+            cols = list(df.columns)
+            for p in reversed(
+                ["TIME_PERIOD", "time_period", "REF_AREA", "ref_area"]
+            ):
+                if p in cols:
+                    cols.remove(p)
+                    cols.insert(0, p)
+            df = df[cols]
+
+            headers = [c.replace("_", " ").title() for c in df.columns]
+            lines.append("| " + " | ".join(headers) + " |")
+            lines.append("| " + " | ".join(["---"] * len(df.columns)) + " |")
+            for _, row in df.iterrows():
+                vals = []
+                for col in df.columns:
+                    v = row[col]
+                    if v is None or (isinstance(v, float) and pd.isna(v)):
+                        vals.append("")
+                    elif isinstance(v, float):
+                        vals.append(f"{v:,.2f}")
+                    else:
+                        vals.append(str(v))
+                lines.append("| " + " | ".join(vals) + " |")
+        except Exception:
+            lines.append("No tabular data available.")
+    else:
+        lines.append("No data available.")
+
+    if source_line:
+        lines.append(f"\n*{source_line}*")
+    if url:
+        lines.append(f"\n*Vega-Lite Spec URL:* {url}")
+
+    return "\n".join(lines)
+
+async def _get_viz_spec(
+    database_id: str,
+    indicator_id: str,
+    country_code: str | None = None,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+    chart_type: str | None = None,
+    relevant_fields: list[str] | None = None,
+    custom_constraints: list[str] | None = None,
+    use_default_constraints: bool = True,
+    chart_title: str | dict | None = None,
+    series_labels: dict[str, str] | None = None,
+    strategy_override: str | None = None,
+    year: int | None = None,
+) -> ToolResult:
+    """Generate a Vega-Lite chart from a single Data360 indicator.
+
+    Use when the user requests a chart or plot for a single indicator.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+    Call `data360_get_disaggregation` first to find available years and breakdowns for the `disaggregation_filters`.
+
+    Args:
+        database_id: Database identifier (e.g. "WB_WDI").
+        indicator_id: Indicator ID (e.g. "WB_WDI_NY_GDP_PCAP_KD").
+        country_code: Semicolon-separated ISO country codes (e.g. "KEN;USA").
+        start_year: Start year (inclusive). Defaults to last 5 years if omitted.
+        end_year: End year (inclusive). Defaults to current year if omitted.
+        disaggregation_filters: Optional dimension filters.
+        chart_type: Optional chart type suggestion. If omitted (recommended), the routing engine automatically determines the optimal chart type and strategy based on the data profile. Do not specify this argument unless the user explicitly requested a specific chart type.
+        relevant_fields: Fields to include in visual encodings.
+        custom_constraints: Custom Draco design rules.
+        use_default_constraints: Whether to apply default Draco design constraints.
+        chart_title: A concise, human-synthesized title summarizing the data insight (e.g. 'Renewable Energy Share in South Asia (2020)'). Prefer clean, natural phrasing instead of raw long indicator names.
+        series_labels: Rename dimension codes for legend (e.g. {"WGI_EST": "Estimate"}).
+        strategy_override: Explicitly force a chart strategy (e.g. "stacked_bar", "temporal_single").
+        year: Specific single year to generate the chart for. Maps internally to start_year and end_year.
+    """
+    if year is not None:
+        if start_year is None:
+            start_year = year
+        if end_year is None:
+            end_year = year
+
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    res = await data360_viz.get_viz_spec(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_code=country_code,
+        start_year=start_year,
+        end_year=end_year,
+        disaggregation_filters=norm_filters,
+        chart_type=chart_type,
+        relevant_fields=relevant_fields,
+        custom_constraints=custom_constraints,
+        use_default_constraints=use_default_constraints,
+        chart_title=chart_title,
+        series_labels=series_labels,
+        strategy_override=strategy_override,
+    )
+
+    if res.get("error"):
+        raise ToolError(res["error"])
+
+    url = res.get("url")
+    strategy = res.get("strategy") or "unknown"
+    reason = res.get("reason") or ""
+    warning = res.get("warning")
+    source_line = res.get("source_line")
+    subtitle_line = res.get("subtitle_line")
+
+    # Prefer the spec already carried in the result dict (populated by _ok() in
+    # visualization.py). The disk-reload below is a fallback for callers that
+    # do not propagate the spec (e.g. when the chart URL points to an external
+    # charts API rather than the local static file server).
+    spec: dict | None = res.get("spec") or None
+    if spec is None and url:
+        try:
+            spec_id = url.split("/")[-1].replace("_vega.json", "")
+            if os.environ.get("PYTEST_CURRENT_TEST"):
+                specs_dir = os.path.join(os.getcwd(), "static", "viz_specs")
+            else:
+                server_dir = os.path.dirname(os.path.abspath(__file__))
+                project_root = os.path.abspath(os.path.join(server_dir, "..", "..", ".."))
+                specs_dir = os.path.join(project_root, "static", "viz_specs")
+            vega_path = os.path.join(specs_dir, f"{spec_id}_vega.json")
+            if os.path.exists(vega_path):
+                with open(vega_path, "r") as f:
+                    spec = json.load(f)
+        except Exception:
+            pass
+
+    text_summary = _make_text_summary(
+        spec=spec,
+        strategy=strategy,
+        reason=reason,
+        warning=warning,
+        source_line=source_line,
+        subtitle_line=subtitle_line,
+        url=url,
+    )
+
+    structured = {
+        "spec": spec,
+        "strategy": strategy,
+        "url": url,
+        "error": None,
+        "warning": warning,
+        "reason": reason,
+        "source_line": source_line,
+        "subtitle_line": subtitle_line,
+    }
+    return ToolResult(
+        content=[
+            TextContent(type="text", text=json.dumps(structured)),
+            TextContent(type="text", text=text_summary),
+        ],
+        structured_content=structured,
+    )
+
+
+async def _get_multi_indicator_viz_spec(
+    indicator_ids: list[dict[str, str]] | None = None,
+    country_code: str | None = None,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+    chart_type: str | None = None,
+    chart_title: str | dict | None = None,
+    series_labels: dict[str, str] | None = None,
+    strategy_override: str | None = None,
+    year: int | None = None,
+) -> ToolResult:
+    """Generate a Vega-Lite chart comparing multiple Data360 indicators.
+
+    Use when you need to compare 2–4 indicators (e.g. via scatterplot or dual-axis line chart).
+    Ensure the database IDs and indicator IDs are already in context before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        indicator_ids: List of database/indicator dicts, e.g. [{"database_id": "WB_WDI", "indicator_id": "..."}].
+        country_code: Semicolon-separated ISO country codes (e.g. "KEN;USA").
+        start_year: Start year (inclusive). Defaults to last 5 years if omitted.
+        end_year: End year (inclusive). Defaults to current year if omitted.
+        disaggregation_filters: Optional dimension filters.
+        chart_type: Optional chart type suggestion. If omitted (recommended), the routing engine automatically determines the optimal chart type and strategy based on the data profile. Do not specify this argument unless the user explicitly requested a specific chart type.
+        chart_title: A concise, human-synthesized title summarizing the data insight (e.g. 'Renewable Energy Share in South Asia (2020)'). Prefer clean, natural phrasing instead of raw long indicator names.
+        series_labels: Rename dimension codes for legend.
+        strategy_override: Explicitly force a chart strategy (e.g. "stacked_bar", "vconcat_panels").
+        year: Specific single year to compare indicators for. Maps internally to start_year and end_year.
+    """
+    if year is not None:
+        if start_year is None:
+            start_year = year
+        if end_year is None:
+            end_year = year
+
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    res = await data360_viz.get_multi_indicator_viz_spec(
+        indicator_ids=indicator_ids,
+        country_code=country_code,
+        start_year=start_year,
+        end_year=end_year,
+        disaggregation_filters=norm_filters,
+        chart_type=chart_type,
+        chart_title=chart_title,
+        series_labels=series_labels,
+        strategy_override=strategy_override,
+    )
+
+    if res.get("error"):
+        raise ToolError(res["error"])
+
+    url = res.get("url")
+    strategy = res.get("strategy") or "unknown"
+    reason = res.get("reason") or ""
+    warning = res.get("warning")
+    source_line = res.get("source_line")
+    subtitle_line = res.get("subtitle_line")
+
+    # Prefer the spec already carried in the result dict (populated by _ok() in
+    # visualization.py). The disk-reload below is a fallback for callers that
+    # do not propagate the spec (e.g. when the chart URL points to an external
+    # charts API rather than the local static file server).
+    spec: dict | None = res.get("spec") or None
+    if spec is None and url:
+        try:
+            spec_id = url.split("/")[-1].replace("_vega.json", "")
+            if os.environ.get("PYTEST_CURRENT_TEST"):
+                specs_dir = os.path.join(os.getcwd(), "static", "viz_specs")
+            else:
+                server_dir = os.path.dirname(os.path.abspath(__file__))
+                project_root = os.path.abspath(os.path.join(server_dir, "..", "..", ".."))
+                specs_dir = os.path.join(project_root, "static", "viz_specs")
+            vega_path = os.path.join(specs_dir, f"{spec_id}_vega.json")
+            if os.path.exists(vega_path):
+                with open(vega_path, "r") as f:
+                    spec = json.load(f)
+        except Exception:
+            pass
+
+    text_summary = _make_text_summary(
+        spec=spec,
+        strategy=strategy,
+        reason=reason,
+        warning=warning,
+        source_line=source_line,
+        subtitle_line=subtitle_line,
+        url=url,
+    )
+
+    structured = {
+        "spec": spec,
+        "strategy": strategy,
+        "url": url,
+        "error": None,
+        "warning": warning,
+        "reason": reason,
+        "source_line": source_line,
+        "subtitle_line": subtitle_line,
+    }
+    return ToolResult(
+        content=[
+            TextContent(type="text", text=json.dumps(structured)),
+            TextContent(type="text", text=text_summary),
+        ],
+        structured_content=structured,
+    )
+
+
+def _get_supported_chart_types() -> str:
+    """Return supported chart types and their data requirements as JSON.
+
+    **DEPRECATED**: Read the ``data360://viz/chart-grammar`` resource instead.
+    This tool is preserved for backward compatibility.
+    """
+    import json
+
+    result = data360_viz.get_supported_chart_types()
+    parsed = json.loads(result)
+    parsed["_deprecation_notice"] = (
+        "This tool is deprecated. Read the data360://viz/chart-grammar resource "
+        "for comprehensive chart strategy rules. The data_profile in every viz "
+        "response now includes per-indicator ranges and scale compatibility."
+    )
+    return json.dumps(parsed, indent=2)
+
+
+
+async def _expand_country_group(
+    group_code: str,
+) -> dict[str, Any]:
+    """Expand a REF_AREA group code into its constituent country codes.
+
+    Use when you need individual country codes for a regional or income group code (e.g. "SAS").
+
+    Args:
+        group_code: The group code to expand (e.g. "SAS" for South Asia, "LIC" for Low Income).
+    """
+    return await data360_providers.expand_country_group(group_code=group_code)
+
+
+async def _summarize_data(
+    database_id: str,
+    indicator_id: str,
+    country_code: str | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    group_by: list[str] | None = None,
+) -> Any:
+    """Compute summary statistics for indicator data, grouped by dimensions.
+
+    Use when the user asks about trends, changes over time, or general statistical summaries.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        database_id: Database identifier (e.g. "WB_WDI").
+        indicator_id: Indicator ID (e.g. "WB_WDI_NY_GDP_PCAP_KD").
+        country_code: Semicolon-separated ISO country codes (e.g. "KEN;USA").
+        disaggregation_filters: Optional dimension filters.
+        start_year: Start year (inclusive). Defaults to last 5 years if omitted.
+        end_year: End year (inclusive). Defaults to current year if omitted.
+        group_by: Dimensions to group by (default is ["ref_area"]).
+    """
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    return await data360_api.summarize_data(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_code=country_code,
+        disaggregation_filters=norm_filters,
+        start_year=start_year,
+        end_year=end_year,
+        group_by=group_by,
+    )
+
+
+async def _rank_countries(
+    database_id: str,
+    indicator_id: str,
+    country_group: str | None = None,
+    country_codes: str | None = None,
+    year: int | None = None,
+    order: Literal["desc", "asc"] = "desc",
+    top_n: int = 10,
+    disaggregation_filters: dict[str, Any] | None = None,
+    rank_universe: Literal["explicit", "all_member_economies"] = "explicit",
+) -> Any:
+    """Rank countries by indicator value for a specific year.
+
+    Use when asked to rank countries, find leaderboards, or query top/bottom performing economies.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+
+    Args:
+        database_id: Database identifier (e.g. "WB_WDI").
+        indicator_id: Indicator ID (e.g. "WB_WDI_NY_GDP_PCAP_KD").
+        country_group: Code of region/income group (e.g. "SAS").
+        country_codes: Semicolon-separated ISO country codes (e.g. "KEN;USA;NGA").
+        year: Year for ranking. If omitted, selected automatically based on coverage.
+        order: Sort order: "desc" (default, highest first) or "asc" (lowest first).
+        top_n: Number of ranked entries to return.
+        disaggregation_filters: Optional dimension filters.
+        rank_universe: "explicit" (default, uses codes/group) or "all_member_economies" (world).
+    """
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    return await data360_api.rank_countries(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_group=country_group,
+        country_codes=country_codes,
+        year=year,
+        order=order,
+        top_n=top_n,
+        disaggregation_filters=norm_filters,
+        rank_universe=rank_universe,
+    )
+
+
+async def _compare_countries(
+    database_id: str,
+    indicator_id: str,
+    country_codes: str,
+    year: int | None = None,
+    include_time_series: bool = False,
+    start_year: int | None = None,
+    end_year: int | None = None,
+    disaggregation_filters: dict[str, Any] | None = None,
+) -> Any:
+    """Compare an indicator across multiple countries (2 to 8).
+
+    Use when asked to compare specific countries or find gaps/convergence between them.
+    Ensure the database ID and the indicator ID are already in context before using this tool. Do not guess or hallucinate these IDs.
+    Call `data360_get_disaggregation` first to find available years and breakdowns for the `disaggregation_filters`.
+
+    Args:
+        database_id: Database identifier (e.g. "WB_WDI").
+        indicator_id: Indicator ID (e.g. "WB_WDI_NY_GDP_PCAP_KD").
+        country_codes: Semicolon-separated ISO country codes (e.g. "KEN;NGA;ZAF").
+        year: Snapshot comparison year. If omitted, selected automatically.
+        include_time_series: Whether to return time-series data for trend comparison.
+        start_year: Start year for time-series alignment. Defaults to last 5 years if omitted.
+        end_year: End year for time-series alignment. Defaults to current year if omitted.
+        disaggregation_filters: Optional dimension filters.
+    """
+    norm_filters = _normalize_disaggregation_filters(disaggregation_filters)
+
+    return await data360_api.compare_countries(
+        database_id=database_id,
+        indicator_id=indicator_id,
+        country_codes=country_codes,
+        year=year,
+        include_time_series=include_time_series,
+        start_year=start_year,
+        end_year=end_year,
+        disaggregation_filters=norm_filters,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool Registration
+# ---------------------------------------------------------------------------
+
+search_indicators = mcp.tool(
+    instrument_mcp_tool(_search_indicators, tool_name="data360_search_indicators"),
+    name="data360_search_indicators",
+)
+
+search_datasets = mcp.tool(
+    instrument_mcp_tool(_search_datasets, tool_name="data360_search_datasets"),
+    name="data360_search_datasets",
+)
+
+get_metadata = mcp.tool(
+    instrument_mcp_tool(_get_metadata, tool_name="data360_get_metadata"),
+    name="data360_get_metadata",
+)
+
+get_data = mcp.tool(
+    instrument_mcp_tool(_get_data, tool_name="data360_get_data"),
+    name="data360_get_data",
+)
+
+get_disaggregation = mcp.tool(
+    instrument_mcp_tool(_get_disaggregation, tool_name="data360_get_disaggregation"),
+    name="data360_get_disaggregation",
+)
+
+find_codelist_value = mcp.tool(
+    instrument_mcp_tool(_find_codelist_value, tool_name="data360_find_codelist_value"),
+    name="data360_find_codelist_value",
+)
+
+list_indicators = mcp.tool(
+    instrument_mcp_tool(_list_indicators, tool_name="data360_list_indicators"),
+    name="data360_list_indicators",
+)
+
+get_data_api_url = mcp.tool(
+    instrument_mcp_tool(_get_data_api_url, tool_name="data360_get_data_api_url"),
+    name="data360_get_data_api_url",
+)
+
+get_viz_spec = mcp.tool(
+    instrument_mcp_tool(_get_viz_spec, tool_name="data360_get_viz_spec"),
+    name="data360_get_viz_spec",
+    app=AppConfig(resource_uri="ui://data360-chart/index.html"),
+)
+
+get_multi_indicator_viz_spec = mcp.tool(
+    instrument_mcp_tool(
+        _get_multi_indicator_viz_spec,
+        tool_name="data360_get_multi_indicator_viz_spec",
+    ),
+    name="data360_get_multi_indicator_viz_spec",
+    app=AppConfig(resource_uri="ui://data360-chart/index.html"),
+)
+
+get_supported_chart_types = mcp.tool(
+    instrument_mcp_tool(
+        _get_supported_chart_types,
+        tool_name="data360_get_supported_chart_types",
+    ),
+    name="data360_get_supported_chart_types",
+)
+
+expand_country_group = mcp.tool(
+    instrument_mcp_tool(
+        _expand_country_group, tool_name="data360_expand_country_group"
+    ),
+    name="data360_expand_country_group",
+)
+
+# ---------------------------------------------------------------------------
+# Data Aggregation Tools (with custom serialization)
+# ---------------------------------------------------------------------------
+
+summarize_data = mcp.add_tool(
+    Tool.from_function(
+        instrument_mcp_tool(_summarize_data, tool_name="data360_summarize_data"),
+        name="data360_summarize_data",
+        serializer=_compact_aggregation_serializer,
+    )
+)
+
+rank_countries = mcp.add_tool(
+    Tool.from_function(
+        instrument_mcp_tool(_rank_countries, tool_name="data360_rank_countries"),
+        name="data360_rank_countries",
+        serializer=_compact_aggregation_serializer,
+    )
+)
+
+compare_countries = mcp.add_tool(
+    Tool.from_function(
+        instrument_mcp_tool(_compare_countries, tool_name="data360_compare_countries"),
+        name="data360_compare_countries",
+        serializer=_compact_aggregation_serializer,
+    )
+)
+
+
+
+@mcp.resource("ui://data360-chart/index.html")
+def data360_chart_html() -> str:
+    """HTML resource for the Data360 self-contained Vega-Lite chart viewer Custom HTML app."""
+    vega_js, vega_lite_js, vega_embed_js, vega_interpreter_js = get_cached_vega_libs()
+    html_template = """<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Data360 Vega-Lite Renderer</title>
+  <style>
+    body {
+      margin: 0;
+      padding: 8px;
+      background: transparent;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    }
+    #vis {
+      width: 100%;
+      height: 100%;
+      min-height: 400px;
+    }
+  </style>
+  <script>{vega_js}</script>
+  <script>{vega_interpreter_js}</script>
+  <script>{vega_lite_js}</script>
+  <script>{vega_embed_js}</script>
+</head>
+<body>
+  <div id="vis"></div>
+
+  <script type="module">
+    class McpAppClient {
+      constructor() {
+        this.pendingRequests = new Map();
+        this.requestId = 0;
+        this.initialized = false;
+        this.hostContext = null;
+        window.addEventListener('message', (e) => this.handleMessage(e));
+        this.initialize();
+      }
+
+      async initialize() {
+        try {
+          const result = await this.request('ui/initialize', {
+            appInfo: { name: 'Data360 Chart', version: '1.0.0' },
+            appCapabilities: {},
+            protocolVersion: '2025-11-21'
+          });
+          this.hostContext = result.hostContext;
+          this.initialized = true;
+          this.notify('ui/notifications/initialized', {});
+          this.reportSize();
+        } catch (error) {
+          console.error('Failed to initialize MCP App:', error);
+        }
+      }
+
+      handleMessage(event) {
+        const data = event.data;
+        if (!data || typeof data !== 'object') return;
+        if ('id' in data && this.pendingRequests.has(data.id)) {
+          const { resolve, reject } = this.pendingRequests.get(data.id);
+          this.pendingRequests.delete(data.id);
+          if (data.error) {
+            reject(new Error(data.error.message));
+          } else {
+            resolve(data.result);
+          }
+          return;
+        }
+        if (data.method === 'ui/notifications/tool-result') {
+          try {
+            const result = data.params;
+            let spec = null;
+            let strategy = null;
+            if (result.structuredContent) {
+              spec = result.structuredContent.spec;
+              strategy = result.structuredContent.strategy;
+            }
+            if (!spec && result.content) {
+              const textBlock = result.content.find(c => c.type === 'text');
+              if (textBlock) {
+                try {
+                  const payload = JSON.parse(textBlock.text);
+                  spec = payload.spec;
+                  strategy = payload.strategy;
+                } catch (e) {
+                  // Ignore JSON parse error for plain text
+                }
+              }
+            }
+            renderChart(spec, strategy);
+          } catch (e) {
+            console.error('Error parsing tool result:', e);
+          }
+        }
+      }
+
+      request(method, params) {
+        return new Promise((resolve, reject) => {
+          const id = ++this.requestId;
+          this.pendingRequests.set(id, { resolve, reject });
+          window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*');
+          setTimeout(() => {
+            if (this.pendingRequests.has(id)) {
+              this.pendingRequests.delete(id);
+              reject(new Error('Request timed out'));
+            }
+          }, 30000);
+        });
+      }
+
+      notify(method, params) {
+        window.parent.postMessage({ jsonrpc: '2.0', method, params }, '*');
+      }
+
+      reportSize() {
+        this.notify('ui/notifications/size-changed', {
+          height: document.body.scrollHeight
+        });
+      }
+    }
+
+    const mcpApp = new McpAppClient();
+    const visDiv = document.getElementById('vis');
+
+    function renderChart(spec, strategy) {
+      if (!spec) {
+        visDiv.innerHTML = '<p>No visualization spec available</p>';
+        mcpApp.reportSize();
+        return;
+      }
+
+      try {
+        vegaEmbed("#vis", spec, {
+          actions: false,
+          theme: mcpApp.hostContext?.theme === 'dark' ? 'dark' : 'default',
+          ast: true,
+          expr: vega.expressionInterpreter
+        }).then(() => {
+          mcpApp.reportSize();
+        }).catch(err => {
+          console.error(err);
+          visDiv.innerHTML = `<p style="color:red;">Failed to render chart spec: ${err.message}</p>`;
+          mcpApp.reportSize();
+        });
+      } catch (e) {
+        visDiv.innerHTML = `<p style="color:red;">Error preparing spec: ${e.message}</p>`;
+        mcpApp.reportSize();
+      }
+    }
+
+    window.addEventListener('load', () => {
+      mcpApp.reportSize();
+    });
+  </script>
+</body>
+</html>
+"""
+    return html_template.replace("{vega_js}", vega_js).replace("{vega_lite_js}", vega_lite_js).replace("{vega_embed_js}", vega_embed_js).replace("{vega_interpreter_js}", vega_interpreter_js)
+
+
+
+async def _search_indicators_for_ui(
+    query: str,
+    database: Optional[str] = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Private helper: returns a flat indicator list for the UI HTML app.
+
+    Not registered as an MCP tool — called internally by data360_indicator_explorer
+    and by the /api/indicators/search FastAPI endpoint.
+    """
+    if not query.strip():
+        return []
+    res = await _search_indicators(query=query, database=database, limit=limit)
+    indicators_data = []
+    if hasattr(res, "indicators") and res.indicators:
+        for ind in res.indicators:
+            indicators_data.append({
+                "idno": ind.idno,
+                "database_id": ind.database_id,
+                "database_name": ind.database_name,
+                "name": ind.name,
+                "truncated_definition": ind.truncated_definition,
+                "time_period_range": ind.time_period_range,
+            })
+    return indicators_data
+
+
+
+@mcp.resource("ui://data360-choice/index.html")
+def data360_choice_html() -> str:
+    """HTML resource for the Data360 self-contained choice Custom HTML app."""
+    return """<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Data360 Option Selector</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
+  <style>
+    :root, .light {
+      --bg-color: transparent;
+      --text-color: #0f172a;
+      --card-bg: #f1f5f9;
+      --card-border: transparent;
+      --btn-hover: #e2e8f0;
+      --btn-border: #cbd5e1;
+      --muted-color: #64748b;
+    }
+
+    .dark {
+      --bg-color: transparent;
+      --text-color: #cbd5e1;
+      --card-bg: #1e293b;
+      --card-border: transparent;
+      --btn-hover: #334155;
+      --btn-border: #475569;
+      --muted-color: #94a3b8;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root:not(.light) {
+        --bg-color: transparent;
+        --text-color: #cbd5e1;
+        --card-bg: #1e293b;
+        --card-border: transparent;
+        --btn-hover: #334155;
+        --btn-border: #475569;
+        --muted-color: #94a3b8;
+      }
+    }
+
+    body {
+      margin: 0;
+      padding: 8px 12px;
+      background: var(--bg-color);
+      color: var(--text-color);
+      font-family: "Noto Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      box-sizing: border-box;
+    }
+    .prompt-title {
+      font-size: 1.15rem;
+      font-weight: 500;
+      color: var(--text-color);
+      margin: 0 0 16px 0;
+      line-height: 1.4;
+    }
+    .choices-container {
+      display: flex;
+      gap: 12px;
+      flex-wrap: wrap;
+      width: 100%;
+    }
+    .choice-card {
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+      align-items: flex-start;
+      flex: 1 1 calc(33.333% - 8px);
+      min-width: 180px;
+      padding: 16px 20px;
+      background: var(--card-bg);
+      border: 1px solid var(--card-border);
+      border-radius: 1.25rem;
+      color: var(--text-color);
+      font-size: 0.95rem;
+      font-weight: 500;
+      font-family: inherit;
+      cursor: pointer;
+      text-align: left;
+      outline: none;
+      box-sizing: border-box;
+      transition: background-color 0.15s, border-color 0.15s, transform 0.1s;
+    }
+    .choice-card:hover:not(:disabled) {
+      background: var(--btn-hover);
+      border-color: var(--btn-border);
+      transform: translateY(-1px);
+    }
+    .choice-card:active:not(:disabled) {
+      transform: translateY(0);
+    }
+    .choice-card:disabled {
+      cursor: not-allowed;
+    }
+    .choice-card:disabled:not(.selected) {
+      opacity: 0.4;
+    }
+    .choice-card.selected {
+      background: var(--btn-hover) !important;
+      border-color: var(--btn-border) !important;
+      opacity: 1 !important;
+      transform: none !important;
+    }
+    .choice-text {
+      flex-grow: 1;
+      margin-bottom: 16px;
+      line-height: 1.35;
+    }
+    .routing-icon {
+      font-size: 1.25rem;
+      font-weight: bold;
+      color: var(--text-color);
+      opacity: 0.8;
+    }
+    .response-sent {
+      font-size: 0.9rem;
+      color: var(--muted-color);
+      margin-top: 12px;
+      display: none;
+    }
+    .choice-card.specify-mode {
+      cursor: default;
+      transform: none !important;
+      background: var(--btn-hover);
+      border-color: var(--btn-border);
+      width: 100%;
+      flex: 1 1 100%;
+      align-items: stretch;
+    }
+    .specify-input {
+      flex-grow: 1;
+      background: transparent;
+      border: none;
+      outline: none;
+      color: var(--text-color);
+      font-size: 0.95rem;
+      font-family: inherit;
+      font-weight: 500;
+      padding: 4px 0;
+      width: 100%;
+    }
+    .specify-input::placeholder {
+      color: var(--muted-color);
+      opacity: 0.6;
+    }
+    .specify-submit-btn {
+      background: transparent;
+      border: none;
+      cursor: pointer;
+      font-size: 1.25rem;
+      font-weight: bold;
+      color: var(--text-color);
+      padding: 0 4px;
+      display: flex;
+      align-items: center;
+      outline: none;
+      transition: transform 0.1s;
+    }
+    .specify-submit-btn:hover {
+      transform: scale(1.1);
+    }
+    .specify-submit-btn:active {
+      transform: scale(1.0);
+    }
+  </style>
+</head>
+<body>
+  <p class="prompt-title" id="card-prompt">Loading...</p>
+  <div class="choices-container" id="choices-container"></div>
+  <div class="response-sent" id="sent-msg">Response sent.</div>
+
+  <script type="module">
+    class McpAppClient {
+      constructor() {
+        this.pendingRequests = new Map();
+        this.requestId = 0;
+        this.initialized = false;
+        this.hostContext = null;
+        window.addEventListener('message', (e) => this.handleMessage(e));
+        this.initialize();
+      }
+
+      async initialize() {
+        try {
+          const result = await this.request('ui/initialize', {
+            appInfo: { name: 'Data360 Choice', version: '1.0.0' },
+            appCapabilities: {},
+            protocolVersion: '2025-11-21'
+          });
+          this.hostContext = result.hostContext;
+          this.initialized = true;
+          this.notify('ui/notifications/initialized', {});
+          this.applyTheme();
+          this.reportSize();
+        } catch (error) {
+          console.error('Failed to initialize MCP App:', error);
+        }
+      }
+
+      applyTheme() {
+        const theme = this.hostContext?.theme || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+        if (theme === 'dark') {
+          document.documentElement.classList.add('dark');
+          document.documentElement.classList.remove('light');
+        } else {
+          document.documentElement.classList.add('light');
+          document.documentElement.classList.remove('dark');
+        }
+      }
+
+      handleMessage(event) {
+        const data = event.data;
+        if (!data || typeof data !== 'object') return;
+        if ('id' in data && this.pendingRequests.has(data.id)) {
+          const { resolve, reject } = this.pendingRequests.get(data.id);
+          this.pendingRequests.delete(data.id);
+          if (data.error) {
+            reject(new Error(data.error.message));
+          } else {
+            resolve(data.result);
+          }
+          return;
+        }
+        if (data.method === 'ui/notifications/host-context-changed') {
+          this.hostContext = { ...this.hostContext, ...data.params };
+          this.applyTheme();
+          return;
+        }
+        if (data.method === 'ui/notifications/tool-result') {
+          try {
+            const result = data.params;
+            let payload = null;
+            if (result.content) {
+              const textBlock = result.content.find(c => c.type === 'text');
+              if (textBlock) {
+                payload = JSON.parse(textBlock.text);
+              }
+            }
+            if (payload) {
+              renderChoiceCard(payload);
+            }
+          } catch (e) {
+            console.error('Error parsing tool result:', e);
+          }
+        }
+      }
+
+      request(method, params) {
+        return new Promise((resolve, reject) => {
+          const id = ++this.requestId;
+          this.pendingRequests.set(id, { resolve, reject });
+          window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*');
+          setTimeout(() => {
+            if (this.pendingRequests.has(id)) {
+              this.pendingRequests.delete(id);
+              reject(new Error('Request timed out'));
+            }
+          }, 30000);
+        });
+      }
+
+      notify(method, params) {
+        window.parent.postMessage({ jsonrpc: '2.0', method, params }, '*');
+      }
+
+      reportSize() {
+        this.notify('ui/notifications/size-changed', {
+          height: document.body.scrollHeight
+        });
+      }
+
+      async sendMessageToChat(text) {
+        return this.request('ui/message', {
+          role: 'user',
+          content: [{ type: 'text', text }]
+        });
+      }
+    }
+
+    const mcpApp = new McpAppClient();
+    const promptEl = document.getElementById('card-prompt');
+    const containerEl = document.getElementById('choices-container');
+    const sentMsgEl = document.getElementById('sent-msg');
+
+    function renderChoiceCard(payload) {
+      const prompt = payload.prompt || "";
+      const options = payload.options || [];
+
+      promptEl.textContent = prompt;
+      containerEl.innerHTML = "";
+
+      options.forEach(opt => {
+        const btn = document.createElement('button');
+        btn.className = 'choice-card';
+
+        const txtDiv = document.createElement('div');
+        txtDiv.className = 'choice-text';
+        txtDiv.textContent = opt;
+
+        const iconDiv = document.createElement('div');
+        iconDiv.className = 'routing-icon';
+        iconDiv.textContent = '↪';
+
+        btn.appendChild(txtDiv);
+        btn.appendChild(iconDiv);
+
+        btn.addEventListener('click', async (e) => {
+          const lowerOpt = opt.toLowerCase();
+          if (lowerOpt.includes('specify') || lowerOpt.includes('other') || lowerOpt.includes('custom') || lowerOpt.includes('enter') || opt.endsWith('...')) {
+            if (btn.classList.contains('specify-mode')) {
+              return;
+            }
+
+            // Enter specify mode
+            btn.classList.add('specify-mode');
+            btn.innerHTML = '';
+
+            // Disable other buttons
+            const cards = containerEl.querySelectorAll('.choice-card');
+            cards.forEach(c => {
+              if (c !== btn) {
+                c.style.opacity = '0.3';
+                c.disabled = true;
+              }
+            });
+
+            const form = document.createElement('form');
+            form.style.display = 'flex';
+            form.style.width = '100%';
+            form.style.gap = '8px';
+            form.style.alignItems = 'center';
+            form.style.boxSizing = 'border-box';
+
+            const input = document.createElement('input');
+            input.type = 'text';
+            input.className = 'specify-input';
+            let placeholder = 'Type here...';
+            if (opt.toLowerCase().includes('country')) {
+              placeholder = 'Enter country name...';
+            } else if (opt.toLowerCase().includes('year') || opt.toLowerCase().includes('range') || opt.toLowerCase().includes('timeframe')) {
+              placeholder = 'e.g. 2015-2020';
+            }
+            input.placeholder = placeholder;
+            input.required = true;
+
+            // Focus input
+            setTimeout(() => input.focus(), 10);
+
+            // Handle Escape key to cancel/revert specify mode
+            input.addEventListener('keydown', (ev) => {
+              if (ev.key === 'Escape') {
+                ev.preventDefault();
+                ev.stopPropagation();
+                renderChoiceCard(payload);
+              }
+            });
+
+            const submitBtn = document.createElement('button');
+            submitBtn.type = 'submit';
+            submitBtn.className = 'specify-submit-btn';
+            submitBtn.textContent = '↪';
+
+            form.appendChild(input);
+            form.appendChild(submitBtn);
+            btn.appendChild(form);
+
+            mcpApp.reportSize();
+
+            form.addEventListener('click', (ev) => ev.stopPropagation());
+            form.addEventListener('submit', async (ev) => {
+              ev.preventDefault();
+              const val = input.value.trim();
+              if (!val) return;
+
+              btn.classList.remove('specify-mode');
+              btn.classList.add('selected');
+              btn.innerHTML = '';
+
+              const finalTxt = document.createElement('div');
+              finalTxt.className = 'choice-text';
+              finalTxt.textContent = val;
+
+              const finalIcon = document.createElement('div');
+              finalIcon.className = 'routing-icon';
+              finalIcon.textContent = '↪';
+
+              btn.appendChild(finalTxt);
+              btn.appendChild(finalIcon);
+
+              try {
+                await mcpApp.sendMessageToChat(`\u21AA\uFE0E *${val}*`);
+              } catch (err) {
+                console.error(err);
+                btn.classList.remove('selected');
+                // Restore original list on error
+                renderChoiceCard(payload);
+              }
+            });
+            return;
+          }
+
+          const cards = containerEl.querySelectorAll('.choice-card');
+          cards.forEach(c => c.disabled = true);
+          btn.classList.add('selected');
+
+          mcpApp.reportSize();
+
+          try {
+            await mcpApp.sendMessageToChat(`\u21AA\uFE0E *${opt}*`);
+          } catch (err) {
+            console.error(err);
+            btn.classList.remove('selected');
+            cards.forEach(c => c.disabled = false);
+            mcpApp.reportSize();
+          }
+        });
+        containerEl.appendChild(btn);
+      });
+
+      mcpApp.reportSize();
+      setTimeout(() => mcpApp.reportSize(), 50);
+    }
+
+    window.addEventListener('load', () => {
+      mcpApp.reportSize();
+    });
+  </script>
+</body>
+</html>
+"""
+
+
+@mcp.tool(
+    name="data360_interactive_choices",
+    app=AppConfig(resource_uri="ui://data360-choice/index.html", prefers_border=False),
+)
+async def data360_interactive_choices(
+    prompt: str,
+    options: list[str],
+    title: Optional[str] = None,
+) -> ToolResult:
+    """Present the user with a set of options to choose from using a custom HTML renderer.
+
+    Always call this tool to provide follow-ups and elicitations based on the natural flow of the
+    conversation and the type of information being discussed. Your goal is to anticipate the
+    user's next question or provide an easy way to steer a broad topic.
+
+    Call this tool in the following scenarios:
+
+    1. Single Follow-up (1 choice):
+       - The "Obvious Next Step": When there is one highly logical action to take after your response.
+         For example, if you explain a mathematical concept, offer a follow-up to walk through a practical example.
+       - Deep Dives into Jargon: If your response introduces a complex technical term or a new concept,
+         offer a single follow-up to explain that specific term so the main response does not get too cluttered.
+       - Launching Interactive Tools: If you mention that you can build a widget or run a simulation,
+         provide a single button to let the user trigger that specific interactive element directly.
+
+    2. Multiple Choices (2+ choices):
+       - Broad Overviews & Branching Paths: When you give a high-level summary of a massive topic,
+         use this to let the user choose exactly which sub-category or "branch" you want to zoom in on next.
+       - Disambiguation (Clarifying Intent): If the user's request is open-ended or could be interpreted in
+         a few different ways, present options so the user can clarify exactly which direction they meant to take.
+         Examples:
+         * GDP/Metric variant: "Real GDP per capita (constant 2015 US$)" vs "Nominal GDP per capita (current US$)"
+         * Timeframe/Year range: "Latest available year" vs "Historical trend (last 10 years)" vs "Specify a custom range"
+         * Breakdown/Disaggregation: "Total economy average" vs "Break down by gender (Male vs Female)" vs "Break down by geographic area (Urban vs Rural)"
+       - Menus and Brainstorming: When generating lists of ideas (like different programming frameworks,
+         design patterns, or troubleshooting steps), use this to act like a clickable menu, letting the user
+         instantly select the one you want to explore.
+
+    3. Non-exhaustive Lists (CRITICAL):
+       - If you present a list of choices that is not exhaustive (such as listing a few popular countries,
+         specific years, indicator variants, or breakdowns), you MUST always dynamically include a customizable
+         option as the last item in the options list.
+         Examples:
+         * Country list: options=["Kenya", "Nigeria", "South Africa", "United States", "India", "Specify another country..."]
+         * Year list: options=["2024 (latest)", "Last 5 years", "Last 10 years", "Specify a custom range"]
+         * Breakdowns: options=["Total Average", "Breakdown by Gender", "Other (specify)"]
+
+    Essentially, surface these components whenever you can save the user the effort of typing out the
+    logical next prompt, or when the conversation has reached a crossroads and you need the user to choose
+    the direction.
+
+    Args:
+        prompt: The question or decision to present to the user.
+        options: List of options the user can choose from.
+        title: Optional heading for the card.
+    """
+    payload = {
+        "prompt": prompt,
+        "options": options,
+        "title": title or "Choose an Option"
+    }
+    return ToolResult(
+        content=[TextContent(type="text", text=json.dumps(payload))]
+    )
+

src/data360/models.py

@@ -0,0 +1,942 @@
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+# Prefix used by the search API's metadata_link entries.
+# Strip this to derive the usable indicator_id.
+_META_ID_PREFIX = "META_"
+
+
+def sanitize_search_query(query: str) -> str:
+    """Validate search query and sanitize unsafe characters for Search V3."""
+    if not query or not query.strip():
+        raise ValueError("Search query cannot be empty")
+    # Strip parentheses, dollar signs, and other punctuation that causes Search V3 to return 0 results.
+    # Preserve alphanumerics, underscores, hyphens, commas, and periods.
+    cleaned = re.sub(r"[^\w\s\-\,\.]", " ", query)
+    sanitized = " ".join(cleaned.split())
+    if not sanitized or not sanitized.strip():
+        raise ValueError("Search query cannot be empty after sanitization")
+    return sanitized
+
+
+
+class MCPPagedResponse(BaseModel):
+    """Response model for MCP paged results.
+    For more information, see: https://github.com/anthropics/skills/blob/main/skills/mcp-builder/reference/mcp_best_practices.md#pagination
+
+    Always respect limit parameter
+    Return has_more, next_offset, total_count
+    Default to 20-50 items
+    """
+
+    count: int = Field(default=0, description="Number of results in the current page")
+    total_count: int | None = Field(default=None, description="Total number of results")
+    offset: int | None = Field(default=None, description="Offset of the current page")
+    has_more: bool | None = Field(
+        default=None, description="Whether there are more results"
+    )
+    next_offset: int | None = Field(default=None, description="Offset of the next page")
+
+
+class SearchRequest(BaseModel):
+    """Request model for data360 search queries."""
+
+    query: str = Field(
+        ..., description="Search query string to find relevant data series"
+    )
+    limit: int = Field(
+        default=10,
+        description="Number of results to return (default is 10)",
+        ge=1,
+        le=50,
+    )
+    count: bool = Field(
+        default=True, description="Whether to include total count in response"
+    )
+    filter: str | None = Field(
+        default=None,
+        description="OData filter expression (e.g., \"type eq 'indicator'\")",
+    )
+    orderby: str | None = Field(
+        default=None,
+        description='OData orderby expression (e.g., "series_description/name")',
+    )
+    select: str | None = Field(
+        default=None,
+        description='OData select expression (e.g., "series_description/idno, series_description/name")',
+    )
+    offset: int = Field(default=0, description="Offset of the current page")
+
+    @model_validator(mode="after")
+    def validate_query(self) -> "SearchRequest":
+        """Validate search query and sanitize unsafe characters."""
+        self.query = sanitize_search_query(self.query)
+        return self
+
+    @model_validator(mode="after")
+    def set_select_default(self) -> "SearchRequest":
+        """Set default select value when None is provided."""
+        if self.select is None:
+            self.select = "series_description/idno, series_description/name, series_description/database_id, series_description/definition_long"
+        return self
+
+    @model_validator(mode="after")
+    def set_filter_default(self) -> "SearchRequest":
+        """Set default filter value when None is provided."""
+        if self.filter is None:
+            # Default to indicator
+            self.filter = "type eq 'indicator'"
+        return self
+
+
+class PrimarySourceInfo(BaseModel):
+    """A single metadata_link entry identifying a primary source indicator.
+
+    The search API returns this under ``additional.metadata_link`` when an
+    indicator has been curated to point to its authoritative primary source
+    (typically in WDI).
+    """
+
+    type: str = Field(..., description="Link type (e.g. 'primary')")
+    metadata_id: str = Field(
+        ...,
+        description="Metadata ID with META_ prefix (e.g. META_WB_WDI_SP_POP_TOTL)",
+    )
+    database_id: str | None = Field(
+        None, description="Primary source database (e.g. WB_WDI)"
+    )
+    database_name: str | None = Field(
+        None, description="Human-readable database name"
+    )
+
+    @property
+    def indicator_id(self) -> str:
+        """Derive the usable indicator_id by stripping the META_ prefix."""
+        if self.metadata_id.startswith(_META_ID_PREFIX):
+            return self.metadata_id[len(_META_ID_PREFIX) :]
+        return self.metadata_id
+
+
+class SeriesDescription(BaseModel):
+    """Model for series description in search results.
+
+    Fields available via select_fields in search:
+    - idno, name, database_id, definition_long (core)
+    - periodicity, time_periods, ref_country, dimensions (extended)
+    """
+
+    idno: str = Field(..., description="Series identifier")
+    name: str = Field(..., description="Series name")
+    database_id: str = Field(..., description="Database identifier")
+    definition_long: str | None = Field(None, description="Series definition")
+    periodicity: str | None = Field(
+        None, description="Data periodicity (Annual, Monthly, etc)"
+    )
+    time_periods: list[dict[str, Any]] | None = Field(
+        None, description="Time period coverage"
+    )
+    ref_country: list[dict[str, Any] | str] | None = Field(
+        None, description="Countries with data"
+    )
+    dimensions: list[dict[str, Any]] | None = Field(
+        None, description="Available disaggregations"
+    )
+    metadata_link: list[PrimarySourceInfo] = Field(
+        default_factory=list,
+        description="Metadata links from the API's additional.metadata_link field.",
+    )
+    connected_entities: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Connected secondary entities for SearchV3 redirect mapping.",
+    )
+
+    @property
+    def primary_source(self) -> PrimarySourceInfo | None:
+        """Return the first primary-type metadata link, or None."""
+        return next((link for link in self.metadata_link if link.type == "primary"), None)
+
+
+class SearchResponse(MCPPagedResponse):
+    """Response model for data360 search results (raw API response)."""
+
+    items: list[SeriesDescription] | None = Field(
+        default=None, description="List of search results containing series information"
+    )
+    error: str | None = Field(
+        default=None, description="Error message if search failed"
+    )
+
+
+class EnrichedIndicator(BaseModel):
+    """Model for an enriched indicator in search results.
+
+    Optimized for LLM consumption with compact, relevant fields.
+    """
+
+    idno: str = Field(..., description="Indicator ID (e.g., WB_GS_NY_GDP_PCAP_KD)")
+    database_id: str = Field(..., description="Database ID (e.g., WB_GS)")
+    database_name: str | None = Field(
+        None,
+        description="Human-readable dataset name for the database_id "
+        "(e.g., 'Gender Statistics' for WB_GS). "
+        "Use this when presenting data to users — never expand database_id by guessing.",
+    )
+    name: str = Field(..., description="Indicator name")
+    truncated_definition: str = Field(
+        ..., description="Truncated definition (max 100 chars)"
+    )
+    periodicity: str | None = Field(
+        None, description="Data periodicity (Annual, Monthly)"
+    )
+    latest_data: str | None = Field(None, description="Most recent year with data")
+    time_period_range: str | None = Field(
+        None, description="Data availability range (e.g., '1990-2024')"
+    )
+    covers_country: dict[str, bool] | None = Field(
+        None,
+        description="Per-country coverage map (e.g. {'KEN': True, 'GHA': False}). "
+        "Populated when required_country is provided. None when no country was requested.",
+    )
+    requested_country: str | None = Field(
+        None,
+        description="Resolved country code this indicator was evaluated against "
+        "(set when per-group countries are used via query_groups; also set for "
+        "single-query path when required_country is provided).",
+    )
+    dimensions: list[str] | None = Field(
+        None, description="Available disaggregations (SEX, AGE, URBANISATION)"
+    )
+    primary_source_of: str | None = Field(
+        None,
+        description="When this indicator was redirected from a secondary source, "
+        "contains the original secondary idno (e.g. 'WB_HNP_SP_POP_TOTL'). "
+        "None if the indicator was already the primary source.",
+    )
+
+
+class EnrichedSearchResponse(MCPPagedResponse):
+    """Response model for enriched search (LLM-optimized).
+
+    Returns indicators sorted by country coverage and recency.
+    """
+
+    indicators: list[EnrichedIndicator] = Field(
+        default_factory=list, description="Enriched indicators sorted by relevance"
+    )
+    required_country: str | None = Field(
+        None,
+        description="Resolved country code(s). Semicolon-separated for multiple countries "
+        "(e.g. 'KEN' or 'KEN;GHA').",
+    )
+    country_names: dict[str, str] | None = Field(
+        None, description="Resolved names of requested countries"
+    )
+    error: str | None = Field(None, description="Error message if search failed")
+
+
+class QueryGroup(BaseModel):
+    """A group of search queries scoped to an optional country.
+
+    Allows binding multiple search terms to a specific geographic scope
+    in a single search() call. Used with the query_groups parameter.
+
+    Example::
+
+        QueryGroup(queries=["GDP per capita", "inflation rate"], country="Kenya")
+    """
+
+    queries: list[str] = Field(
+        ...,
+        description="Search terms for this group (e.g., ['GDP per capita', 'inflation rate']). "
+        "At least one non-empty string required.",
+        min_length=1,
+    )
+    country: str | None = Field(
+        None,
+        description="Country name or 3-letter code for this group (e.g., 'Kenya' or 'KEN'). "
+        "If None, no country filtering is applied to indicators in this group.",
+    )
+
+
+class QueryGroupResult(BaseModel):
+    """Result group for a single query within a multi-query search.
+
+    Only returned when result_layout='by_query'.
+    """
+
+    query: str = Field(..., description="The search query that produced these results")
+    country_code: str | None = Field(
+        None,
+        description="Resolved country code for this query group (e.g., 'KEN'). "
+        "Set when query_groups is used and a country was specified for this group.",
+    )
+    indicators: list[EnrichedIndicator] = Field(
+        default_factory=list, description="Indicators found for this query"
+    )
+    count: int = Field(default=0, description="Number of indicators in this group")
+    error: str | None = Field(
+        None, description="Error message if this sub-query failed"
+    )
+
+
+class MultiQuerySearchResponse(BaseModel):
+    """Response for multi-query search (when queries parameter is used).
+
+    result_layout='merged': indicators contains a flat, deduped list.
+    result_layout='by_query': results contains one group per input query.
+    dedupe=True with by_query means cross-group dedup — first group to
+    claim an indicator keeps it; later groups skip it.
+    """
+
+    indicators: list[EnrichedIndicator] = Field(
+        default_factory=list,
+        description="Flat indicator list. Populated when result_layout='merged'; "
+        "empty when 'by_query' (see results field instead).",
+    )
+    results: list[QueryGroupResult] | None = Field(
+        None,
+        description="Per-query result groups (result_layout='by_query')",
+    )
+    result_layout: Literal["merged", "by_query"] = Field(
+        "merged", description="Layout mode used: 'merged' or 'by_query'"
+    )
+    queries: list[str] = Field(
+        default_factory=list, description="The input query strings"
+    )
+    required_country: str | None = Field(
+        None,
+        description="Resolved country code(s) used for all sub-queries. "
+        "Semicolon-separated for multiple countries (e.g. 'KEN;GHA').",
+    )
+    country_names: dict[str, str] | None = Field(
+        None, description="Resolved names of requested countries"
+    )
+    total_candidates: int = Field(
+        0,
+        description="Total indicators found before dedup (merged) or across all groups (by_query)",
+    )
+    deduplicated_count: int | None = Field(
+        None, description="Number of duplicates removed (merged layout only)"
+    )
+    error: str | None = Field(
+        None, description="Top-level error if the entire multi-query operation failed"
+    )
+
+
+class MetadataRequest(BaseModel):
+    """Request model for data 360 metadata retrieval."""
+
+    indicator_id: str = Field(
+        ..., description="Series ID (idno) to retrieve metadata for"
+    )
+    database_id: str = Field(
+        ..., description="Database identifier (e.g., IPC_IPC, WB_GS)"
+    )
+
+    @model_validator(mode="after")
+    def validate_ids(self) -> "MetadataRequest":
+        """Validate database_id and indicator_id logic."""
+        if not self.database_id or not self.database_id.strip():
+            raise ValueError("database_id cannot be empty or whitespace-only.")
+        if not self.indicator_id or not self.indicator_id.strip():
+            raise ValueError("indicator_id cannot be empty or whitespace-only.")
+        if self.database_id == self.indicator_id:
+            raise ValueError(
+                f"Invalid database_id: '{self.database_id}'. It matches indicator_id."
+            )
+
+        return self
+
+
+class MetadataResponse(BaseModel):
+    """Response model for metadata retrieval."""
+
+    indicator_metadata: dict[str, Any] | None = Field(
+        default=None, description="Metadata information for the requested series"
+    )
+    disaggregation_options: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Available disaggregation options for the indicator",
+    )
+    error: str | None = Field(
+        default=None, description="Error message if metadata retrieval failed"
+    )
+
+
+class IndicatorDataRequest(BaseModel):
+    """Request model for retrieving indicator data from Data360 API."""
+
+    database_id: str = Field(
+        ..., description="Unique identifier for the database (e.g., WB_GS)"
+    )
+    indicator_id: str = Field(
+        ..., description="Indicator ID (e.g., WB_GS_NY_GDP_PCAP_KD)"
+    )
+    disaggregation_filters: dict[str, str | None] | None = Field(
+        default=None,
+        description=(
+            "Per-dimension filters: each value is a string or null (never a JSON array). "
+            "Example: {'REF_AREA': 'KEN', 'UNIT_MEASURE': 'KD'}. "
+            "Multiple areas: comma-separated ISO codes in REF_AREA (e.g. 'KEN,TZA'); "
+            "semicolons in REF_AREA are accepted and normalized to commas. "
+            "Use null for a dimension to request all values of that dimension."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_ids(self) -> "IndicatorDataRequest":
+        """Validate database_id and indicator_id logic."""
+        if not self.database_id or not self.database_id.strip():
+            raise ValueError("database_id cannot be empty or whitespace-only.")
+        if not self.indicator_id or not self.indicator_id.strip():
+            raise ValueError("indicator_id cannot be empty or whitespace-only.")
+        # 1. Check if database_id is suspicious (same as indicator_id)
+        if self.database_id == self.indicator_id:
+            raise ValueError(
+                f"Invalid database_id: '{self.database_id}'. It matches indicator_id. "
+                "Database ID should be the short dataset code (e.g., 'WB_GS', 'WB_HCP')."
+            )
+
+        return self
+
+
+class IndicatorDataResponse(MCPPagedResponse):
+    """Response model for indicator data retrieval."""
+
+    data: list[dict[str, Any]] | None = Field(
+        default=None, description="List of indicator data points"
+    )
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Basic metadata for the indicator (e.g., name, definition)",
+    )
+    error: str | None = Field(
+        default=None, description="Error message if data retrieval failed"
+    )
+    failed_validation: list[str] | None = Field(
+        default=None, description="List of filter validation errors"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Data Aggregation Tool Models (Tier 1 — full implementation)
+# ---------------------------------------------------------------------------
+
+
+class GroupSummary(BaseModel):
+    """Summary statistics for a single group in a summarize_data response."""
+
+    group_key: dict[str, str] = Field(
+        ...,
+        description="Dimension values defining this group "
+        '(e.g. {"ref_area": "KEN"} or {"ref_area": "KEN", "sex": "F"})',
+    )
+    count: int = Field(..., description="Number of observations in this group")
+    latest_value: float | None = Field(None, description="Most recent obs_value")
+    latest_year: str | None = Field(None, description="Year of latest_value")
+    earliest_value: float | None = Field(None, description="Oldest obs_value in range")
+    earliest_year: str | None = Field(None, description="Year of earliest_value")
+    min: float | None = Field(None, description="Minimum obs_value")
+    max: float | None = Field(None, description="Maximum obs_value")
+    mean: float | None = Field(None, description="Arithmetic mean of obs_values")
+    median: float | None = Field(None, description="Median obs_value")
+    total_change: float | None = Field(
+        None, description="latest - earliest (absolute change)"
+    )
+    pct_change: float | None = Field(
+        None,
+        description="((latest - earliest) / |earliest|) * 100. "
+        "None if earliest is zero or missing.",
+    )
+    trend_direction: str | None = Field(
+        None,
+        description="'increasing', 'decreasing', 'stable', or 'volatile'. "
+        "Based on linear regression slope and R² over the series.",
+    )
+    time_range: str | None = Field(
+        None, description="Actual data range (e.g. '2005-2023')"
+    )
+    claim_ids: list[str] = Field(
+        default_factory=list,
+        description="Source claim_ids from underlying raw observations",
+    )
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        claim_ids are retained here — they are 8-character PCN hashes and the
+        UI needs them to render provenance attribution per group. The token cost
+        is bounded (one hash per observation per group) and preserves the
+        group→claim_ids association that a flat top-level list would lose.
+        """
+        return {
+            "group": self.group_key,
+            "n": self.count,
+            "latest": {"value": self.latest_value, "year": self.latest_year},
+            "earliest": {"value": self.earliest_value, "year": self.earliest_year},
+            "range": self.time_range,
+            "stats": {
+                "min": self.min,
+                "max": self.max,
+                "mean": self.mean,
+                "median": self.median,
+            },
+            "change": {"abs": self.total_change, "pct": self.pct_change},
+            "trend": self.trend_direction,
+            "claim_ids": self.claim_ids,
+        }
+
+
+class DataSummaryResponse(BaseModel):
+    """Response model for data360_summarize_data."""
+
+    groups: list[GroupSummary] = Field(
+        default_factory=list, description="Per-group summary statistics"
+    )
+    metadata: dict[str, Any] | None = Field(
+        None, description="Indicator metadata (name, definition, database_name)"
+    )
+    unit_measure: str | None = Field(
+        None, description="Unit of measurement for interpreting values"
+    )
+    error: str | None = Field(
+        None, description="Error message if request failed; otherwise None"
+    )
+    ambiguous_dimensions: list[str] | None = Field(
+        None,
+        description=(
+            "Disaggregation dimensions present in the data with more than one distinct "
+            "value that are NOT included in group_by. When non-empty, the per-group "
+            "time-series statistics may be computed over mixed disaggregation values "
+            "(e.g. SEX=M, F, and _T all collapsed into one group), making trend and "
+            "summary stats unreliable. To fix: either add these dimensions to group_by "
+            "(e.g. group_by=['ref_area', 'sex']) or pass disaggregation_filters to pin "
+            "each dimension to a single value (e.g. {'SEX': '_T'})."
+        ),
+    )
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        claim_ids are excluded from each GroupSummary entry — they are PCN
+        hashes retained in the full model for provenance traceability.
+        """
+        return {
+            "indicator": self.metadata.get("name") if self.metadata else None,
+            "unit": self.unit_measure,
+            "ambiguous_dimensions": self.ambiguous_dimensions,
+            "groups": [g.to_compact() for g in self.groups],
+            "error": self.error,
+        }
+
+
+class RankedCountry(BaseModel):
+    """A single country entry in a ranking result."""
+
+    rank: int = Field(..., description="Ordinal rank (ties share the same rank)")
+    ref_area: str = Field(..., description="Country/region code (e.g. 'KEN')")
+    country_name: str | None = Field(None, description="Human-readable country name")
+    obs_value: float = Field(..., description="The indicator value for ranking year")
+    percentile: float | None = Field(
+        None,
+        description="Percentile position (0-100) within the ranked set",
+    )
+    claim_id: str | None = Field(
+        None, description="Claim ID from the source observation"
+    )
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        claim_id is retained — it is the PCN hash for this observation and the
+        UI needs it to render per-entry provenance attribution. Only percentile
+        is dropped; it is derivable from rank order and adds no LLM value.
+        """
+        return {
+            "rank": self.rank,
+            "code": self.ref_area,
+            "country": self.country_name or self.ref_area,
+            "value": self.obs_value,
+            "claim_id": self.claim_id,
+        }
+
+
+class ExcludedCountry(BaseModel):
+    """A country excluded from ranking due to missing data."""
+
+    ref_area: str = Field(..., description="Country/region code")
+    country_name: str | None = Field(None, description="Human-readable country name")
+    reason: str = Field(..., description="Why the country was excluded")
+
+
+class RankingResponse(BaseModel):
+    """Response model for data360_rank_countries."""
+
+    year: str | None = Field(None, description="The year used for ranking")
+    year_selection_note: str | None = Field(
+        None,
+        description="Explains how the ranking year was chosen. "
+        "E.g. 'Latest year with broadest coverage (2022, 18/20 countries)' "
+        "or 'Most recent year (2023, 12/20 countries)'.",
+    )
+    order: str = Field(
+        "desc", description="'desc' (highest first) or 'asc' (lowest first)"
+    )
+    total_with_data: int = Field(0, description="Number of countries that had data")
+    total_requested: int = Field(0, description="Number of countries attempted")
+    universe: str | None = Field(
+        None,
+        description=(
+            "'explicit' when country_group or country_codes was used; "
+            "'all_member_economies' when ranking used full geographic fetch with "
+            "member-economy row filtering."
+        ),
+    )
+    universe_size: int | None = Field(
+        None,
+        description=(
+            "For explicit scope: same as total_requested. For all_member_economies: "
+            "count of known FMR leaf economies in the ranking universe."
+        ),
+    )
+    rankings: list[RankedCountry] = Field(
+        default_factory=list, description="Ranked list of countries"
+    )
+    excluded: list[ExcludedCountry] = Field(
+        default_factory=list, description="Countries with no data for ranking year"
+    )
+    metadata: dict[str, Any] | None = Field(None, description="Indicator metadata")
+    unit_measure: str | None = Field(None, description="Unit of measurement")
+    error: str | None = Field(None, description="Error message if request failed")
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        Key reductions vs. the full model:
+        - rankings: claim_id and percentile dropped from each entry (PCN hash
+          retained in the full RankedCountry model).
+        - excluded: capped at 5 sample entries; full count is in excluded_count.
+          This prevents 30+ excluded entries from flooding the context when
+          ranking a large group like SSF (48 countries).
+        """
+        return {
+            "year": self.year,
+            "year_selection_note": self.year_selection_note,
+            "order": self.order,
+            "counts": {
+                "with_data": self.total_with_data,
+                "requested": self.total_requested,
+            },
+            "unit": self.unit_measure,
+            "indicator": self.metadata.get("name") if self.metadata else None,
+            "rankings": [r.to_compact() for r in self.rankings],
+            "excluded_count": len(self.excluded),
+            "excluded_sample": [
+                {"code": e.ref_area, "name": e.country_name}
+                for e in self.excluded[:5]
+            ],
+            "error": self.error,
+        }
+
+
+class ComparisonSnapshot(BaseModel):
+    """Single-year comparison snapshot across countries."""
+
+    year: str = Field(..., description="The comparison year")
+    year_selection_note: str | None = Field(
+        None,
+        description="Explains how the comparison year was chosen. "
+        "E.g. 'User-specified year: 2022' or 'Latest year with data for all compared countries: 2023'.",
+    )
+    rankings: list[RankedCountry] = Field(
+        default_factory=list,
+        description="Countries sorted by obs_value with rank and gap_to_leader",
+    )
+    spread: dict[str, float | None] = Field(
+        default_factory=dict,
+        description="Spread statistics: min, max, range, coefficient_of_variation",
+    )
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        Delegates to RankedCountry.to_compact() for each ranked entry, which
+        retains claim_id (PCN hash) and drops percentile. claim_id is preserved
+        here so the UI can render per-country provenance attribution in the
+        snapshot table.
+        """
+        return {
+            "year": self.year,
+            "year_selection_note": self.year_selection_note,
+            "rankings": [r.to_compact() for r in self.rankings],
+            "spread": self.spread,
+        }
+
+
+class ComparisonTimeSeries(BaseModel):
+    """Time-series comparison across countries."""
+
+    aligned_years: list[str] = Field(
+        default_factory=list,
+        description="Years where ALL compared countries have data",
+    )
+    series: dict[str, list[dict[str, Any]]] = Field(
+        default_factory=dict,
+        description="Per-country time series: {ref_area: [{time_period, obs_value, claim_id}]}",
+    )
+    convergence: str | None = Field(
+        None,
+        description="'converging', 'diverging', or 'parallel'. "
+        "Based on coefficient of variation trend across aligned years.",
+    )
+    cagr: dict[str, float | None] = Field(
+        default_factory=dict,
+        description="Compound annual growth rate per country over aligned period",
+    )
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        The per-year ``series`` dict is retained but restructured: each data
+        point is encoded as a positional array ``[time_period, obs_value, claim_id]``
+        instead of a named dict. This reduces per-point overhead from ~55 chars
+        to ~24 chars (~56% reduction) while preserving the year→value→PCN
+        association the UI needs for provenance attribution.
+
+        A ``series_schema`` field documents the array positions so the UI
+        decoder does not need to hard-code positional assumptions.
+
+        ``aligned_years`` list is replaced by ``year_range`` + ``n_aligned_years``
+        since the LLM only needs to know the span, not the individual years.
+        """
+        year_range = (
+            f"{self.aligned_years[0]}-{self.aligned_years[-1]}"
+            if self.aligned_years
+            else None
+        )
+        compact_series = {
+            country: [
+                [pt["time_period"], pt["obs_value"], pt.get("claim_id")]
+                for pt in points
+            ]
+            for country, points in self.series.items()
+        }
+        return {
+            "year_range": year_range,
+            "n_aligned_years": len(self.aligned_years),
+            "convergence": self.convergence,
+            "cagr": self.cagr,
+            "series_schema": ["time_period", "obs_value", "claim_id"],
+            "series": compact_series,
+        }
+
+
+class CountryComparisonResponse(BaseModel):
+    """Response model for data360_compare_countries."""
+
+    snapshot: ComparisonSnapshot | None = Field(
+        None, description="Single-year ranked comparison"
+    )
+    time_series: ComparisonTimeSeries | None = Field(
+        None,
+        description="Aligned time-series comparison (when include_time_series=True)",
+    )
+    metadata: dict[str, Any] | None = Field(None, description="Indicator metadata")
+    unit_measure: str | None = Field(None, description="Unit of measurement")
+    error: str | None = Field(None, description="Error message if request failed")
+    country_names: dict[str, str] | None = Field(None, description="Resolved names of compared countries")
+
+    def to_compact(self) -> dict[str, Any]:
+        """Return a slimmed dict for LLM context.
+
+        Delegates to ComparisonSnapshot.to_compact() and
+        ComparisonTimeSeries.to_compact(), which strip claim_ids (PCN hashes)
+        and per-year series data respectively.
+        """
+        return {
+            "indicator": self.metadata.get("name") if self.metadata else None,
+            "unit": self.unit_measure,
+            "snapshot": self.snapshot.to_compact() if self.snapshot else None,
+            "time_series": self.time_series.to_compact() if self.time_series else None,
+            "country_names": self.country_names,
+            "error": self.error,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Data Aggregation Tool Models (Tier 2 — stubs for future implementation)
+# ---------------------------------------------------------------------------
+
+
+class DerivedDataResponse(BaseModel):
+    """Response model for data360_compute_derived (stub — not yet implemented).
+
+    Will contain derived/transformed values (growth rates, CAGR, moving averages,
+    index rebasing) computed from raw indicator data.
+    """
+
+    computation: str | None = Field(None, description="Computation type applied")
+    data: list[dict[str, Any]] = Field(
+        default_factory=list, description="Computed values"
+    )
+    summary: str | None = Field(None, description="Human-readable one-line summary")
+    metadata: dict[str, Any] | None = Field(None, description="Indicator metadata")
+    unit_measure: str | None = Field(None, description="Original unit")
+    derived_unit: str | None = Field(
+        None, description="Unit for derived values (e.g. '%' for growth_rate)"
+    )
+    error: str | None = Field(None, description="Error message if request failed")
+
+
+class PivotTableResponse(BaseModel):
+    """Response model for data360_pivot_table (stub — not yet implemented).
+
+    Will contain a cross-tabulation of multiple indicators and/or countries,
+    organized as a structured table with row/column dimensions.
+    """
+
+    table: list[dict[str, Any]] = Field(default_factory=list, description="Table rows")
+    column_metadata: list[dict[str, Any]] = Field(
+        default_factory=list, description="Per-column metadata"
+    )
+    claim_map: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping of cell keys to source claim_ids",
+    )
+    missing_cells: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="Cells with no data: [{row, column, reason}]",
+    )
+    error: str | None = Field(None, description="Error message if request failed")
+
+
+class DiagnosticIndicatorSummary(BaseModel):
+    """Per-indicator summary within a diagnostic summary response (stub)."""
+
+    indicator_id: str = Field(..., description="Indicator ID")
+    database_id: str = Field(..., description="Database ID")
+    name: str = Field(..., description="Indicator name")
+    latest_value: float | None = Field(None, description="Most recent value")
+    latest_year: str | None = Field(None, description="Year of latest value")
+    trend_direction: str | None = Field(
+        None, description="'increasing', 'decreasing', 'stable', 'volatile'"
+    )
+    pct_change: float | None = Field(None, description="Percent change over period")
+    time_range: str | None = Field(None, description="Actual data range")
+    claim_ids: list[str] = Field(default_factory=list, description="Source claim_ids")
+    coverage_note: str | None = Field(None, description="Gaps or caveats")
+
+
+class DiagnosticSummaryResponse(BaseModel):
+    """Response model for data360_diagnostic_summary (stub — not yet implemented).
+
+    Will contain a multi-indicator diagnostic summary for a topic and country,
+    with per-indicator trend analysis and cross-indicator notes.
+    """
+
+    topic: str | None = Field(None, description="Diagnostic category used")
+    country_code: str | None = Field(None, description="Resolved country code(s)")
+    indicators: list[DiagnosticIndicatorSummary] = Field(
+        default_factory=list, description="Per-indicator summaries"
+    )
+    gaps: list[str] = Field(
+        default_factory=list,
+        description="Topics searched but no indicator found",
+    )
+    metadata_sources: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="List of {database_id, database_name} used",
+    )
+    error: str | None = Field(None, description="Error message if request failed")
+
+
+class DiscoveredIndicator(BaseModel):
+    """Model for a discovered and validated indicator."""
+
+    indicator_id: str = Field(..., description="Indicator ID")
+    database_id: str = Field(..., description="Database identifier")
+    name: str = Field(..., description="Indicator name")
+    truncated_definition: str = Field(
+        ..., description="Short definition (max 100 chars)"
+    )
+    has_country: bool = Field(
+        ..., description="Whether data exists for the requested country"
+    )
+    country_code: str | None = Field(
+        default=None, description="Country code used for validation"
+    )
+    available_dimensions: list[str] = Field(
+        default_factory=list, description="List of available disaggregation dimensions"
+    )
+    available_frequencies: list[str] = Field(
+        default_factory=list, description="List of available frequencies"
+    )
+    periodicity: str | None = Field(
+        default=None, description="Periodicity of the indicator"
+    )
+    has_required_dimensions: bool = Field(
+        default=True, description="Whether the indicator has all required dimensions"
+    )
+    time_range: dict[str, str | None] | None = Field(
+        default=None, description="Start and end years of data availability"
+    )
+    error: str | None = Field(
+        default=None, description="Error message if validation failed"
+    )
+
+
+class DiscoveryResult(BaseModel):
+    """Result of indicator discovery process."""
+
+    indicators: list[DiscoveredIndicator] = Field(
+        default_factory=list, description="List of discovered and validated indicators"
+    )
+    error: str | None = Field(
+        default=None, description="Error message if discovery failed entirely"
+    )
+
+
+class DatasetSearchRequest(BaseModel):
+    """Request model for dataset search queries. Includes V3 special character sanitization."""
+
+    query: str = Field(
+        ..., description="Search query string to find relevant datasets"
+    )
+    limit: int = Field(
+        default=10,
+        description="Number of results to return (default is 10)",
+        ge=1,
+        le=50,
+    )
+    offset: int = Field(default=0, description="Offset of the current page")
+
+    @model_validator(mode="after")
+    def validate_query(self) -> "DatasetSearchRequest":
+        """Validate search query and sanitize unsafe characters."""
+        self.query = sanitize_search_query(self.query)
+        return self
+
+
+class DatasetDescription(BaseModel):
+    """Model for dataset description in search results."""
+
+    idno: str = Field(..., description="Dataset identifier")
+    name: str = Field(..., description="Dataset name")
+    description: str | None = Field(None, description="Dataset description")
+    data_classification: str | None = Field(None, description="Data classification (e.g. public)")
+    data_last_updated: str | None = Field(None, description="Last updated timestamp")
+    economies_count: int | None = Field(None, description="Number of economies covered")
+    time_period: dict[str, Any] | None = Field(None, description="Time period range covered")
+
+
+class DatasetSearchResponse(MCPPagedResponse):
+    """Response model for data360 dataset search results."""
+
+    items: list[DatasetDescription] = Field(
+        default_factory=list, description="List of search results containing dataset information"
+    )
+    error: str | None = Field(
+        default=None, description="Error message if search failed"
+    )

src/data360/otel_setup.py

@@ -0,0 +1,179 @@
+"""OpenTelemetry setup: Azure Monitor (deployed), OTLP/console (local), httpx outbound spans."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from data360.config import MCPServerSettings
+
+_logger = logging.getLogger(__name__)
+
+_HTTPX_INSTRUMENTED = False
+_MIN_TRANSPORT_PARTS_FOR_URL = 2
+
+
+def data360_operation_from_url(url: str | None) -> str:  # noqa: PLR0911
+    """Derive a stable operation label for spans from the outbound request URL (no query logged)."""
+    if not url:
+        return "http"
+    try:
+        path = urlparse(url).path.lower()
+    except Exception:
+        return "http"
+    if "searchv2" in path:
+        return "search"
+    if "metadata" in path:
+        return "metadata"
+    if "disaggregation" in path:
+        return "disaggregation"
+    # Avoid matching .../metadata/... "data" substring before generic data path
+    if path.rstrip("/").endswith("/data") or "/data360/data" in path:
+        return "data"
+    if "codelist" in path:
+        return "codelist"
+    if path.rstrip("/").endswith("/indicators"):
+        return "indicators"
+    if "chart" in path or "vega" in path:
+        return "charts"
+    return "http"
+
+
+def _httpx_request_hook(span, request: object) -> None:
+    """Attach Data360-specific attributes; never log bodies or full URLs with secrets."""
+    try:
+        if span is None:
+            return
+        is_recording = getattr(span, "is_recording", None)
+        if callable(is_recording) and not is_recording():
+            return
+        url_str: str | None = None
+        if isinstance(request, tuple) and len(request) >= _MIN_TRANSPORT_PARTS_FOR_URL:
+            url_str = str(request[1])
+        else:
+            req_any = cast("Any", request)
+            url_attr = getattr(req_any, "url", None)
+            if url_attr is not None:
+                url_str = str(url_attr)
+        op = data360_operation_from_url(url_str)
+        span.set_attribute("data360.operation", op)
+        if url_str:
+            try:
+                parsed = urlparse(url_str)
+                netloc = parsed.netloc.split("@")[-1]
+                span.set_attribute("server.address", netloc.split(":")[0])
+            except Exception:
+                pass
+    except Exception:
+        pass
+
+
+def _httpx_response_hook(span, request: object, response: object) -> None:
+    """Record outcome; avoid logging bodies."""
+    try:
+        if span is None:
+            return
+        is_recording = getattr(span, "is_recording", None)
+        if callable(is_recording) and not is_recording():
+            return
+        status = getattr(response, "status_code", None)
+        if status is not None:
+            span.set_attribute("http.response.status_code", int(status))
+    except Exception:
+        pass
+
+
+def configure_open_telemetry_for_server(settings: MCPServerSettings) -> None:
+    """Configure trace export: Azure Monitor when deployed; OTLP or console when local."""
+    connection_string = settings.azure_connection_string or os.environ.get(
+        "APPLICATIONINSIGHTS_CONNECTION_STRING"
+    )
+    env = (settings.env or "").lower()
+
+    if env != "local" and connection_string:
+        try:
+            from azure.monitor.opentelemetry import (  # type: ignore[import-untyped]  # noqa: PLC0415
+                configure_azure_monitor,
+            )
+
+            configure_azure_monitor(connection_string=connection_string)
+            _logger.info("Azure Monitor OpenTelemetry configured.")
+        except ImportError:
+            _logger.warning("azure-monitor-opentelemetry not available.")
+        return
+
+    # Local / no Azure: optional OTLP (Jaeger, collector) or console exporter
+    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT") or os.environ.get(
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
+    )
+    console = os.environ.get("MCP_OTEL_CONSOLE", "").lower() in ("1", "true", "yes")
+
+    if not endpoint and not console:
+        _logger.debug(
+            "Local telemetry: no OTLP endpoint and MCP_OTEL_CONSOLE unset; "
+            "traces use noop unless OTEL_* env configures a provider elsewhere."
+        )
+        return
+
+    from opentelemetry import trace  # noqa: PLC0415
+    from opentelemetry.sdk.resources import SERVICE_NAME, Resource  # noqa: PLC0415
+    from opentelemetry.sdk.trace import TracerProvider  # noqa: PLC0415
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor  # noqa: PLC0415
+
+    service_name = os.environ.get("OTEL_SERVICE_NAME", "data360-mcp")
+    resource = Resource.create({SERVICE_NAME: service_name})
+    provider = TracerProvider(resource=resource)
+
+    if console:
+        from opentelemetry.sdk.trace.export import ConsoleSpanExporter  # noqa: PLC0415
+
+        provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+        _logger.info("OpenTelemetry console span export enabled (MCP_OTEL_CONSOLE).")
+
+    if endpoint:
+        try:
+            use_http = endpoint.startswith(("http://", "https://"))
+            proto = os.environ.get("OTEL_EXPORTER_OTLP_PROTOCOL", "").lower()
+            if proto in ("http/protobuf", "http/json"):
+                use_http = True
+            if use_http:
+                from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # noqa: PLC0415
+                    OTLPSpanExporter,
+                )
+            else:
+                from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # noqa: PLC0415
+                    OTLPSpanExporter,
+                )
+
+            exporter = OTLPSpanExporter()
+            provider.add_span_processor(BatchSpanProcessor(exporter))
+            _logger.info(
+                "OpenTelemetry OTLP trace export enabled (endpoint from OTEL_EXPORTER_OTLP_*)."
+            )
+        except Exception:
+            _logger.exception("Failed to configure OTLP trace exporter; traces may be incomplete.")
+
+    trace.set_tracer_provider(provider)
+
+
+def instrument_httpx_outbound() -> None:
+    """Patch httpx so all AsyncClient/Client requests emit dependency spans."""
+    global _HTTPX_INSTRUMENTED  # noqa: PLW0603
+    if _HTTPX_INSTRUMENTED:
+        return
+    try:
+        from opentelemetry.instrumentation.httpx import (  # noqa: PLC0415
+            HTTPXClientInstrumentor,
+        )
+
+        HTTPXClientInstrumentor().instrument(
+            request_hook=_httpx_request_hook,
+            response_hook=_httpx_response_hook,
+        )
+        _HTTPX_INSTRUMENTED = True
+        _logger.info("HTTPX OpenTelemetry instrumentation enabled.")
+    except ImportError:
+        _logger.warning("opentelemetry-instrumentation-httpx not installed.")

src/data360/providers.py

@@ -0,0 +1,1512 @@
+"""Providers for Data360 codelist and reference area data."""
+
+import asyncio
+import json
+import logging
+import os
+import random
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from data360.config import get_data360_settings
+from data360.http_client import get_shared_httpx_client
+
+data360_config = get_data360_settings()
+
+_logger = logging.getLogger(__name__)
+
+
+class DatabaseManager:
+    """Manages the list of databases dynamically fetched from the Data360 API.
+
+    On startup, loads a complete JSON fallback so the mapping is never empty.
+    All subsequent live refreshes happen in a background asyncio task, ensuring
+    that get_mapping() is always a sub-millisecond in-memory dict lookup with
+    no I/O or network cost on the hot path.
+    """
+
+    def __init__(self, ttl_seconds: float = 86400.0):
+        self._cache: dict[str, str] = {}
+        self._last_fetched: float = 0.0
+        self._ttl = ttl_seconds
+        self._bg_task: asyncio.Task | None = None
+        self._load_fallback()
+
+    def _load_fallback(self):
+        """Load the bundled databases.json at startup to guarantee a non-empty cache."""
+        fallback_path = Path(__file__).parent / "databases.json"
+        try:
+            with open(fallback_path, encoding="utf-8") as f:
+                self._cache = json.load(f)
+            _logger.info("Loaded %d databases from fallback JSON.", len(self._cache))
+        except Exception as e:
+            _logger.error("Failed to load fallback database mapping: %s", e)
+            self._cache = {}
+
+    # ------------------------------------------------------------------
+    # Public API — always a pure in-memory read, never blocks on network
+    # ------------------------------------------------------------------
+
+    async def get_mapping(self) -> dict[str, str]:
+        """Return the cached database_id→name mapping.
+
+        Always returns immediately from in-memory cache. A background task
+        is responsible for keeping the cache fresh via periodic API fetches.
+        """
+        self._ensure_background_sync()
+        return self._cache
+
+    def resolve_database_ids(self, query: str | None, strict: bool = False) -> list[str]:
+        """Resolve database search terms (semicolon separated) to database IDs from the cache.
+
+        Matches by exact ID, exact acronym suffix, exact name, or substring (if not strict).
+        Raises ValueError if any term cannot be resolved.
+        """
+        if not query:
+            return []
+        tokens = [t.strip() for t in query.split(';') if t.strip()]
+        resolved_ids = []
+        for token in tokens:
+            resolved = self._resolve_single_database_id(token, strict=strict)
+            if resolved:
+                if resolved not in resolved_ids:
+                    resolved_ids.append(resolved)
+            else:
+                raise ValueError(f"Database '{token}' could not be resolved.")
+        return resolved_ids
+
+    def _resolve_single_database_id(self, query: str, strict: bool = False) -> str | None:
+        query_lower = query.lower().strip()
+
+        # 1. Exact match on database ID (key)
+        for db_id in self._cache:
+            if query_lower == db_id.lower():
+                return db_id
+
+        # 2. Exact match on database ID acronym suffix (e.g. "wdi" matches "wb_wdi")
+        for db_id in self._cache:
+            parts = db_id.split('_')
+            if len(parts) > 1 and query_lower == parts[-1].lower():
+                return db_id
+
+        # 3. Exact match on database name (value)
+        for db_id, name in self._cache.items():
+            if query_lower == name.lower():
+                return db_id
+
+        if not strict:
+            # 4. Substring match on database ID
+            for db_id in self._cache:
+                if query_lower in db_id.lower():
+                    return db_id
+
+            # 5. Substring match on database name
+            for db_id, name in self._cache.items():
+                if query_lower in name.lower():
+                    return db_id
+
+            # 6. Fuzzy prefix/character match on ID and name as fallback
+            best_match = None
+            best_score = 0.70
+            for db_id, name in self._cache.items():
+                score_id = self._calculate_similarity(query_lower, db_id.lower())
+                score_name = self._calculate_similarity(query_lower, name.lower())
+                max_score = max(score_id, score_name)
+                if max_score > best_score:
+                    best_score = max_score
+                    best_match = db_id
+            if best_match:
+                return best_match
+
+        return None
+
+    def _calculate_similarity(self, s1: str, s2: str) -> float:
+        """Calculate similarity ratio between two strings."""
+        if not s1 or not s2:
+            return 0.0
+
+        if len(s1) <= 3:
+            if s1 in s2 or s2.startswith(s1):
+                return 0.8
+            return 0.0
+
+        len1, len2 = len(s1), len(s2)
+        if abs(len1 - len2) > max(len1, len2) * 0.5:
+            return 0.0
+
+        s1_chars = set(s1)
+        s2_chars = set(s2)
+        common = len(s1_chars & s2_chars)
+        total = len(s1_chars | s2_chars)
+        char_similarity = common / total if total > 0 else 0
+
+        prefix_len = 0
+        for c1, c2 in zip(s1, s2):
+            if c1 == c2:
+                prefix_len += 1
+            else:
+                break
+        prefix_ratio = prefix_len / min(len1, len2)
+
+        return (char_similarity * 0.4) + (prefix_ratio * 0.6)
+
+    def resolve_database_id(self, query: str | None) -> str | None:
+        """Resolve a database search term to a single database ID from the cache.
+
+        Deprecated: use resolve_database_ids instead.
+        """
+        try:
+            ids = self.resolve_database_ids(query)
+            return ids[0] if ids else None
+        except ValueError:
+            return None
+
+    # ------------------------------------------------------------------
+    # Background sync machinery
+    # ------------------------------------------------------------------
+
+    def _ensure_background_sync(self) -> None:
+        """Spawn the background refresh loop if it is not already running."""
+        if os.environ.get("PYTEST_RUNNING"):
+            return
+        if self._bg_task is None or self._bg_task.done():
+            self._bg_task = asyncio.create_task(self._background_sync_loop())
+
+    async def _background_sync_loop(self) -> None:
+        """Run forever, refreshing the cache from the API when the TTL expires."""
+        while True:
+            elapsed = time.monotonic() - self._last_fetched
+            if elapsed >= self._ttl:
+                try:
+                    mapping = await self._fetch_all()
+                    if mapping:
+                        self._cache = mapping
+                        _logger.info(
+                            "Background refresh: updated %d databases.", len(mapping)
+                        )
+                except Exception as e:
+                    _logger.error("Background database fetch failed: %s", e)
+                    # Keep existing cache; retry after the next full TTL cycle.
+                finally:
+                    self._last_fetched = time.monotonic()
+
+            sleep_for = max(0.0, self._ttl - (time.monotonic() - self._last_fetched))
+            await asyncio.sleep(sleep_for)
+
+    async def _fetch_all(self) -> dict[str, str]:
+        """Fetch all datasets from the search endpoint using pagination."""
+        url = data360_config.search_url or f"{data360_config.api_url}/searchv2"
+        mapping: dict[str, str] = {}
+        skip = 0
+        limit = 50
+
+        client = get_shared_httpx_client()
+        while True:
+            items = None
+            last_error = None
+            for attempt in range(3):
+                try:
+                    response = await client.post(
+                        url,
+                        headers={
+                            "accept": "*/*",
+                            "Content-Type": "application/json",
+                        },
+                        json={
+                            "filter": "type eq 'dataset' and (is_active ne false or is_active eq null)",
+                            "orderby": "series_description/name",
+                            "select": "series_description/database_id, series_description/name",
+                            "skip": skip,
+                            "top": limit,
+                        },
+                    )
+                    response.raise_for_status()
+                    data = response.json()
+                    items = data.get("value", [])
+                    break  # Success
+                except Exception as e:
+                    last_error = e
+                    _logger.warning(
+                        "Fetch attempt %d failed for skip=%d: %s",
+                        attempt + 1,
+                        skip,
+                        e,
+                    )
+                    if attempt < 2:
+                        await asyncio.sleep(2**attempt)  # Backoff: 1s, 2s
+
+            if items is None:
+                # All attempts failed
+                raise (
+                    last_error
+                    if last_error
+                    else Exception("Unknown error during fetch")
+                )
+
+            if not items:
+                break
+
+            for x in items:
+                sd = x.get("series_description", {})
+                db_id = sd.get("database_id")
+                db_name = sd.get("name")
+                if db_id and db_name and db_id not in mapping:
+                    mapping[db_id] = db_name
+
+            skip += limit
+
+        return mapping
+
+
+# Global instance
+_database_manager: DatabaseManager | None = None
+
+
+def get_database_manager() -> DatabaseManager:
+    """Get the global DatabaseManager instance."""
+    global _database_manager
+    if _database_manager is None:
+        _database_manager = DatabaseManager()
+    return _database_manager
+
+
+async def get_database_mapping() -> dict[str, str]:
+    """Get mapping of database IDs to their actual names (e.g., {'WB_GS': 'Gender Statistics'})."""
+    return await get_database_manager().get_mapping()
+
+
+# ---------------------------------------------------------------------------
+# Natural-language aliases for group codes.
+#
+# This map is intentionally minimal: it contains ONLY phrases where the
+# existing fuzzy/substring search in CodelistManager._search_global would
+# genuinely fail to return the correct code. The LLM and the fuzzy layer
+# already handle most natural-language variations (e.g. "South Asia",
+# "low income countries", "sub-saharan africa") without help from this map.
+#
+# Entries kept here fall into four categories:
+#   1. "and" vs "&" variants — substring check fails because the official
+#      codelist uses "&" but users type "and".
+#   2. Abbreviations not present in the official name (e.g. "mena").
+#   3. Common shorthands whose words don't appear in the official name
+#      (e.g. "fragile states" vs "Fragile and conflict affected situations").
+#   4. One semantic synonym where the variant word is absent from the
+#      official name ("lower income" vs "Low income").
+#
+# All values are FMR group codes that must exist in ref_area_groups.json.
+# Enforced by TestDataIntegrity.test_all_alias_values_exist_in_shipped_data.
+#
+# Future path if coverage proves insufficient: build-time sentence-transformer
+# embeddings over all group names, cosine-similarity fallback after alias miss.
+# ---------------------------------------------------------------------------
+_GROUP_ALIASES: dict[str, str] = {
+    # Category 1: "and" vs "&" — fuzzy fails because "&" != "and"
+    "east asia and pacific": "EAS",  # official: "East Asia & Pacific"
+    "europe and central asia": "ECS",  # official: "Europe & Central Asia"
+    "latin america and the caribbean": "LCN",  # official: "Latin America & Caribbean"
+    "middle east and north africa": "MEA",  # official: "Middle East, North Africa, Afghanistan & Pakistan"
+    "middle east & north africa": "MEA",  # same but omits "Afghanistan & Pakistan"
+    "low and middle income": "LMY",  # official: "Low & middle income"
+    # Category 2: abbreviation not in official name
+    "mena": "MEA",  # common abbreviation for the region
+    # Category 3: shorthands whose words don't appear in the official name
+    "fragile states": "FCS",  # official: "Fragile and conflict affected situations"
+    "small island states": "SST",  # official: "Small states"
+    "eastern africa": "AFE",  # official: "Africa Eastern and Southern"
+    "western africa": "AFW",  # official: "Africa Western and Central"
+    # Category 4: semantic synonym — "lower" absent from "Low income"
+    "lower income": "LIC",
+}
+
+
+# FMR endpoint templates (version segment is optional; omitting returns latest).
+_FMR_HIERARCHY_URL = (
+    "https://fmr.worldbank.org/FMR/sdmx/v2/structure/hierarchy/WB/H_REF_AREA_GROUPS/{version}"
+    "?format=sdmx-json"
+)
+_FMR_CODELIST_URL = (
+    "https://fmr.worldbank.org/FMR/sdmx/v2/structure/codelist/WB/CL_REF_GROUPINGS/{version}"
+    "?format=sdmx-json"
+)
+# Group types whose entries are all leaf countries — not expandable groups.
+_LEAF_ONLY_TYPES: frozenset[str] = frozenset({"WLD", "_T"})
+
+
+class GroupHierarchyManager:
+    """Manages REF_AREA group-to-country mappings from the FMR hierarchy.
+
+    Startup behaviour (zero-latency):
+      Loads the bundled src/data360/ref_area_groups.json immediately on first
+      access so the tool is usable without any network I/O on the hot path.
+      Re-generate that file with::
+
+          uv run python scripts/build_ref_area_groups.py
+
+    Background sync (TTL = 7 days):
+      The first public method call from within an async context spawns a
+      long-lived asyncio task that wakes once every 7 days and re-fetches
+      the FMR hierarchy and codelist endpoints.  On a successful fetch the
+      in-memory state is atomically replaced.
+
+      FMR (https://fmr.worldbank.org) is a VPN-restricted resource.  A
+      failed fetch is logged at WARNING level and the existing in-memory
+      state is kept intact.  The loop then sleeps another full TTL cycle
+      before trying again — non-VPN deployments therefore produce at most
+      one warning per week and never retry aggressively.
+
+    Covers all 147 group codes across 6 group types:
+      REGION, INCOME, LENDING, OTHER, REGION_UN, CONTINENT.
+    """
+
+    # 7-day TTL: income group compositions change at most once a year (July 1).
+    _TTL: float = 7 * 24 * 3600.0
+
+    _DATA_FILE = Path(__file__).parent / "ref_area_groups.json"
+
+    def __init__(self, include_types: set[str] | None = None) -> None:
+        """Initialize and load the bundled JSON fallback synchronously.
+
+        Args:
+            include_types: If provided, only expose groups of these types.
+                Defaults to all types. Common subset:
+                {"REGION", "INCOME", "LENDING", "OTHER"}
+        """
+        self._groups: dict[str, dict[str, Any]] = {}
+        self._all_countries: set[str] = set()
+        self._meta: dict[str, Any] = {}
+        self._include_types = include_types
+        self._loaded = False
+        self._initial_fetch_succeeded = False
+        self._last_fetched: float = 0.0
+        self._bg_task: asyncio.Task | None = None  # type: ignore[type-arg]
+
+    # ------------------------------------------------------------------
+    # SDMX parsing helpers (static — also imported by build_ref_area_groups.py)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def parse_name_map(codelist_data: dict) -> dict[str, str]:
+        """Build a {code: name} map from a CL_REF_GROUPINGS SDMX-JSON payload."""
+        codes = codelist_data["data"]["codelists"][0]["codes"]
+        return {c["id"]: c["name"] for c in codes}
+
+    @staticmethod
+    def parse_hierarchy(
+        hierarchy_data: dict,
+        name_map: dict[str, str],
+        include_types: set[str] | None = None,
+    ) -> tuple[dict[str, dict], set[str], str]:
+        """Parse H_REF_AREA_GROUPS SDMX-JSON into (groups, all_countries, version).
+
+        groups format:
+            {
+                "SAS": {"name": "South Asia", "type": "REGION", "countries": [...]},
+                ...
+            }
+        all_countries: set of every individual country code that appears in at
+            least one group.
+        version: hierarchy version string from the SDMX payload (e.g. "38.0").
+        """
+        hcl = hierarchy_data["data"]["hierarchicalCodelists"][0]
+        version = hcl["version"]
+        top_level = hcl["hierarchies"][0]["hierarchicalCodes"]
+
+        groups: dict[str, dict] = {}
+        all_countries: set[str] = set()
+
+        for type_node in top_level:
+            group_type = type_node["id"]
+            if group_type in _LEAF_ONLY_TYPES:
+                continue
+            if include_types and group_type not in include_types:
+                continue
+
+            for group_node in type_node.get("hierarchicalCodes", []):
+                group_id = group_node["id"]
+                country_nodes = group_node.get("hierarchicalCodes", [])
+                if not country_nodes:
+                    continue
+
+                countries = sorted(c["id"] for c in country_nodes)
+                all_countries.update(countries)
+
+                # Strip UTF-8 mojibake from some FMR source names.
+                # (e.g. 9WN: "Western Asia\u00c2\u00a0 and ..." — \u00c2\u00a0 is
+                # a UTF-8 non-breaking space decoded as Latin-1.)
+                raw_name = name_map.get(group_id, group_id)
+                clean_name = " ".join(raw_name.replace("\u00c2\u00a0", " ").split())
+
+                groups[group_id] = {
+                    "name": clean_name,
+                    "type": group_type,
+                    "countries": countries,
+                }
+
+        return groups, all_countries, version
+
+    # ------------------------------------------------------------------
+    # Bundled-JSON loader (synchronous, called once at __init__)
+    # ------------------------------------------------------------------
+
+    def _load(self) -> None:
+        """Load the bundled ref_area_groups.json. Called once at __init__."""
+        if self._loaded:
+            return
+        try:
+            with open(self._DATA_FILE, encoding="utf-8") as f:
+                data = json.load(f)
+            self._apply(data)
+            _logger.info(
+                "GroupHierarchyManager: loaded %d groups (%d countries) from bundled file. Source: %s",
+                len(self._groups),
+                len(self._all_countries),
+                self._meta.get("source", "unknown"),
+            )
+        except FileNotFoundError:
+            _logger.error(
+                "GroupHierarchyManager: bundled data file not found at %s. "
+                "Run scripts/build_ref_area_groups.py to generate it.",
+                self._DATA_FILE,
+            )
+        except Exception as e:
+            _logger.error("GroupHierarchyManager: failed to load bundled data: %s", e)
+        finally:
+            # Mark as loaded regardless so _ensure_loaded does not retry
+            # the synchronous disk read in a loop.
+            self._loaded = True
+
+    def _apply(self, data: dict) -> None:
+        """Atomically swap the in-memory state from a parsed data dict."""
+        raw_groups: dict[str, dict] = data.get("groups", {})
+        if self._include_types:
+            raw_groups = {
+                k: v
+                for k, v in raw_groups.items()
+                if v.get("type") in self._include_types
+            }
+        self._groups = raw_groups
+        self._all_countries = set(data.get("all_countries", []))
+        self._meta = data.get("_meta", {})
+
+    def _ensure_loaded(self) -> None:
+        if not self._loaded:
+            self._load()
+
+    # ------------------------------------------------------------------
+    # Background sync machinery (mirrors DatabaseManager)
+    # ------------------------------------------------------------------
+
+    def _ensure_background_sync(self) -> None:
+        """Spawn the background refresh loop if it is not already running.
+
+        No-op when called outside a running event loop (e.g. in sync test code
+        or during module import). The bundled JSON is always pre-loaded, so
+        the background task is only an update mechanism, not a prerequisite.
+        """
+        if os.environ.get("PYTEST_RUNNING"):
+            return
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            # No running event loop — skip task creation.
+            return
+        if self._bg_task is None or self._bg_task.done():
+            self._bg_task = asyncio.create_task(self._background_sync_loop())
+
+    async def _background_sync_loop(self) -> None:
+        """Run forever, waking every TTL seconds to refresh from FMR.
+
+        TTL policy:
+          - Success: in-memory state is replaced; next wake is _TTL seconds later.
+          - Failure: existing state is kept; _last_fetched is still advanced by
+            _TTL so the next wake is also _TTL seconds later.  This means a
+            non-VPN deployment gets at most one WARNING log per week rather than
+            retrying aggressively.
+
+        The loop is safe to cancel: cancellation propagates through
+        asyncio.sleep and exits cleanly.
+        """
+        backoff = 5.0
+        max_backoff = 900.0  # 15 minutes
+        while True:
+            if self._initial_fetch_succeeded:
+                elapsed = time.monotonic() - self._last_fetched
+                sleep_for = max(0.0, self._TTL - elapsed)
+                if sleep_for > 0:
+                    await asyncio.sleep(sleep_for)
+                    continue
+
+            try:
+                groups, all_countries, version = await self._fetch_fmr_data()
+                # Build a minimal data dict compatible with _apply.
+                data = {
+                    "_meta": {
+                        "source": f"FMR H_REF_AREA_GROUPS v{version} + CL_REF_GROUPINGS (live)",
+                        "hierarchy_version": version,
+                    },
+                    "groups": groups,
+                    "all_countries": sorted(all_countries),
+                }
+                self._apply(data)
+                self._initial_fetch_succeeded = True
+                self._last_fetched = time.monotonic()
+                _logger.info(
+                    "GroupHierarchyManager: background refresh completed — "
+                    "%d groups (%d countries), hierarchy v%s.",
+                    len(self._groups),
+                    len(self._all_countries),
+                    version,
+                )
+                backoff = 5.0
+                sleep_for = self._TTL
+            except Exception as e:
+                if not self._initial_fetch_succeeded:
+                    sleep_for = backoff
+                    backoff = min(backoff * 2 + random.uniform(0.1, 1.0), max_backoff)
+                    _logger.warning(
+                        "GroupHierarchyManager: initial background FMR fetch failed (%s). "
+                        "Retrying in %.1f seconds.",
+                        e,
+                        sleep_for,
+                    )
+                else:
+                    sleep_for = self._TTL
+                    self._last_fetched = time.monotonic()
+                    _logger.warning(
+                        "GroupHierarchyManager: background FMR fetch failed (%s). "
+                        "Next attempt in %.0f days.",
+                        e,
+                        self._TTL / 86400,
+                    )
+
+            await asyncio.sleep(sleep_for)
+
+    async def _fetch_fmr_data(
+        self,
+        hierarchy_version: str = "",
+        codelist_version: str = "",
+    ) -> tuple[dict[str, dict], set[str], str]:
+        """Fetch and parse the FMR hierarchy + codelist endpoints.
+
+        Args:
+            hierarchy_version: Specific version string (e.g. "38.0").  If empty,
+                the FMR API returns the latest version.
+            codelist_version: Specific codelist version (e.g. "2.0").  If empty,
+                the FMR API returns the latest version.
+
+        Returns:
+            Tuple of (groups, all_countries, version) — same shape as
+            parse_hierarchy().
+        """
+        hierarchy_url = _FMR_HIERARCHY_URL.format(version=hierarchy_version)
+        codelist_url = _FMR_CODELIST_URL.format(version=codelist_version)
+
+        client = get_shared_httpx_client()
+        h_resp, cl_resp = await asyncio.gather(
+            client.get(hierarchy_url, headers={"Accept": "application/json"}),
+            client.get(codelist_url, headers={"Accept": "application/json"}),
+        )
+        h_resp.raise_for_status()
+        cl_resp.raise_for_status()
+        hierarchy_data = h_resp.json()
+        codelist_data = cl_resp.json()
+
+        name_map = self.parse_name_map(codelist_data)
+        return self.parse_hierarchy(hierarchy_data, name_map, self._include_types)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def is_group(self, code: str) -> bool:
+        """Return True if the code is a known country group (not a leaf country)."""
+        self._ensure_loaded()
+        self._ensure_background_sync()
+        return code.upper() in self._groups
+
+    def is_country(self, code: str) -> bool:
+        """Return True if the code is an individual country in the hierarchy."""
+        self._ensure_loaded()
+        return code.upper() in self._all_countries and not self.is_group(code.upper())
+
+    def list_rankable_country_codes(self) -> list[str]:
+        """Return sorted leaf economy codes (FMR member countries, excluding group aggregates).
+
+        Used for ranking metadata and for ``member_economies_only`` filtering; the Data API
+        may still return additional aggregate codes when ``REF_AREA`` is unpinned—those
+        should be dropped with :meth:`is_country` per row.
+        """
+        self._ensure_loaded()
+        self._ensure_background_sync()
+        return sorted(c for c in self._all_countries if self.is_country(c))
+
+    def get_group_info(self, code: str) -> dict[str, Any] | None:
+        """Return {name, type, countries} for a group code, or None if unknown."""
+        self._ensure_loaded()
+        self._ensure_background_sync()
+        return self._groups.get(code.upper())
+
+    def get_group_type(self, code: str) -> str | None:
+        """Return the group type string (REGION, INCOME, ...) or None."""
+        info = self.get_group_info(code)
+        return info["type"] if info else None
+
+    def expand_group(self, code: str) -> list[str]:
+        """Return sorted list of country codes in a group, or [] if unknown."""
+        info = self.get_group_info(code)
+        return list(info["countries"]) if info else []
+
+    def get_meta(self) -> dict[str, Any]:
+        """Return metadata about the loaded hierarchy (version, built_at, etc.)."""
+        self._ensure_loaded()
+        return self._meta
+
+    def search_groups(self, query: str, limit: int = 10) -> list[dict[str, Any]]:
+        """Search group names by substring. Returns [{id, name, type, count}]."""
+        self._ensure_loaded()
+        q = query.lower().strip()
+        results = []
+        for gid, info in self._groups.items():
+            if q in info["name"].lower() or q == gid.lower():
+                results.append(
+                    {
+                        "id": gid,
+                        "name": info["name"],
+                        "type": info["type"],
+                        "count": len(info["countries"]),
+                    }
+                )
+        results.sort(key=lambda x: x["name"])
+        return results[:limit]
+
+
+# Global instance
+_group_hierarchy_manager: GroupHierarchyManager | None = None
+
+
+def get_group_hierarchy_manager() -> GroupHierarchyManager:
+    """Get the global GroupHierarchyManager instance."""
+    global _group_hierarchy_manager
+    if _group_hierarchy_manager is None:
+        _group_hierarchy_manager = GroupHierarchyManager()
+    return _group_hierarchy_manager
+
+
+def _make_group_note(group_code: str, info: dict) -> str:
+    """Build the standard guidance note for a REF_AREA group result."""
+    return (
+        f"This is a {info['type'].lower()} group with "
+        f"{len(info['countries'])} member countries. "
+        f"Use data360_expand_country_group('{group_code}') "
+        "to get individual country codes."
+    )
+
+
+_UNIT_MEASURE_FALLBACKS = {
+    "ZS": "Percent",
+    "PS": "Persons",
+    "USD": "US Dollars",
+    "LCU": "Local Currency Unit",
+    "DY": "Days",
+    "YR": "Years",
+    "MR": "Meters",
+    "KG": "Kilograms",
+    "TN": "Tonnes",
+}
+
+
+class CodelistManager:
+    """Unified manager for all Data360 codelists.
+
+    Primary data source (lazy startup fetch, then background refresh):
+      On first use, it fetches all dimension codelists from the extdataportal
+      metadata API in a single HTTP call and populates ``_extdataportal``.
+      Covers COMP_BREAKDOWN (5 000+ codes), UNIT_MEASURE (769 codes),
+      AGE (173 codes), URBANISATION (16 codes), SEX (7 codes), FREQ (34 codes),
+      and REF_AREA (532 codes).
+
+      After the initial fetch a background task wakes every ``_TTL`` seconds
+      (default 7 days) and atomically replaces the in-memory mapping so the
+      server always has fresh labels without restarting.
+
+    Graceful degradation:
+      If the network is unavailable at startup ``_extdataportal`` stays empty
+      and ``get_label()`` / ``get_dimension_labels()`` return the raw code
+      unchanged.  The background loop retries after the next TTL cycle.
+
+    Legacy paths (kept for backward compatibility):
+      ``find_value()`` / ``get_codelist_mapping()`` still work for REF_AREA and
+      UNIT_MEASURE via the old per-type API fetch (used by the
+      ``find_codelist_value`` MCP tool).
+      ``STATIC_MAPPINGS`` (name→code) is kept for the ``find_value()`` search
+      path on SEX, AGE, URBANISATION, FREQ.
+
+    New preferred path:
+      ``get_label(dimension, code)`` — O(1) code→name lookup.
+      ``get_dimension_labels(dimension)`` — full {code: name} dict.
+    """
+
+    # 7-day TTL: codelists rarely change; this mirrors GroupHierarchyManager.
+    _TTL: float = 7 * 24 * 3600.0
+
+    # COMP_BREAKDOWN_1/2/3 are identical on the API — stored once under this key.
+    _COMP_BREAKDOWN_DIMS: frozenset[str] = frozenset(
+        {"COMP_BREAKDOWN_1", "COMP_BREAKDOWN_2", "COMP_BREAKDOWN_3"}
+    )
+    _COMP_BREAKDOWN_KEY = "COMP_BREAKDOWN"
+
+    # Prefix stripped from COMP_BREAKDOWN labels for chart readability.
+    _COMP_BREAKDOWN_STRIP_PREFIX = "Metric: "
+
+    # Codelists available via /codelist?type=X API
+    GLOBAL_CODELISTS = ["REF_AREA", "UNIT_MEASURE"]
+
+    # Static mappings for codelists without global API endpoints
+    # These are based on actual values from disaggregation responses
+    # Reference: WB_SSGD_UNEMPLOYMENT_RATE_disaggregation.json
+    STATIC_MAPPINGS: dict[str, dict[str, str]] = {
+        "FREQ": {
+            # Common frequency codes found in Data360
+            "annual": "A",
+            "yearly": "A",
+            "year": "A",
+            "monthly": "M",
+            "month": "M",
+            "quarterly": "Q",
+            "quarter": "Q",
+            "other": "_O",
+            "irregular": "_O",
+        },
+        "SEX": {
+            # Sex codes from actual disaggregation data
+            "female": "F",
+            "women": "F",
+            "woman": "F",
+            "girls": "F",
+            "girl": "F",
+            "male": "M",
+            "men": "M",
+            "man": "M",
+            "boys": "M",
+            "boy": "M",
+            "total": "_T",
+            "all": "_T",
+            "both": "_T",
+            "overall": "_T",
+        },
+        "AGE": {
+            # Age group codes from actual disaggregation data
+            "youth": "Y15T24",
+            "young": "Y15T24",
+            "15-24": "Y15T24",
+            "15 to 24": "Y15T24",
+            "young adults": "Y15T29",
+            "15-29": "Y15T29",
+            "adults": "Y30T59",
+            "30-59": "Y30T59",
+            "25+": "Y_GE25",
+            "25 and over": "Y_GE25",
+            "adult": "Y_GE25",
+            "elderly": "Y_GE60",
+            "60+": "Y_GE60",
+            "60 and over": "Y_GE60",
+            "seniors": "Y_GE60",
+            "total": "_T",
+            "all ages": "_T",
+        },
+        "URBANISATION": {
+            # Urbanisation codes from actual disaggregation data
+            "urban": "URB",
+            "city": "URB",
+            "cities": "URB",
+            "rural": "RUR",
+            "countryside": "RUR",
+            "village": "RUR",
+            "total": "_T",
+            "all": "_T",
+        },
+    }
+
+    def __init__(self) -> None:
+        """Initialise the CodelistManager.
+
+        ``_extdataportal`` starts empty.  It is populated lazily on first use.
+        """
+        self._cache: dict[str, list[dict[str, Any]]] = {}
+        self._loaded: set[str] = set()
+        # Runtime-fetched extdataportal data: {dimension → {code → name}}.
+        # Populated lazily; stays empty (graceful fallback) if offline.
+        self._extdataportal: dict[str, dict[str, str]] = {}
+        self._initial_fetch_succeeded = False
+        self._last_fetched: float = 0.0
+        self._bg_task: asyncio.Task | None = None  # type: ignore[type-arg]
+
+    # ------------------------------------------------------------------
+    # Extdataportal fetch helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_extdataportal_response(raw: dict) -> dict[str, dict[str, str]]:
+        """Parse the extdataportal JSON response into {dimension: {code: name}}.
+
+        Deduplicates COMP_BREAKDOWN_1/2/3 into a single COMP_BREAKDOWN key and
+        strips the ``'Metric: '`` prefix from COMP_BREAKDOWN labels.
+        """
+        built: dict[str, dict[str, str]] = {}
+        strip = CodelistManager._COMP_BREAKDOWN_STRIP_PREFIX
+        cb_key = CodelistManager._COMP_BREAKDOWN_KEY
+        cb_dims = CodelistManager._COMP_BREAKDOWN_DIMS
+
+        for dim, items in raw.items():
+            if dim == "_meta" or not isinstance(items, list):
+                continue
+            # Normalise dimension key
+            norm = dim.upper()
+            target_key = cb_key if norm in cb_dims else norm
+            # Build {id: name} — strip 'Metric: ' prefix from COMP_BREAKDOWN
+            mapping: dict[str, str] = {}
+            for item in items:
+                if not isinstance(item, dict) or "id" not in item:
+                    continue
+                name = item.get("name", item["id"])
+                if target_key == cb_key and name.startswith(strip):
+                    name = name[len(strip):]
+                mapping[item["id"]] = name
+            # Merge into existing entry (COMP_BREAKDOWN_1/2/3 all write to cb_key)
+            if target_key in built:
+                built[target_key].update(mapping)
+            else:
+                built[target_key] = mapping
+
+        return built
+
+    async def _fetch_extdataportal(self) -> dict[str, dict[str, str]]:
+        """Fetch all dimension codelists from the extdataportal metadata API.
+
+        Returns:
+            Parsed {dimension: {code: name}} mapping.
+
+        Raises:
+            httpx.HTTPStatusError / httpx.RequestError on network failure.
+        """
+        url = data360_config.codelist_api_base_url
+        client = get_shared_httpx_client()
+        response = await client.get(url, timeout=30.0)
+        response.raise_for_status()
+        raw: dict = response.json()
+        return self._parse_extdataportal_response(raw)
+
+    def _apply_extdataportal(self, mapping: dict[str, dict[str, str]]) -> None:
+        """Atomically replace the in-memory extdataportal mapping."""
+        self._extdataportal = mapping
+        _logger.info(
+            "CodelistManager: extdataportal codelists loaded — %d dimensions, "
+            "COMP_BREAKDOWN=%d codes.",
+            len(mapping),
+            len(mapping.get(self._COMP_BREAKDOWN_KEY, {})),
+        )
+
+    # ------------------------------------------------------------------
+    # Lazy loader (same pattern as _ensure_loaded for REF_AREA)
+    # ------------------------------------------------------------------
+
+    async def _ensure_extdataportal_loaded(self) -> None:
+        """Fetch extdataportal codelists on first use (lazy load).
+
+        Mirrors the pattern of ``_ensure_loaded()`` for REF_AREA: called at the
+        top of any async path that reads ``_extdataportal`` (e.g.
+        ``_map_dimension_codes``).  Subsequent calls are instant no-ops once the
+        data is populated.  Starts the background refresh loop on first call.
+        """
+        if not self._extdataportal:
+            try:
+                mapping = await self._fetch_extdataportal()
+                self._apply_extdataportal(mapping)
+                self._initial_fetch_succeeded = True
+                self._last_fetched = time.monotonic()
+            except Exception as exc:
+                _logger.warning(
+                    "CodelistManager: extdataportal fetch failed (%s). "
+                    "Dimension codes will display as raw values until the "
+                    "next retry.",
+                    exc,
+                )
+        self._ensure_background_refresh()
+
+    # ------------------------------------------------------------------
+    # Background refresh (mirrors GroupHierarchyManager pattern)
+    # ------------------------------------------------------------------
+
+    def _ensure_background_refresh(self) -> None:
+        """Spawn the background refresh task if not already running.
+
+        No-op outside a running event loop (e.g. in sync tests).
+        """
+        if os.environ.get("PYTEST_RUNNING"):
+            return
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if self._bg_task is None or self._bg_task.done():
+            self._bg_task = asyncio.create_task(self._background_refresh_loop())
+
+    async def _background_refresh_loop(self) -> None:
+        """Wake every TTL seconds and refresh from extdataportal.
+
+        On success the in-memory mapping is atomically replaced.
+        On failure the existing mapping is kept and a WARNING is logged;
+        the loop sleeps another full TTL before retrying.
+        """
+        backoff = 5.0
+        max_backoff = 900.0  # 15 minutes
+        while True:
+            if self._initial_fetch_succeeded:
+                elapsed = time.monotonic() - self._last_fetched
+                sleep_for = max(0.0, self._TTL - elapsed)
+                if sleep_for > 0:
+                    await asyncio.sleep(sleep_for)
+                    continue
+
+            try:
+                mapping = await self._fetch_extdataportal()
+                self._apply_extdataportal(mapping)
+                self._initial_fetch_succeeded = True
+                self._last_fetched = time.monotonic()
+                _logger.info(
+                    "CodelistManager: background refresh completed — "
+                    "%d dimensions, COMP_BREAKDOWN=%d codes.",
+                    len(mapping),
+                    len(mapping.get(self._COMP_BREAKDOWN_KEY, {})),
+                )
+                backoff = 5.0
+                sleep_for = self._TTL
+            except Exception as exc:
+                if not self._initial_fetch_succeeded:
+                    sleep_for = backoff
+                    backoff = min(backoff * 2 + random.uniform(0.1, 1.0), max_backoff)
+                    _logger.warning(
+                        "CodelistManager: initial background refresh failed (%s). "
+                        "Retrying in %.1f seconds.",
+                        exc,
+                        sleep_for,
+                    )
+                else:
+                    sleep_for = self._TTL
+                    self._last_fetched = time.monotonic()
+                    _logger.warning(
+                        "CodelistManager: background refresh failed (%s). "
+                        "Next attempt in %.0f days.",
+                        exc,
+                        self._TTL / 86400,
+                    )
+
+            await asyncio.sleep(sleep_for)
+
+    # ------------------------------------------------------------------
+    # Public label-lookup API (synchronous — reads pre-fetched dict)
+    # ------------------------------------------------------------------
+
+    def _resolve_extdataportal_key(self, dimension: str) -> str:
+        """Normalise dimension name for extdataportal lookup.
+
+        Maps COMP_BREAKDOWN_1/2/3 → COMP_BREAKDOWN; everything else is
+        upper-cased and passed through unchanged.
+        """
+        upper = dimension.upper()
+        if upper in self._COMP_BREAKDOWN_DIMS:
+            return self._COMP_BREAKDOWN_KEY
+        return upper
+
+    def get_label(self, dimension: str, code: str) -> str:
+        """Return the human-readable label for a dimension code.
+
+        Reads from the in-memory ``_extdataportal`` dict populated by
+        extdataportal mapping (lazy-loaded).  Returns the raw ``code`` unchanged if the
+        dimension or code is not found (graceful degradation).
+
+        Args:
+            dimension: Dimension name, e.g. ``"COMP_BREAKDOWN_1"``, ``"SEX"``.
+            code: The raw code value, e.g. ``"WGI_EST"``, ``"F"``.
+
+        Returns:
+            Human-readable label or the original ``code`` if not found.
+        """
+        key = self._resolve_extdataportal_key(dimension)
+        if key == "UNIT_MEASURE" and code in _UNIT_MEASURE_FALLBACKS:
+            return _UNIT_MEASURE_FALLBACKS[code]
+        return self._extdataportal.get(key, {}).get(code, code)
+
+    def get_dimension_labels(self, dimension: str) -> dict[str, str]:
+        """Return a ``{code: name}`` mapping for an entire dimension.
+
+        Suitable for vectorised DataFrame replacement via ``df[col].map(lookup)``.
+        Returns an empty dict if the dimension is not found.
+
+        Args:
+            dimension: Dimension name, e.g. ``"COMP_BREAKDOWN_1"``, ``"UNIT_MEASURE"``.
+
+        Returns:
+            A copy of the code→name dict for the dimension.
+        """
+        key = self._resolve_extdataportal_key(dimension)
+        return dict(self._extdataportal.get(key, {}))
+
+    async def _ensure_loaded(self, codelist_type: str) -> None:
+        """Ensure a global codelist is loaded from extdataportal."""
+        if codelist_type in self._loaded:
+            return
+        if codelist_type in self.GLOBAL_CODELISTS:
+            await self._ensure_extdataportal_loaded()
+            ext_key = self._resolve_extdataportal_key(codelist_type)
+            if ext_key in self._extdataportal and self._extdataportal[ext_key]:
+                items = [
+                    {"Id": code, "Name": name}
+                    for code, name in self._extdataportal[ext_key].items()
+                ]
+                self._cache[codelist_type] = items
+                self._loaded.add(codelist_type)
+
+    def _normalize_query(self, query: str) -> str:
+        """Normalize query for case-insensitive and whitespace-invariant search."""
+        return query.lower().strip()
+
+    async def find_value(
+        self, codelist_type: str, query: str, limit: int = 5
+    ) -> list[dict[str, Any]]:
+        """Find values in a codelist matching the query.
+
+        Args:
+            codelist_type: Type of codelist (REF_AREA, FREQ, SEX, etc.)
+            query: Search query (e.g., "Kenya", "monthly", "female")
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matches with id, name, and score
+        """
+        codelist_type = codelist_type.upper()
+
+        # Check for multi-value query (comma-separated)
+        if "," in query:
+            parts = [p.strip() for p in query.split(",") if p.strip()]
+            all_results = []
+            seen_ids = set()
+
+            for part in parts:
+                part_lower = self._normalize_query(part)
+                # Recurse for single value
+                matches = await self.find_value(
+                    codelist_type, part, limit=1
+                )  # find top match for each
+                for m in matches:
+                    if m["id"] not in seen_ids:
+                        all_results.append(m)
+                        seen_ids.add(m["id"])
+            return all_results
+
+        # Explicitly normalize using helper
+        query_lower = self._normalize_query(query)
+
+        # Handle global codelists (API-based)
+        if codelist_type in self.GLOBAL_CODELISTS:
+            await self._ensure_loaded(codelist_type)
+            return self._search_global(codelist_type, query_lower, limit)
+
+        # Handle static codelists
+        if codelist_type in self.STATIC_MAPPINGS:
+            return self._search_static(codelist_type, query_lower, limit)
+
+        # Unknown codelist
+        _logger.warning(f"Unknown codelist type: {codelist_type}")
+        return []
+
+    def _search_global(
+        self, codelist_type: str, query_lower: str, limit: int
+    ) -> list[dict[str, Any]]:
+        """Search in a global (API-fetched) codelist.
+
+        For REF_AREA, results are enriched with group metadata (is_group,
+        group_type, member_count) sourced from the GroupHierarchyManager.
+        """
+        items = self._cache.get(codelist_type, [])
+        results: list[dict[str, Any]] = []
+
+        # Also search without spaces for cases like "Vietnam" vs "Viet Nam"
+        query_no_spaces = query_lower.replace(" ", "")
+
+        for item in items:
+            item_id = item.get("Id", "")
+            item_name = item.get("Name", "")
+            name_lower = item_name.lower()
+            name_no_spaces = name_lower.replace(" ", "")
+
+            score = 0
+
+            # Exact ID match
+            if query_lower == item_id.lower():
+                score = 100
+            # Exact name match
+            elif query_lower == name_lower:
+                score = 100
+            # Exact match ignoring spaces (Vietnam == Viet Nam)
+            elif query_no_spaces == name_no_spaces:
+                score = 100
+            # ID starts with query
+            elif item_id.lower().startswith(query_lower):
+                score = 95
+            # Name contains query exactly
+            elif query_lower in name_lower:
+                score = 90
+            # No-space match (vietnam in vietnam)
+            elif query_no_spaces in name_no_spaces:
+                score = 90
+            # Query contains name
+            elif name_lower in query_lower:
+                score = 85
+            else:
+                # Fuzzy: prefix matching
+                similarity = self._calculate_similarity(query_lower, name_lower)
+                if similarity > 0.7:
+                    score = int(similarity * 100)
+
+            if score > 0:
+                results.append(
+                    {
+                        "id": item_id,
+                        "name": item_name,
+                        "score": score,
+                    }
+                )
+
+        results.sort(key=lambda x: (-x["score"], x["name"]))
+        matches = results[:limit]
+
+        # Enrich REF_AREA results with group metadata.
+        if codelist_type == "REF_AREA":
+            ghm = get_group_hierarchy_manager()
+            for match in matches:
+                info = ghm.get_group_info(match["id"])
+                if info:
+                    match["is_group"] = True
+                    match["group_type"] = info["type"]
+                    match["member_count"] = len(info["countries"])
+                    match["note"] = _make_group_note(match["id"], info)
+                else:
+                    match["is_group"] = False
+
+        return matches
+
+    def _search_static(
+        self, codelist_type: str, query_lower: str, limit: int
+    ) -> list[dict[str, Any]]:
+        """Search in a static (hardcoded) codelist."""
+        mapping = self.STATIC_MAPPINGS.get(codelist_type, {})
+        results: list[dict[str, Any]] = []
+
+        for name, code in mapping.items():
+            name_lower = name.lower()
+            score = 0
+
+            # Exact match
+            if query_lower == name_lower:
+                score = 100
+            # Query is the code itself
+            elif query_lower == code.lower():
+                score = 100
+            # Name contains query
+            elif query_lower in name_lower:
+                score = 90
+            # Query contains name
+            elif name_lower in query_lower:
+                score = 80
+
+            if score > 0:
+                results.append(
+                    {
+                        "id": code,
+                        "name": name.capitalize(),
+                        "score": score,
+                    }
+                )
+
+        # Deduplicate by id (keep highest score)
+        seen: dict[str, dict[str, Any]] = {}
+        for r in results:
+            rid = r["id"]
+            if rid not in seen or r["score"] > seen[rid]["score"]:
+                seen[rid] = r
+
+        deduped = list(seen.values())
+        deduped.sort(key=lambda x: (-x["score"], x["name"]))
+        return deduped[:limit]
+
+    def _calculate_similarity(self, s1: str, s2: str) -> float:
+        """Calculate similarity ratio between two strings."""
+        if not s1 or not s2:
+            return 0.0
+
+        if len(s1) <= 3:
+            if s1 in s2 or s2.startswith(s1):
+                return 0.8
+            return 0.0
+
+        len1, len2 = len(s1), len(s2)
+        if abs(len1 - len2) > max(len1, len2) * 0.5:
+            return 0.0
+
+        s1_chars = set(s1)
+        s2_chars = set(s2)
+        common = len(s1_chars & s2_chars)
+        total = len(s1_chars | s2_chars)
+        char_similarity = common / total if total > 0 else 0
+
+        prefix_len = 0
+        for c1, c2 in zip(s1, s2):
+            if c1 == c2:
+                prefix_len += 1
+            else:
+                break
+        prefix_ratio = prefix_len / min(len1, len2)
+
+        return (char_similarity * 0.4) + (prefix_ratio * 0.6)
+
+    async def get_codelist_mapping(self, codelist_type: str) -> dict[str, str]:
+        """Get a dictionary mapping codes to names (e.g., {'KEN': 'Kenya'})."""
+        codelist_type = codelist_type.upper()
+
+        # Try from extdataportal first
+        try:
+            await self._ensure_extdataportal_loaded()
+            ext_key = self._resolve_extdataportal_key(codelist_type)
+            if ext_key in self._extdataportal and self._extdataportal[ext_key]:
+                return dict(self._extdataportal[ext_key])
+        except Exception:
+            _logger.debug("Failed to load from extdataportal.", exc_info=True)
+
+        # Fallback: derive global codelist from extdataportal via _ensure_loaded cache path
+        if codelist_type in self.GLOBAL_CODELISTS:
+            try:
+                await self._ensure_loaded(codelist_type)
+                items = self._cache.get(codelist_type, [])
+                return {item.get("Id", ""): item.get("Name", "") for item in items}
+            except Exception:
+                _logger.warning(
+                    "Global codelist load failed for %s.", codelist_type, exc_info=True
+                )
+
+        # Static mappings (reverse the value->code mapping to code->name)
+        if codelist_type in self.STATIC_MAPPINGS:
+            # STATIC_MAPPINGS is Name -> Code. We want Code -> Name.
+            # Names in static mapping are lower case keys, we should capitalize for display.
+            mapping = {}
+            for name, code in self.STATIC_MAPPINGS[codelist_type].items():
+                if (
+                    code not in mapping
+                ):  # First win or preferred name logic could be added
+                    mapping[code] = name.capitalize()
+            return mapping
+
+        return {}
+
+
+# Global instance
+_codelist_manager: CodelistManager | None = None
+
+
+def get_codelist_manager() -> CodelistManager:
+    """Get the global CodelistManager instance."""
+    global _codelist_manager
+    if _codelist_manager is None:
+        _codelist_manager = CodelistManager()
+    return _codelist_manager
+
+
+async def find_codelist_value(
+    codelist_type: str, query: str, limit: int = 5
+) -> list[dict[str, Any]]:
+    """Find values in a Data360 codelist by name (e.g. country or dimension labels).
+
+    Use when you need to convert a user-friendly name to an API code. Helpful before
+    data360_search_indicators (required_country) or when building disaggregation_filters
+    for data360_get_data / data360_get_viz_spec. Not required if 3-letter codes are already known.
+
+    For REF_AREA queries, results include group metadata:
+      - is_group (bool): whether the code is a country group or an individual country
+      - group_type (str): REGION, INCOME, LENDING, OTHER, REGION_UN, or CONTINENT
+      - member_count (int): number of countries in the group
+      - note (str): guidance on using data360_expand_country_group
+
+    Workflow for country groups (e.g. "South Asian countries", "low income countries"):
+      1. Call this function with codelist_type="REF_AREA" and the group name as query.
+      2. If the result has is_group=True, you have the group code (e.g. "SAS", "LIC").
+      3. To get individual country-level codes, call data360_expand_country_group with
+         that code. Use the returned country_codes string directly in data360_get_data
+         or data360_search_indicators disaggregation_filters.
+      4. To use the group as a regional aggregate instead, pass the group code directly
+         (e.g. REF_AREA="SAS") without expanding.
+
+    Args:
+        codelist_type: One of REF_AREA (countries/regions), FREQ, SEX, AGE, URBANISATION, UNIT_MEASURE.
+        query: Search term (e.g. "Kenya", "female", "annual"). Comma-separated for multiple
+            (e.g. "Kenya, Tanzania") returns one match per part. For REF_AREA, natural-language
+            group phrases are also recognized (e.g. "South Asian countries", "low income countries").
+        limit: Maximum number of matches to return (default 5).
+
+    Returns:
+        List of dicts, each with: id (code, e.g. "KEN"), name (e.g. "Kenya"), score (relevance 0–100).
+        For REF_AREA, also includes is_group, group_type, member_count, note when applicable.
+        Sorted by score descending. Empty list if no matches or unknown codelist_type.
+    """
+    # Check alias map for REF_AREA before fuzzy search.
+    if codelist_type.upper() == "REF_AREA":
+        alias_key = query.lower().strip()
+        if alias_key in _GROUP_ALIASES:
+            group_code = _GROUP_ALIASES[alias_key]
+            ghm = get_group_hierarchy_manager()
+            info = ghm.get_group_info(group_code)
+            if info:
+                result = {
+                    "id": group_code,
+                    "name": info["name"],
+                    "score": 100,
+                    "is_group": True,
+                    "group_type": info["type"],
+                    "member_count": len(info["countries"]),
+                    "note": _make_group_note(group_code, info),
+                }
+                return [result]
+
+    manager = get_codelist_manager()
+    return await manager.find_value(codelist_type, query, limit)
+
+
+async def get_codelist_mapping(codelist_type: str) -> dict[str, str]:
+    """Get mapping of codes to names for a codelist."""
+    manager = get_codelist_manager()
+    return await manager.get_codelist_mapping(codelist_type)
+
+
+# Convenience functions for common codelists
+async def find_reference_area(query: str, limit: int = 5) -> list[dict[str, Any]]:
+    """Find reference areas (countries/regions) matching the query."""
+    return await find_codelist_value("REF_AREA", query, limit)
+
+
+async def find_frequency(query: str, limit: int = 5) -> list[dict[str, Any]]:
+    """Find frequency codes matching the query."""
+    return await find_codelist_value("FREQ", query, limit)
+
+
+async def find_sex(query: str, limit: int = 5) -> list[dict[str, Any]]:
+    """Find sex/gender codes matching the query."""
+    return await find_codelist_value("SEX", query, limit)
+
+
+async def find_age_group(query: str, limit: int = 5) -> list[dict[str, Any]]:
+    """Find age group codes matching the query."""
+    return await find_codelist_value("AGE", query, limit)
+
+
+async def expand_country_group(
+    group_code: str,
+) -> dict[str, Any]:
+    """Expand a REF_AREA group code into its constituent country codes.
+
+    Use this when a user asks about a region, income group, or lending category
+    and you need individual country-level data rather than the aggregate.
+
+    Workflow for group discovery and expansion:
+      1. If you only have a natural-language name (e.g. "South Asian countries"),
+         call data360_find_codelist_value(codelist_type="REF_AREA", query="<name>")
+         first to resolve it to a group code (e.g. "SAS").
+      2. Pass that code to this function to get the full country list.
+      3. Use the returned country_codes string as disaggregation_filters['REF_AREA']
+         (already comma-separated ISO codes), or pass the same codes via get_data's
+         country_code using semicolons between codes (e.g. 'KEN;MAR').
+
+    Decision guidance — check the returned `count` after calling this function:
+    - count <= 20: proceed with country-level data retrieval directly.
+    - count > 20: inform the user before fetching all countries. Say:
+      "This group contains N countries. Do you want individual country-level
+      data for all of them, or would you prefer the regional aggregate?"
+      Wait for their answer before proceeding.
+
+    Covers groups sourced from FMR H_REF_AREA_GROUPS v38.0:
+      REGION    - WB regional classifications (SAS, SSF, EAS, ECS, LCN, ...)
+      INCOME    - LIC, LMC, UMC, HIC, MIC, LMY, MIX
+      LENDING   - IDA, IBRD, blend classifications
+      OTHER     - FCS, LDC, SST, OED, EUU, ...
+      REGION_UN - UN M49 statistical divisions
+      CONTINENT - Continental groupings
+
+    Args:
+        group_code: REF_AREA group code (e.g. "SAS", "LIC", "EAS", "FCS").
+            Case-insensitive. Natural-language names (e.g. "south asian countries")
+            are also accepted as a convenience; they are resolved via the alias map.
+            For reliable discovery, use data360_find_codelist_value first.
+
+    Returns:
+        Dict with:
+          - group_code (str): uppercased code
+          - group_name (str): human-readable name
+          - group_type (str): REGION | INCOME | LENDING | OTHER | REGION_UN | CONTINENT
+          - countries (list[dict]): [{code, name}] for each member country
+          - country_codes (str): comma-separated codes for direct use in API calls
+          - count (int): number of member countries
+          - hierarchy_version (str): FMR hierarchy version used
+        On failure:
+          - error (str): description of what went wrong
+    """
+    ghm = get_group_hierarchy_manager()
+    code_upper = group_code.strip().upper()
+    info = ghm.get_group_info(code_upper)
+
+    if not info:
+        # Try alias resolution as a fallback
+        alias_key = group_code.lower().strip()
+        if alias_key in _GROUP_ALIASES:
+            code_upper = _GROUP_ALIASES[alias_key]
+            info = ghm.get_group_info(code_upper)
+
+    if not info:
+        return {
+            "error": (
+                f"Unknown group code: '{group_code}'. "
+                "Use data360_find_codelist_value('REF_AREA', '<name>') to find "
+                "the correct code, or check that the group exists in the FMR hierarchy."
+            )
+        }
+
+    # Build country list with names from the Data360 codelist (best-effort).
+    # Codes are always available; names may be missing for some entries.
+    cl_manager = get_codelist_manager()
+    country_name_map: dict[str, str] = {}
+    try:
+        country_name_map = await cl_manager.get_codelist_mapping("REF_AREA")
+    except Exception as e:
+        # Names are a convenience; codes are always returned even without them.
+        _logger.warning(
+            "expand_country_group: failed to fetch REF_AREA name mapping for '%s': %s. "
+            "Country names will fall back to code strings.",
+            code_upper,
+            e,
+        )
+
+    countries = [
+        {"code": c, "name": country_name_map.get(c, c)} for c in info["countries"]
+    ]
+
+    meta = ghm.get_meta()
+
+    return {
+        "group_code": code_upper,
+        "group_name": info["name"],
+        "group_type": info["type"],
+        "countries": countries,
+        "country_codes": ",".join(c["code"] for c in countries),
+        "count": len(countries),
+        "hierarchy_version": meta.get("hierarchy_version", "unknown"),
+    }

src/data360/ref_area_groups.json

@@ -0,0 +1,5633 @@
+{
+  "_meta": {
+    "source": "FMR H_REF_AREA_GROUPS v38.0 + CL_REF_GROUPINGS",
+    "built_at": "2026-04-26",
+    "hierarchy_version": "38.0",
+    "total_groups": 147,
+    "total_countries": 251,
+    "group_types": [
+      "CONTINENT",
+      "INCOME",
+      "LENDING",
+      "OTHER",
+      "REGION",
+      "REGION_UN"
+    ],
+    "note": "Re-generate with: uv run python scripts/build_ref_area_groups.py"
+  },
+  "groups": {
+    "AFE": {
+      "name": "Africa Eastern and Southern",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "BDI",
+        "BWA",
+        "COD",
+        "COM",
+        "ERI",
+        "ETH",
+        "KEN",
+        "LSO",
+        "MDG",
+        "MOZ",
+        "MUS",
+        "MWI",
+        "NAM",
+        "RWA",
+        "SDN",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "AFW": {
+      "name": "Africa Western and Central",
+      "type": "REGION",
+      "countries": [
+        "BEN",
+        "BFA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COG",
+        "CPV",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "LBR",
+        "MLI",
+        "MRT",
+        "NER",
+        "NGA",
+        "SEN",
+        "SLE",
+        "TCD",
+        "TGO"
+      ]
+    },
+    "ARB": {
+      "name": "Arab World",
+      "type": "REGION",
+      "countries": [
+        "ARE",
+        "BHR",
+        "COM",
+        "DJI",
+        "DZA",
+        "EGY",
+        "IRQ",
+        "JOR",
+        "KWT",
+        "LBN",
+        "LBY",
+        "MAR",
+        "MRT",
+        "OMN",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SDN",
+        "SOM",
+        "SYR",
+        "TUN",
+        "YEM"
+      ]
+    },
+    "BEA": {
+      "name": "East Asia & Pacific (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "CHN",
+        "IDN",
+        "MNG",
+        "MYS",
+        "NRU",
+        "PHL",
+        "PLW",
+        "THA",
+        "VNM"
+      ]
+    },
+    "BEC": {
+      "name": "Europe & Central Asia (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "ALB",
+        "ARM",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "GEO",
+        "HRV",
+        "KAZ",
+        "MDA",
+        "MKD",
+        "MNE",
+        "POL",
+        "ROU",
+        "RUS",
+        "SRB",
+        "TKM",
+        "TUR",
+        "UKR"
+      ]
+    },
+    "BLA": {
+      "name": "Latin America & Caribbean (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "ARG",
+        "ATG",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "CHL",
+        "COL",
+        "CRI",
+        "DOM",
+        "ECU",
+        "GTM",
+        "JAM",
+        "KNA",
+        "MEX",
+        "PAN",
+        "PER",
+        "PRY",
+        "SLV",
+        "SUR",
+        "TTO",
+        "URY",
+        "VEN"
+      ]
+    },
+    "BMN": {
+      "name": "Middle East, North Africa, Afghanistan & Pakistan (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "DZA",
+        "EGY",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "LBN",
+        "LBY",
+        "MAR",
+        "TUN"
+      ]
+    },
+    "BSA": {
+      "name": "South Asia (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "IND"
+      ]
+    },
+    "BSS": {
+      "name": "Sub-Saharan Africa (IBRD only)",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "BWA",
+        "GAB",
+        "GNQ",
+        "MUS",
+        "NAM",
+        "SWZ",
+        "SYC",
+        "ZAF"
+      ]
+    },
+    "CAM": {
+      "name": "Central America (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "BLZ",
+        "CRI",
+        "GTM",
+        "HND",
+        "MEX",
+        "NIC",
+        "SLV"
+      ]
+    },
+    "CAS": {
+      "name": "Central Asia (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "KAZ",
+        "KGZ",
+        "TJK",
+        "TKM",
+        "UZB"
+      ]
+    },
+    "CAT": {
+      "name": "Central Asia and Turkiye",
+      "type": "REGION",
+      "countries": [
+        "KAZ",
+        "KGZ",
+        "TJK",
+        "TKM",
+        "TUR",
+        "UZB"
+      ]
+    },
+    "CFR": {
+      "name": "Central Africa (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "GAB",
+        "GNQ",
+        "STP",
+        "TCD"
+      ]
+    },
+    "CMD": {
+      "name": "Middle East",
+      "type": "REGION",
+      "countries": [
+        "ARE",
+        "BHR",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "KWT",
+        "LBN",
+        "OMN",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SYR",
+        "YEM"
+      ]
+    },
+    "CNA": {
+      "name": "Central Asia",
+      "type": "REGION",
+      "countries": [
+        "KAZ",
+        "KGZ",
+        "TJK",
+        "TKM",
+        "UZB"
+      ]
+    },
+    "CRB": {
+      "name": "Caribbean (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "CUB",
+        "DMA",
+        "DOM",
+        "GRD",
+        "HTI",
+        "JAM",
+        "LCA",
+        "VCT"
+      ]
+    },
+    "DEA": {
+      "name": "East Asia & Pacific (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "FJI",
+        "FSM",
+        "KHM",
+        "KIR",
+        "LAO",
+        "MHL",
+        "MMR",
+        "PNG",
+        "SLB",
+        "TLS",
+        "TON",
+        "TUV",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "DEC": {
+      "name": "Europe & Central Asia (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "KGZ",
+        "TJK",
+        "UZB",
+        "XKX"
+      ]
+    },
+    "DLA": {
+      "name": "Latin America & Caribbean (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "DMA",
+        "GRD",
+        "GUY",
+        "HND",
+        "HTI",
+        "LCA",
+        "NIC",
+        "VCT"
+      ]
+    },
+    "DMN": {
+      "name": "Middle East, North Africa, Afghanistan & Pakistan (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "DJI",
+        "PAK",
+        "SYR",
+        "YEM"
+      ]
+    },
+    "DSA": {
+      "name": "South Asia (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "BGD",
+        "BTN",
+        "LKA",
+        "MDV",
+        "NPL"
+      ]
+    },
+    "DSS": {
+      "name": "Sub-Saharan Africa (IDA total)",
+      "type": "REGION",
+      "countries": [
+        "BDI",
+        "BEN",
+        "BFA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "ERI",
+        "ETH",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "KEN",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NGA",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "EAP": {
+      "name": "East Asia & Pacific (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "CHN",
+        "FJI",
+        "FSM",
+        "IDN",
+        "KHM",
+        "KIR",
+        "LAO",
+        "MHL",
+        "MMR",
+        "MNG",
+        "MYS",
+        "PHL",
+        "PLW",
+        "PNG",
+        "PRK",
+        "SLB",
+        "THA",
+        "TLS",
+        "TON",
+        "TUV",
+        "VNM",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "EAS": {
+      "name": "East Asia & Pacific",
+      "type": "REGION",
+      "countries": [
+        "ASM",
+        "AUS",
+        "BRN",
+        "CHN",
+        "FJI",
+        "FSM",
+        "GUM",
+        "HKG",
+        "IDN",
+        "JPN",
+        "KHM",
+        "KIR",
+        "KOR",
+        "LAO",
+        "MAC",
+        "MHL",
+        "MMR",
+        "MNG",
+        "MNP",
+        "MYS",
+        "NCL",
+        "NRU",
+        "NZL",
+        "PHL",
+        "PLW",
+        "PNG",
+        "PRK",
+        "PYF",
+        "SGP",
+        "SLB",
+        "THA",
+        "TLS",
+        "TON",
+        "TUV",
+        "TWN",
+        "VNM",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "ECA": {
+      "name": "Europe & Central Asia (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "ALB",
+        "ARM",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "GEO",
+        "KAZ",
+        "KGZ",
+        "MDA",
+        "MKD",
+        "MNE",
+        "RUS",
+        "SRB",
+        "TJK",
+        "TKM",
+        "TUR",
+        "UKR",
+        "UZB",
+        "XKX"
+      ]
+    },
+    "ECS": {
+      "name": "Europe & Central Asia",
+      "type": "REGION",
+      "countries": [
+        "ALB",
+        "AND",
+        "ARM",
+        "AUT",
+        "AZE",
+        "BEL",
+        "BGR",
+        "BIH",
+        "BLR",
+        "CHE",
+        "CHI",
+        "CYP",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "FRO",
+        "GBR",
+        "GEO",
+        "GIB",
+        "GRC",
+        "GRL",
+        "HRV",
+        "HUN",
+        "IMN",
+        "IRL",
+        "ISL",
+        "ITA",
+        "KAZ",
+        "KGZ",
+        "LIE",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MCO",
+        "MDA",
+        "MKD",
+        "MNE",
+        "NLD",
+        "NOR",
+        "POL",
+        "PRT",
+        "ROU",
+        "RUS",
+        "SMR",
+        "SRB",
+        "SVK",
+        "SVN",
+        "SWE",
+        "TJK",
+        "TKM",
+        "TUR",
+        "UKR",
+        "UZB",
+        "XKX"
+      ]
+    },
+    "EER": {
+      "name": "Eastern Europe (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "BGR",
+        "BLR",
+        "MDA",
+        "RUS",
+        "UKR"
+      ]
+    },
+    "ESA": {
+      "name": "East and Southern Africa (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "BDI",
+        "BWA",
+        "COM",
+        "ERI",
+        "ETH",
+        "KEN",
+        "LSO",
+        "MDG",
+        "MOZ",
+        "MUS",
+        "MWI",
+        "NAM",
+        "RWA",
+        "SDN",
+        "SOM",
+        "SSD",
+        "SWZ",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "ESS": {
+      "name": "Eastern Asia (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "CHN",
+        "MNG",
+        "PRK"
+      ]
+    },
+    "LAC": {
+      "name": "Latin America & Caribbean (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "ARG",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "COL",
+        "CRI",
+        "CUB",
+        "DMA",
+        "DOM",
+        "ECU",
+        "GRD",
+        "GTM",
+        "HND",
+        "HTI",
+        "JAM",
+        "LCA",
+        "MEX",
+        "NIC",
+        "PER",
+        "PRY",
+        "SLV",
+        "SUR",
+        "VCT"
+      ]
+    },
+    "LCN": {
+      "name": "Latin America & Caribbean",
+      "type": "REGION",
+      "countries": [
+        "ABW",
+        "ARG",
+        "ATG",
+        "BHS",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BRB",
+        "CHL",
+        "COL",
+        "CRI",
+        "CUB",
+        "CUW",
+        "CYM",
+        "DMA",
+        "DOM",
+        "ECU",
+        "GRD",
+        "GTM",
+        "GUY",
+        "HND",
+        "HTI",
+        "JAM",
+        "KNA",
+        "LCA",
+        "MAF",
+        "MEX",
+        "NIC",
+        "PAN",
+        "PER",
+        "PRI",
+        "PRY",
+        "SLV",
+        "SUR",
+        "SXM",
+        "TCA",
+        "TTO",
+        "URY",
+        "VCT",
+        "VEN",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "MCT": {
+      "name": "Middle East, Central Asia and Turkiye",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "ARE",
+        "BHR",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "KAZ",
+        "KGZ",
+        "KWT",
+        "LBN",
+        "OMN",
+        "PAK",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SYR",
+        "TJK",
+        "TKM",
+        "TUR",
+        "UZB",
+        "YEM"
+      ]
+    },
+    "MDE": {
+      "name": "Middle East (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "DJI",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "LBN",
+        "PSE",
+        "SYR",
+        "YEM"
+      ]
+    },
+    "MEA": {
+      "name": "Middle East, North Africa, Afghanistan & Pakistan",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "ARE",
+        "BHR",
+        "DJI",
+        "DZA",
+        "EGY",
+        "IRN",
+        "IRQ",
+        "ISR",
+        "JOR",
+        "KWT",
+        "LBN",
+        "LBY",
+        "MAR",
+        "MLT",
+        "OMN",
+        "PAK",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SYR",
+        "TUN",
+        "YEM"
+      ]
+    },
+    "MNA": {
+      "name": "Middle East, North Africa, Afghanistan & Pakistan (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "DJI",
+        "DZA",
+        "EGY",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "LBN",
+        "LBY",
+        "MAR",
+        "PAK",
+        "PSE",
+        "SYR",
+        "TUN",
+        "YEM"
+      ]
+    },
+    "MPA": {
+      "name": "Middle East, Pakistan, and Afghanistan",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "ARE",
+        "BHR",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "KWT",
+        "LBN",
+        "OMN",
+        "PAK",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SYR",
+        "YEM"
+      ]
+    },
+    "NAC": {
+      "name": "North America",
+      "type": "REGION",
+      "countries": [
+        "BMU",
+        "CAN",
+        "USA"
+      ]
+    },
+    "NAF": {
+      "name": "North Africa",
+      "type": "REGION",
+      "countries": [
+        "DZA",
+        "EGY",
+        "LBY",
+        "MAR",
+        "TUN"
+      ]
+    },
+    "PAC": {
+      "name": "Pacific (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "FJI",
+        "FSM",
+        "KIR",
+        "MHL",
+        "PNG",
+        "SLB",
+        "TON",
+        "TUV",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "SAM": {
+      "name": "South America (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "ARG",
+        "BOL",
+        "BRA",
+        "COL",
+        "ECU",
+        "PER",
+        "PRY",
+        "SUR"
+      ]
+    },
+    "SAS": {
+      "name": "South Asia",
+      "type": "REGION",
+      "countries": [
+        "BGD",
+        "BTN",
+        "IND",
+        "LKA",
+        "MDV",
+        "NPL"
+      ]
+    },
+    "SAX": {
+      "name": "South Asia, excluding India",
+      "type": "REGION",
+      "countries": [
+        "BGD",
+        "BTN",
+        "LKA",
+        "MDV",
+        "NPL"
+      ]
+    },
+    "SEA": {
+      "name": "South-Eastern Asia (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "IDN",
+        "KHM",
+        "LAO",
+        "MMR",
+        "MYS",
+        "PHL",
+        "THA",
+        "TLS",
+        "VNM"
+      ]
+    },
+    "SER": {
+      "name": "Southern Europe (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "ALB",
+        "ARM",
+        "AZE",
+        "BIH",
+        "GEO",
+        "MKD",
+        "MNE",
+        "SRB",
+        "TUR",
+        "XKX"
+      ]
+    },
+    "SSA": {
+      "name": "Sub-Saharan Africa (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "ERI",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "KEN",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "NAM",
+        "NER",
+        "NGA",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "SSF": {
+      "name": "Sub-Saharan Africa",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "ERI",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "KEN",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "NAM",
+        "NER",
+        "NGA",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "TEA": {
+      "name": "East Asia & Pacific (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "CHN",
+        "FJI",
+        "FSM",
+        "IDN",
+        "KHM",
+        "KIR",
+        "LAO",
+        "MHL",
+        "MMR",
+        "MNG",
+        "MYS",
+        "NRU",
+        "PHL",
+        "PLW",
+        "PNG",
+        "SLB",
+        "THA",
+        "TLS",
+        "TON",
+        "TUV",
+        "VNM",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "TEC": {
+      "name": "Europe & Central Asia (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "ALB",
+        "ARM",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "GEO",
+        "HRV",
+        "KAZ",
+        "KGZ",
+        "MDA",
+        "MKD",
+        "MNE",
+        "POL",
+        "ROU",
+        "RUS",
+        "SRB",
+        "TJK",
+        "TKM",
+        "TUR",
+        "UKR",
+        "UZB",
+        "XKX"
+      ]
+    },
+    "TLA": {
+      "name": "Latin America & Caribbean (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "ARG",
+        "ATG",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "CHL",
+        "COL",
+        "CRI",
+        "DMA",
+        "DOM",
+        "ECU",
+        "GRD",
+        "GTM",
+        "GUY",
+        "HND",
+        "HTI",
+        "JAM",
+        "KNA",
+        "LCA",
+        "MEX",
+        "NIC",
+        "PAN",
+        "PER",
+        "PRY",
+        "SLV",
+        "SUR",
+        "TTO",
+        "URY",
+        "VCT",
+        "VEN"
+      ]
+    },
+    "TMN": {
+      "name": "Middle East, North Africa, Afghanistan & Pakistan (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "AFG",
+        "DJI",
+        "DZA",
+        "EGY",
+        "IRN",
+        "IRQ",
+        "JOR",
+        "LBN",
+        "LBY",
+        "MAR",
+        "PAK",
+        "SYR",
+        "TUN",
+        "YEM"
+      ]
+    },
+    "TSA": {
+      "name": "South Asia (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "BGD",
+        "BTN",
+        "IND",
+        "LKA",
+        "MDV",
+        "NPL"
+      ]
+    },
+    "TSS": {
+      "name": "Sub-Saharan Africa (IDA & IBRD)",
+      "type": "REGION",
+      "countries": [
+        "AGO",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "ERI",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "KEN",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "NAM",
+        "NER",
+        "NGA",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "WAF": {
+      "name": "West Africa (excluding high income)",
+      "type": "REGION",
+      "countries": [
+        "BEN",
+        "BFA",
+        "CIV",
+        "CPV",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "LBR",
+        "MLI",
+        "MRT",
+        "NER",
+        "NGA",
+        "SEN",
+        "SLE",
+        "TGO"
+      ]
+    },
+    "9AF": {
+      "name": "UN M49 Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "AGO",
+        "ATF",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "DZA",
+        "EGY",
+        "ERI",
+        "ESH",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "IOT",
+        "KEN",
+        "LBR",
+        "LBY",
+        "LSO",
+        "MAR",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "MYT",
+        "NAM",
+        "NER",
+        "NGA",
+        "REU",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SHN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TCD",
+        "TGO",
+        "TUN",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "9AM": {
+      "name": "UN M49 Americas",
+      "type": "REGION_UN",
+      "countries": [
+        "ABW",
+        "AIA",
+        "ARG",
+        "ATG",
+        "BES",
+        "BHS",
+        "BLM",
+        "BLZ",
+        "BMU",
+        "BOL",
+        "BRA",
+        "BRB",
+        "BVT",
+        "CAN",
+        "CHL",
+        "COL",
+        "CRI",
+        "CUB",
+        "CUW",
+        "CYM",
+        "DMA",
+        "DOM",
+        "ECU",
+        "FLK",
+        "GLP",
+        "GRD",
+        "GRL",
+        "GTM",
+        "GUF",
+        "GUY",
+        "HND",
+        "HTI",
+        "JAM",
+        "KNA",
+        "LCA",
+        "MAF",
+        "MEX",
+        "MSR",
+        "MTQ",
+        "NIC",
+        "PAN",
+        "PER",
+        "PRI",
+        "PRY",
+        "SGS",
+        "SLV",
+        "SPM",
+        "SUR",
+        "SXM",
+        "TCA",
+        "TTO",
+        "URY",
+        "USA",
+        "VCT",
+        "VEN",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "9AS": {
+      "name": "UN M49 Asia",
+      "type": "REGION_UN",
+      "countries": [
+        "AFG",
+        "ARE",
+        "ARM",
+        "AZE",
+        "BGD",
+        "BHR",
+        "BRN",
+        "BTN",
+        "CHN",
+        "CYP",
+        "GEO",
+        "HKG",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "ISR",
+        "JOR",
+        "JPN",
+        "KAZ",
+        "KGZ",
+        "KHM",
+        "KOR",
+        "KWT",
+        "LAO",
+        "LBN",
+        "LKA",
+        "MAC",
+        "MDV",
+        "MMR",
+        "MNG",
+        "MYS",
+        "NPL",
+        "OMN",
+        "PAK",
+        "PHL",
+        "PRK",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SGP",
+        "SYR",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TUR",
+        "UZB",
+        "VNM",
+        "YEM"
+      ]
+    },
+    "9AZ": {
+      "name": "UN M49 Australia and New Zealand",
+      "type": "REGION_UN",
+      "countries": [
+        "AUS",
+        "CCK",
+        "CXR",
+        "HMD",
+        "NFK",
+        "NZL"
+      ]
+    },
+    "9CA": {
+      "name": "UN M49 Central Asia",
+      "type": "REGION_UN",
+      "countries": [
+        "KAZ",
+        "KGZ",
+        "TJK",
+        "TKM",
+        "UZB"
+      ]
+    },
+    "9CM": {
+      "name": "UN M49 Central America",
+      "type": "REGION_UN",
+      "countries": [
+        "BLZ",
+        "CRI",
+        "GTM",
+        "HND",
+        "MEX",
+        "NIC",
+        "PAN",
+        "SLV"
+      ]
+    },
+    "9CR": {
+      "name": "UN M49 Caribbean",
+      "type": "REGION_UN",
+      "countries": [
+        "ABW",
+        "AIA",
+        "ATG",
+        "BES",
+        "BHS",
+        "BLM",
+        "BRB",
+        "CUB",
+        "CUW",
+        "CYM",
+        "DMA",
+        "DOM",
+        "GLP",
+        "GRD",
+        "HTI",
+        "JAM",
+        "KNA",
+        "LCA",
+        "MAF",
+        "MSR",
+        "MTQ",
+        "PRI",
+        "SXM",
+        "TCA",
+        "TTO",
+        "VCT",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "9CS": {
+      "name": "UN M49 Central Asia and Southern Asia (MDG=M49)",
+      "type": "REGION_UN",
+      "countries": [
+        "AFG",
+        "BGD",
+        "BTN",
+        "IND",
+        "IRN",
+        "KAZ",
+        "KGZ",
+        "LKA",
+        "MDV",
+        "NPL",
+        "PAK",
+        "TJK",
+        "TKM",
+        "UZB"
+      ]
+    },
+    "9EA": {
+      "name": "UN M49 Eastern Asia",
+      "type": "REGION_UN",
+      "countries": [
+        "CHN",
+        "HKG",
+        "JPN",
+        "KOR",
+        "MAC",
+        "MNG",
+        "PRK"
+      ]
+    },
+    "9EE": {
+      "name": "UN M49 Eastern Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "BGR",
+        "BLR",
+        "CZE",
+        "HUN",
+        "MDA",
+        "POL",
+        "ROU",
+        "RUS",
+        "SVK",
+        "UKR"
+      ]
+    },
+    "9EF": {
+      "name": "UN M49 Eastern Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "ATF",
+        "BDI",
+        "COM",
+        "DJI",
+        "ERI",
+        "ETH",
+        "IOT",
+        "KEN",
+        "MDG",
+        "MOZ",
+        "MUS",
+        "MWI",
+        "MYT",
+        "REU",
+        "RWA",
+        "SOM",
+        "SSD",
+        "SYC",
+        "TZA",
+        "UGA",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "9ES": {
+      "name": "UN M49 Eastern Asia and South-eastern Asia (MDG=M49)",
+      "type": "REGION_UN",
+      "countries": [
+        "BRN",
+        "CHN",
+        "HKG",
+        "IDN",
+        "JPN",
+        "KHM",
+        "KOR",
+        "LAO",
+        "MAC",
+        "MMR",
+        "MNG",
+        "MYS",
+        "PHL",
+        "PRK",
+        "SGP",
+        "THA",
+        "TLS",
+        "VNM"
+      ]
+    },
+    "9EU": {
+      "name": "UN M49 Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "ALA",
+        "ALB",
+        "AND",
+        "AUT",
+        "BEL",
+        "BGR",
+        "BIH",
+        "BLR",
+        "CHE",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "FRO",
+        "GBR",
+        "GGY",
+        "GIB",
+        "GRC",
+        "HRV",
+        "HUN",
+        "IMN",
+        "IRL",
+        "ISL",
+        "ITA",
+        "JEY",
+        "LIE",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MCO",
+        "MDA",
+        "MKD",
+        "MLT",
+        "MNE",
+        "NLD",
+        "NOR",
+        "POL",
+        "PRT",
+        "ROU",
+        "RUS",
+        "SJM",
+        "SMR",
+        "SRB",
+        "SVK",
+        "SVN",
+        "SWE",
+        "UKR",
+        "VAT"
+      ]
+    },
+    "9LC": {
+      "name": "UN M49 Latin America and the Caribbean (MDG=M49)",
+      "type": "REGION_UN",
+      "countries": [
+        "ABW",
+        "AIA",
+        "ARG",
+        "ATG",
+        "BES",
+        "BHS",
+        "BLM",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BRB",
+        "BVT",
+        "CHL",
+        "COL",
+        "CRI",
+        "CUB",
+        "CUW",
+        "CYM",
+        "DMA",
+        "DOM",
+        "ECU",
+        "FLK",
+        "GLP",
+        "GRD",
+        "GTM",
+        "GUF",
+        "GUY",
+        "HND",
+        "HTI",
+        "JAM",
+        "KNA",
+        "LCA",
+        "MAF",
+        "MEX",
+        "MSR",
+        "MTQ",
+        "NIC",
+        "PAN",
+        "PER",
+        "PRI",
+        "PRY",
+        "SGS",
+        "SLV",
+        "SUR",
+        "SXM",
+        "TCA",
+        "TTO",
+        "URY",
+        "VCT",
+        "VEN",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "9MC": {
+      "name": "UN M49 Micronesia",
+      "type": "REGION_UN",
+      "countries": [
+        "FSM",
+        "GUM",
+        "KIR",
+        "MHL",
+        "MNP",
+        "NRU",
+        "PLW",
+        "UMI"
+      ]
+    },
+    "9MF": {
+      "name": "UN M49 Middle Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "AGO",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "GAB",
+        "GNQ",
+        "STP",
+        "TCD"
+      ]
+    },
+    "9ML": {
+      "name": "UN M49 Melanesia",
+      "type": "REGION_UN",
+      "countries": [
+        "FJI",
+        "NCL",
+        "PNG",
+        "SLB",
+        "VUT"
+      ]
+    },
+    "9NE": {
+      "name": "UN M49 Northern America and Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "ALA",
+        "ALB",
+        "AND",
+        "AUT",
+        "BEL",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BMU",
+        "CAN",
+        "CHE",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "FRO",
+        "GBR",
+        "GGY",
+        "GIB",
+        "GRC",
+        "GRL",
+        "HRV",
+        "HUN",
+        "IMN",
+        "IRL",
+        "ISL",
+        "ITA",
+        "JEY",
+        "LIE",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MCO",
+        "MDA",
+        "MKD",
+        "MLT",
+        "MNE",
+        "NLD",
+        "NOR",
+        "POL",
+        "PRT",
+        "ROU",
+        "RUS",
+        "SJM",
+        "SMR",
+        "SPM",
+        "SRB",
+        "SVK",
+        "SVN",
+        "SWE",
+        "UKR",
+        "USA",
+        "VAT"
+      ]
+    },
+    "9NF": {
+      "name": "UN M49 Northern Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "DZA",
+        "EGY",
+        "ESH",
+        "LBY",
+        "MAR",
+        "SDN",
+        "TUN"
+      ]
+    },
+    "9NM": {
+      "name": "UN M49 Northern America",
+      "type": "REGION_UN",
+      "countries": [
+        "BMU",
+        "CAN",
+        "GRL",
+        "SPM",
+        "USA"
+      ]
+    },
+    "9NU": {
+      "name": "UN M49 Northern Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "ALA",
+        "DNK",
+        "EST",
+        "FIN",
+        "FRO",
+        "GBR",
+        "GGY",
+        "IMN",
+        "IRL",
+        "ISL",
+        "JEY",
+        "LTU",
+        "LVA",
+        "NOR",
+        "SJM",
+        "SWE"
+      ]
+    },
+    "9OC": {
+      "name": "UN M49 Oceania",
+      "type": "REGION_UN",
+      "countries": [
+        "ASM",
+        "AUS",
+        "CCK",
+        "COK",
+        "CXR",
+        "FJI",
+        "FSM",
+        "GUM",
+        "HMD",
+        "KIR",
+        "MHL",
+        "MNP",
+        "NCL",
+        "NFK",
+        "NIU",
+        "NRU",
+        "NZL",
+        "PCN",
+        "PLW",
+        "PNG",
+        "PYF",
+        "SLB",
+        "TKL",
+        "TON",
+        "TUV",
+        "UMI",
+        "VUT",
+        "WLF",
+        "WSM"
+      ]
+    },
+    "9OX": {
+      "name": "UN M49 Oceania excluding Australia and New Zealand",
+      "type": "REGION_UN",
+      "countries": [
+        "ASM",
+        "COK",
+        "FJI",
+        "FSM",
+        "GUM",
+        "KIR",
+        "MHL",
+        "MNP",
+        "NCL",
+        "NIU",
+        "NRU",
+        "PCN",
+        "PLW",
+        "PNG",
+        "PYF",
+        "SLB",
+        "TKL",
+        "TON",
+        "TUV",
+        "UMI",
+        "VUT",
+        "WLF",
+        "WSM"
+      ]
+    },
+    "9PL": {
+      "name": "UN M49 Polynesia",
+      "type": "REGION_UN",
+      "countries": [
+        "ASM",
+        "COK",
+        "NIU",
+        "PCN",
+        "PYF",
+        "TKL",
+        "TON",
+        "TUV",
+        "WLF",
+        "WSM"
+      ]
+    },
+    "9SA": {
+      "name": "UN M49 Southern Asia (MDG=M49)",
+      "type": "REGION_UN",
+      "countries": [
+        "AFG",
+        "BGD",
+        "BTN",
+        "IND",
+        "IRN",
+        "LKA",
+        "MDV",
+        "NPL",
+        "PAK"
+      ]
+    },
+    "9SE": {
+      "name": "UN M49 South-eastern Asia (MDG=M49)",
+      "type": "REGION_UN",
+      "countries": [
+        "BRN",
+        "IDN",
+        "KHM",
+        "LAO",
+        "MMR",
+        "MYS",
+        "PHL",
+        "SGP",
+        "THA",
+        "TLS",
+        "VNM"
+      ]
+    },
+    "9SF": {
+      "name": "UN M49 Southern Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "BWA",
+        "LSO",
+        "NAM",
+        "SWZ",
+        "ZAF"
+      ]
+    },
+    "9SM": {
+      "name": "UN M49 South America",
+      "type": "REGION_UN",
+      "countries": [
+        "ARG",
+        "BOL",
+        "BRA",
+        "BVT",
+        "CHL",
+        "COL",
+        "ECU",
+        "FLK",
+        "GUF",
+        "GUY",
+        "PER",
+        "PRY",
+        "SGS",
+        "SUR",
+        "URY",
+        "VEN"
+      ]
+    },
+    "9SS": {
+      "name": "UN M49 Sub-Saharan Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "AGO",
+        "ATF",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "ERI",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "IOT",
+        "KEN",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "MYT",
+        "NAM",
+        "NER",
+        "NGA",
+        "REU",
+        "RWA",
+        "SEN",
+        "SHN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "9SU": {
+      "name": "UN M49 Southern Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "ALB",
+        "AND",
+        "BIH",
+        "ESP",
+        "GIB",
+        "GRC",
+        "HRV",
+        "ITA",
+        "MKD",
+        "MLT",
+        "MNE",
+        "PRT",
+        "SMR",
+        "SRB",
+        "SVN",
+        "VAT"
+      ]
+    },
+    "9WA": {
+      "name": "UN M49 Western Asia",
+      "type": "REGION_UN",
+      "countries": [
+        "ARE",
+        "ARM",
+        "AZE",
+        "BHR",
+        "CYP",
+        "GEO",
+        "IRQ",
+        "ISR",
+        "JOR",
+        "KWT",
+        "LBN",
+        "OMN",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SYR",
+        "TUR",
+        "YEM"
+      ]
+    },
+    "9WE": {
+      "name": "UN M49 Western Europe",
+      "type": "REGION_UN",
+      "countries": [
+        "AUT",
+        "BEL",
+        "CHE",
+        "DEU",
+        "FRA",
+        "LIE",
+        "LUX",
+        "MCO",
+        "NLD"
+      ]
+    },
+    "9WF": {
+      "name": "UN M49 Western Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "BEN",
+        "BFA",
+        "CIV",
+        "CPV",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "LBR",
+        "MLI",
+        "MRT",
+        "NER",
+        "NGA",
+        "SEN",
+        "SHN",
+        "SLE",
+        "TGO"
+      ]
+    },
+    "9WL": {
+      "name": "UN M49 World",
+      "type": "REGION_UN",
+      "countries": [
+        "ABW",
+        "AFG",
+        "AGO",
+        "AIA",
+        "ALA",
+        "ALB",
+        "AND",
+        "ARE",
+        "ARG",
+        "ARM",
+        "ASM",
+        "ATF",
+        "ATG",
+        "AUS",
+        "AUT",
+        "AZE",
+        "BDI",
+        "BEL",
+        "BEN",
+        "BES",
+        "BFA",
+        "BGD",
+        "BGR",
+        "BHR",
+        "BHS",
+        "BIH",
+        "BLM",
+        "BLR",
+        "BLZ",
+        "BMU",
+        "BOL",
+        "BRA",
+        "BRB",
+        "BRN",
+        "BTN",
+        "BVT",
+        "BWA",
+        "CAF",
+        "CAN",
+        "CCK",
+        "CHE",
+        "CHL",
+        "CHN",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COK",
+        "COL",
+        "COM",
+        "CPV",
+        "CRI",
+        "CUB",
+        "CUW",
+        "CXR",
+        "CYM",
+        "CYP",
+        "CZE",
+        "DEU",
+        "DJI",
+        "DMA",
+        "DNK",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "ERI",
+        "ESH",
+        "ESP",
+        "EST",
+        "ETH",
+        "FIN",
+        "FJI",
+        "FLK",
+        "FRA",
+        "FRO",
+        "FSM",
+        "GAB",
+        "GBR",
+        "GEO",
+        "GGY",
+        "GHA",
+        "GIB",
+        "GIN",
+        "GLP",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "GRC",
+        "GRD",
+        "GRL",
+        "GTM",
+        "GUF",
+        "GUM",
+        "GUY",
+        "HKG",
+        "HMD",
+        "HND",
+        "HRV",
+        "HTI",
+        "HUN",
+        "IDN",
+        "IMN",
+        "IND",
+        "IOT",
+        "IRL",
+        "IRN",
+        "IRQ",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JAM",
+        "JEY",
+        "JOR",
+        "JPN",
+        "KAZ",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "KNA",
+        "KOR",
+        "KWT",
+        "LAO",
+        "LBN",
+        "LBR",
+        "LBY",
+        "LCA",
+        "LIE",
+        "LKA",
+        "LSO",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MAC",
+        "MAF",
+        "MAR",
+        "MCO",
+        "MDA",
+        "MDG",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MLI",
+        "MLT",
+        "MMR",
+        "MNE",
+        "MNG",
+        "MNP",
+        "MOZ",
+        "MRT",
+        "MSR",
+        "MTQ",
+        "MUS",
+        "MWI",
+        "MYS",
+        "MYT",
+        "NAM",
+        "NCL",
+        "NER",
+        "NFK",
+        "NGA",
+        "NIC",
+        "NIU",
+        "NLD",
+        "NOR",
+        "NPL",
+        "NRU",
+        "NZL",
+        "OMN",
+        "PAK",
+        "PAN",
+        "PCN",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "POL",
+        "PRI",
+        "PRK",
+        "PRT",
+        "PRY",
+        "PSE",
+        "PYF",
+        "QAT",
+        "REU",
+        "ROU",
+        "RUS",
+        "RWA",
+        "SAU",
+        "SDN",
+        "SEN",
+        "SGP",
+        "SGS",
+        "SHN",
+        "SJM",
+        "SLB",
+        "SLE",
+        "SLV",
+        "SMR",
+        "SOM",
+        "SPM",
+        "SRB",
+        "SSD",
+        "STP",
+        "SUR",
+        "SVK",
+        "SVN",
+        "SWE",
+        "SWZ",
+        "SXM",
+        "SYC",
+        "SYR",
+        "TCA",
+        "TCD",
+        "TGO",
+        "THA",
+        "TJK",
+        "TKL",
+        "TKM",
+        "TLS",
+        "TON",
+        "TTO",
+        "TUN",
+        "TUR",
+        "TUV",
+        "TZA",
+        "UGA",
+        "UKR",
+        "UMI",
+        "URY",
+        "USA",
+        "UZB",
+        "VAT",
+        "VCT",
+        "VEN",
+        "VGB",
+        "VIR",
+        "VNM",
+        "VUT",
+        "WLF",
+        "WSM",
+        "YEM",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "9WN": {
+      "name": "UN M49 Western Asia and Northern Africa",
+      "type": "REGION_UN",
+      "countries": [
+        "ARE",
+        "ARM",
+        "AZE",
+        "BHR",
+        "CYP",
+        "DZA",
+        "EGY",
+        "ESH",
+        "GEO",
+        "IRQ",
+        "ISR",
+        "JOR",
+        "KWT",
+        "LBN",
+        "LBY",
+        "MAR",
+        "OMN",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SDN",
+        "SYR",
+        "TUN",
+        "TUR",
+        "YEM"
+      ]
+    },
+    "24F": {
+      "name": "FY24 IDA countries classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "KIR",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "24T": {
+      "name": "FY24 IDA & IBRD countries classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "IRQ",
+        "KIR",
+        "LBN",
+        "LBY",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "UKR",
+        "VEN",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "25F": {
+      "name": "FY25 IDA countries classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "KIR",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "BHI": {
+      "name": "IBRD countries classified as high income",
+      "type": "LENDING",
+      "countries": [
+        "ATG",
+        "CHL",
+        "HRV",
+        "KNA",
+        "NRU",
+        "PAN",
+        "POL",
+        "ROU",
+        "SYC",
+        "TTO",
+        "URY"
+      ]
+    },
+    "DFS": {
+      "name": "IDA countries classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "KIR",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "DNF": {
+      "name": "IDA countries not classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "BEN",
+        "BGD",
+        "BTN",
+        "CIV",
+        "CPV",
+        "DJI",
+        "DMA",
+        "FJI",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GRD",
+        "GUY",
+        "HND",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "LAO",
+        "LBR",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MDG",
+        "MDV",
+        "MRT",
+        "MWI",
+        "NIC",
+        "NPL",
+        "PAK",
+        "RWA",
+        "SEN",
+        "SLE",
+        "TGO",
+        "TJK",
+        "TON",
+        "TZA",
+        "UGA",
+        "UZB",
+        "VCT",
+        "VUT",
+        "WSM",
+        "ZMB"
+      ]
+    },
+    "IBB": {
+      "name": "IBRD, including blend",
+      "type": "LENDING",
+      "countries": [
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "ATG",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BWA",
+        "CHL",
+        "CHN",
+        "CMR",
+        "COG",
+        "COL",
+        "CPV",
+        "CRI",
+        "DMA",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "FJI",
+        "GAB",
+        "GEO",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "HRV",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KEN",
+        "KNA",
+        "LBN",
+        "LBY",
+        "LCA",
+        "MAR",
+        "MDA",
+        "MEX",
+        "MKD",
+        "MNE",
+        "MNG",
+        "MUS",
+        "MYS",
+        "NAM",
+        "NGA",
+        "NRU",
+        "PAK",
+        "PAN",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "POL",
+        "PRY",
+        "ROU",
+        "RUS",
+        "SLV",
+        "SRB",
+        "SUR",
+        "SWZ",
+        "SYC",
+        "THA",
+        "TKM",
+        "TLS",
+        "TTO",
+        "TUN",
+        "TUR",
+        "UKR",
+        "URY",
+        "UZB",
+        "VCT",
+        "VEN",
+        "VNM",
+        "ZAF",
+        "ZWE"
+      ]
+    },
+    "IBD": {
+      "name": "IBRD only",
+      "type": "LENDING",
+      "countries": [
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "ATG",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BWA",
+        "CHL",
+        "CHN",
+        "COL",
+        "CRI",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "GAB",
+        "GEO",
+        "GNQ",
+        "GTM",
+        "HRV",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KNA",
+        "LBN",
+        "LBY",
+        "MAR",
+        "MDA",
+        "MEX",
+        "MKD",
+        "MNE",
+        "MNG",
+        "MUS",
+        "MYS",
+        "NAM",
+        "NRU",
+        "PAN",
+        "PER",
+        "PHL",
+        "PLW",
+        "POL",
+        "PRY",
+        "ROU",
+        "RUS",
+        "SLV",
+        "SRB",
+        "SUR",
+        "SWZ",
+        "SYC",
+        "THA",
+        "TKM",
+        "TTO",
+        "TUN",
+        "TUR",
+        "UKR",
+        "URY",
+        "VEN",
+        "VNM",
+        "ZAF"
+      ]
+    },
+    "IBT": {
+      "name": "IDA & IBRD total",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "ATG",
+        "AZE",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BTN",
+        "BWA",
+        "CAF",
+        "CHL",
+        "CHN",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COL",
+        "COM",
+        "CPV",
+        "CRI",
+        "DJI",
+        "DMA",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "ERI",
+        "ETH",
+        "FJI",
+        "FSM",
+        "GAB",
+        "GEO",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "GUY",
+        "HND",
+        "HRV",
+        "HTI",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "KNA",
+        "LAO",
+        "LBN",
+        "LBR",
+        "LBY",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MAR",
+        "MDA",
+        "MDG",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MLI",
+        "MMR",
+        "MNE",
+        "MNG",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "MYS",
+        "NAM",
+        "NER",
+        "NGA",
+        "NIC",
+        "NPL",
+        "NRU",
+        "PAK",
+        "PAN",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "POL",
+        "PRY",
+        "ROU",
+        "RUS",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLB",
+        "SLE",
+        "SLV",
+        "SOM",
+        "SRB",
+        "SSD",
+        "STP",
+        "SUR",
+        "SWZ",
+        "SYC",
+        "SYR",
+        "TCD",
+        "TGO",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TON",
+        "TTO",
+        "TUN",
+        "TUR",
+        "TUV",
+        "TZA",
+        "UGA",
+        "UKR",
+        "URY",
+        "UZB",
+        "VCT",
+        "VEN",
+        "VNM",
+        "VUT",
+        "WSM",
+        "XKX",
+        "YEM",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "IDA": {
+      "name": "IDA total",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "BTN",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "DMA",
+        "ERI",
+        "ETH",
+        "FJI",
+        "FSM",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GRD",
+        "GUY",
+        "HND",
+        "HTI",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBR",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MDG",
+        "MDV",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PNG",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLB",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TGO",
+        "TJK",
+        "TLS",
+        "TON",
+        "TUV",
+        "TZA",
+        "UGA",
+        "UZB",
+        "VCT",
+        "VUT",
+        "WSM",
+        "XKX",
+        "YEM",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "IDB": {
+      "name": "IDA blend",
+      "type": "LENDING",
+      "countries": [
+        "CMR",
+        "COG",
+        "CPV",
+        "DMA",
+        "FJI",
+        "GRD",
+        "KEN",
+        "LCA",
+        "NGA",
+        "PAK",
+        "PNG",
+        "TLS",
+        "UZB",
+        "VCT",
+        "ZWE"
+      ]
+    },
+    "IDX": {
+      "name": "IDA only",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "BTN",
+        "CAF",
+        "CIV",
+        "COD",
+        "COM",
+        "DJI",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GUY",
+        "HND",
+        "HTI",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBR",
+        "LKA",
+        "LSO",
+        "MDG",
+        "MDV",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NIC",
+        "NPL",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLB",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TGO",
+        "TJK",
+        "TON",
+        "TUV",
+        "TZA",
+        "UGA",
+        "VUT",
+        "WSM",
+        "XKX",
+        "YEM",
+        "ZMB"
+      ]
+    },
+    "IFS": {
+      "name": "IDA & IBRD countries classified as fragile situations",
+      "type": "LENDING",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "IRQ",
+        "KIR",
+        "LBN",
+        "LBY",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "UKR",
+        "VEN",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "HIC": {
+      "name": "High income",
+      "type": "INCOME",
+      "countries": [
+        "ABW",
+        "AND",
+        "ARE",
+        "ASM",
+        "ATG",
+        "AUS",
+        "AUT",
+        "BEL",
+        "BHR",
+        "BHS",
+        "BMU",
+        "BRB",
+        "BRN",
+        "CAN",
+        "CHE",
+        "CHI",
+        "CHL",
+        "CUW",
+        "CYM",
+        "CYP",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "FRO",
+        "GBR",
+        "GIB",
+        "GRC",
+        "GRL",
+        "GUM",
+        "GUY",
+        "HKG",
+        "HRV",
+        "HUN",
+        "IMN",
+        "IRL",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JPN",
+        "KNA",
+        "KOR",
+        "KWT",
+        "LIE",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MAC",
+        "MAF",
+        "MCO",
+        "MLT",
+        "MNP",
+        "NCL",
+        "NLD",
+        "NOR",
+        "NRU",
+        "NZL",
+        "OMN",
+        "PAN",
+        "POL",
+        "PRI",
+        "PRT",
+        "PYF",
+        "QAT",
+        "ROU",
+        "SAU",
+        "SGP",
+        "SMR",
+        "SVK",
+        "SVN",
+        "SWE",
+        "SXM",
+        "SYC",
+        "TCA",
+        "TTO",
+        "TWN",
+        "URY",
+        "USA",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "LIC": {
+      "name": "Low income",
+      "type": "INCOME",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "COD",
+        "ERI",
+        "ETH",
+        "GMB",
+        "GNB",
+        "LBR",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MWI",
+        "NER",
+        "PRK",
+        "RWA",
+        "SDN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "SYR",
+        "TCD",
+        "TGO",
+        "UGA",
+        "YEM"
+      ]
+    },
+    "LMC": {
+      "name": "Lower middle income",
+      "type": "INCOME",
+      "countries": [
+        "AGO",
+        "BEN",
+        "BGD",
+        "BOL",
+        "BTN",
+        "CIV",
+        "CMR",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "DZA",
+        "EGY",
+        "FSM",
+        "GHA",
+        "GIN",
+        "HND",
+        "HTI",
+        "IND",
+        "IRN",
+        "JOR",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBN",
+        "LKA",
+        "LSO",
+        "MAR",
+        "MMR",
+        "MNG",
+        "MRT",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PHL",
+        "PNG",
+        "SEN",
+        "SLB",
+        "STP",
+        "SWZ",
+        "TJK",
+        "TLS",
+        "TUN",
+        "TZA",
+        "UKR",
+        "UZB",
+        "VNM",
+        "VUT",
+        "WSM",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "LMY": {
+      "name": "Low & middle income",
+      "type": "INCOME",
+      "countries": [
+        "AFG",
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "AZE",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BTN",
+        "BWA",
+        "CAF",
+        "CHN",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COL",
+        "COM",
+        "CPV",
+        "CRI",
+        "CUB",
+        "DJI",
+        "DMA",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "ERI",
+        "ETH",
+        "FJI",
+        "FSM",
+        "GAB",
+        "GEO",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "HND",
+        "HTI",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBN",
+        "LBR",
+        "LBY",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MAR",
+        "MDA",
+        "MDG",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MLI",
+        "MMR",
+        "MNE",
+        "MNG",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "MYS",
+        "NAM",
+        "NER",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "PRK",
+        "PRY",
+        "PSE",
+        "RUS",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLB",
+        "SLE",
+        "SLV",
+        "SOM",
+        "SRB",
+        "SSD",
+        "STP",
+        "SUR",
+        "SWZ",
+        "SYR",
+        "TCD",
+        "TGO",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TON",
+        "TUN",
+        "TUR",
+        "TUV",
+        "TZA",
+        "UGA",
+        "UKR",
+        "UZB",
+        "VCT",
+        "VNM",
+        "VUT",
+        "WSM",
+        "XKX",
+        "YEM",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "MIC": {
+      "name": "Middle income",
+      "type": "INCOME",
+      "countries": [
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "AZE",
+        "BEN",
+        "BGD",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BTN",
+        "BWA",
+        "CHN",
+        "CIV",
+        "CMR",
+        "COG",
+        "COL",
+        "COM",
+        "CPV",
+        "CRI",
+        "CUB",
+        "DJI",
+        "DMA",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "FJI",
+        "FSM",
+        "GAB",
+        "GEO",
+        "GHA",
+        "GIN",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "HND",
+        "HTI",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBN",
+        "LBY",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MAR",
+        "MDA",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MMR",
+        "MNE",
+        "MNG",
+        "MRT",
+        "MUS",
+        "MYS",
+        "NAM",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "PRY",
+        "PSE",
+        "RUS",
+        "SEN",
+        "SLB",
+        "SLV",
+        "SRB",
+        "STP",
+        "SUR",
+        "SWZ",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TON",
+        "TUN",
+        "TUR",
+        "TUV",
+        "TZA",
+        "UKR",
+        "UZB",
+        "VCT",
+        "VNM",
+        "VUT",
+        "WSM",
+        "XKX",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "MIX": {
+      "name": "Middle income, excluding China & India",
+      "type": "INCOME",
+      "countries": [
+        "AGO",
+        "ALB",
+        "ARG",
+        "ARM",
+        "AZE",
+        "BEN",
+        "BGD",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BOL",
+        "BRA",
+        "BTN",
+        "BWA",
+        "CIV",
+        "CMR",
+        "COG",
+        "COL",
+        "COM",
+        "CPV",
+        "CRI",
+        "CUB",
+        "DJI",
+        "DMA",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "FJI",
+        "FSM",
+        "GAB",
+        "GEO",
+        "GHA",
+        "GIN",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "HND",
+        "HTI",
+        "IDN",
+        "IRN",
+        "IRQ",
+        "JAM",
+        "JOR",
+        "KAZ",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBN",
+        "LBY",
+        "LCA",
+        "LKA",
+        "LSO",
+        "MAR",
+        "MDA",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MMR",
+        "MNE",
+        "MNG",
+        "MRT",
+        "MUS",
+        "MYS",
+        "NAM",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PER",
+        "PHL",
+        "PLW",
+        "PNG",
+        "PRY",
+        "PSE",
+        "RUS",
+        "SEN",
+        "SLB",
+        "SLV",
+        "SRB",
+        "STP",
+        "SUR",
+        "SWZ",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TON",
+        "TUN",
+        "TUR",
+        "TUV",
+        "TZA",
+        "UKR",
+        "UZB",
+        "VCT",
+        "VNM",
+        "VUT",
+        "WSM",
+        "XKX",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "UMC": {
+      "name": "Upper middle income",
+      "type": "INCOME",
+      "countries": [
+        "ALB",
+        "ARG",
+        "ARM",
+        "AZE",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BLZ",
+        "BRA",
+        "BWA",
+        "CHN",
+        "COL",
+        "CRI",
+        "CUB",
+        "DMA",
+        "DOM",
+        "ECU",
+        "FJI",
+        "GAB",
+        "GEO",
+        "GNQ",
+        "GRD",
+        "GTM",
+        "IDN",
+        "IRQ",
+        "JAM",
+        "KAZ",
+        "LBY",
+        "LCA",
+        "MDA",
+        "MDV",
+        "MEX",
+        "MHL",
+        "MKD",
+        "MNE",
+        "MUS",
+        "MYS",
+        "NAM",
+        "PER",
+        "PLW",
+        "PRY",
+        "PSE",
+        "RUS",
+        "SLV",
+        "SRB",
+        "SUR",
+        "THA",
+        "TKM",
+        "TON",
+        "TUR",
+        "TUV",
+        "VCT",
+        "XKX",
+        "ZAF"
+      ]
+    },
+    "CEB": {
+      "name": "Central Europe and the Baltics",
+      "type": "OTHER",
+      "countries": [
+        "BGR",
+        "CZE",
+        "EST",
+        "HRV",
+        "HUN",
+        "LTU",
+        "LVA",
+        "POL",
+        "ROU",
+        "SVK",
+        "SVN"
+      ]
+    },
+    "CSS": {
+      "name": "Caribbean small states",
+      "type": "OTHER",
+      "countries": [
+        "ATG",
+        "BHS",
+        "BLZ",
+        "BRB",
+        "DMA",
+        "GRD",
+        "GUY",
+        "JAM",
+        "KNA",
+        "LCA",
+        "SUR",
+        "TTO",
+        "VCT"
+      ]
+    },
+    "DAC": {
+      "name": "Development Assistance Committee members",
+      "type": "OTHER",
+      "countries": [
+        "AUS",
+        "AUT",
+        "BEL",
+        "CAN",
+        "CHE",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "FIN",
+        "FRA",
+        "GBR",
+        "GRC",
+        "HUN",
+        "IRL",
+        "ISL",
+        "ITA",
+        "JPN",
+        "KOR",
+        "LTU",
+        "LUX",
+        "NLD",
+        "NOR",
+        "NZL",
+        "POL",
+        "PRT",
+        "SVK",
+        "SVN",
+        "SWE",
+        "USA"
+      ]
+    },
+    "EAR": {
+      "name": "Early-demographic dividend",
+      "type": "OTHER",
+      "countries": [
+        "ARG",
+        "BGD",
+        "BHR",
+        "BLZ",
+        "BOL",
+        "BTN",
+        "BWA",
+        "CPV",
+        "DJI",
+        "DOM",
+        "DZA",
+        "ECU",
+        "EGY",
+        "ETH",
+        "FSM",
+        "GAB",
+        "GHA",
+        "GRD",
+        "GTM",
+        "HND",
+        "HTI",
+        "IDN",
+        "IND",
+        "IRN",
+        "ISR",
+        "JOR",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBY",
+        "LSO",
+        "MDV",
+        "MEX",
+        "MMR",
+        "NAM",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PAN",
+        "PER",
+        "PHL",
+        "PNG",
+        "PRY",
+        "PSE",
+        "RWA",
+        "SAU",
+        "SLB",
+        "SLV",
+        "SUR",
+        "SWZ",
+        "SYR",
+        "TJK",
+        "TKM",
+        "TON",
+        "TUR",
+        "UZB",
+        "VEN",
+        "VUT",
+        "WSM",
+        "YEM",
+        "ZAF",
+        "ZWE"
+      ]
+    },
+    "EMU": {
+      "name": "Euro area",
+      "type": "OTHER",
+      "countries": [
+        "AUT",
+        "BEL",
+        "CYP",
+        "DEU",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "GRC",
+        "HRV",
+        "IRL",
+        "ITA",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MLT",
+        "NLD",
+        "PRT",
+        "SVK",
+        "SVN"
+      ]
+    },
+    "EUU": {
+      "name": "European Union",
+      "type": "OTHER",
+      "countries": [
+        "AUT",
+        "BEL",
+        "BGR",
+        "CYP",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "GRC",
+        "HRV",
+        "HUN",
+        "IRL",
+        "ITA",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MLT",
+        "NLD",
+        "POL",
+        "PRT",
+        "ROU",
+        "SVK",
+        "SVN",
+        "SWE"
+      ]
+    },
+    "FCS": {
+      "name": "Fragile and conflict affected situations",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BFA",
+        "CAF",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GNB",
+        "HTI",
+        "IRQ",
+        "KIR",
+        "LBN",
+        "LBY",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "NER",
+        "NGA",
+        "PNG",
+        "PSE",
+        "SDN",
+        "SLB",
+        "SOM",
+        "SSD",
+        "STP",
+        "SYR",
+        "TCD",
+        "TLS",
+        "TUV",
+        "UKR",
+        "VEN",
+        "XKX",
+        "YEM",
+        "ZWE"
+      ]
+    },
+    "FTI": {
+      "name": "Global Partnership for Education",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "ALB",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "BTN",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "DMA",
+        "ERI",
+        "ETH",
+        "FSM",
+        "GEO",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GRD",
+        "GUY",
+        "HND",
+        "HTI",
+        "KEN",
+        "KGZ",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBR",
+        "LCA",
+        "LSO",
+        "MDA",
+        "MDG",
+        "MDV",
+        "MHL",
+        "MLI",
+        "MMR",
+        "MNG",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NGA",
+        "NIC",
+        "NPL",
+        "PAK",
+        "PNG",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "TCD",
+        "TGO",
+        "TJK",
+        "TLS",
+        "TZA",
+        "UGA",
+        "UZB",
+        "VCT",
+        "VNM",
+        "VUT",
+        "YEM",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "GCC": {
+      "name": "Gulf Cooperation Council",
+      "type": "OTHER",
+      "countries": [
+        "ARE",
+        "BHR",
+        "KWT",
+        "OMN",
+        "QAT",
+        "SAU"
+      ]
+    },
+    "HPC": {
+      "name": "Heavily indebted poor countries (HIPC)",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BOL",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "ETH",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GUY",
+        "HND",
+        "HTI",
+        "LBR",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NIC",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "STP",
+        "TCD",
+        "TGO",
+        "TZA",
+        "UGA",
+        "ZMB"
+      ]
+    },
+    "LDC": {
+      "name": "Least developed countries: UN classification",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "AGO",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BGD",
+        "CAF",
+        "COD",
+        "COM",
+        "DJI",
+        "ERI",
+        "ETH",
+        "GIN",
+        "GMB",
+        "GNB",
+        "HTI",
+        "KHM",
+        "KIR",
+        "LAO",
+        "LBR",
+        "LSO",
+        "MDG",
+        "MLI",
+        "MMR",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NPL",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SLB",
+        "SLE",
+        "SOM",
+        "SSD",
+        "TCD",
+        "TGO",
+        "TLS",
+        "TUV",
+        "TZA",
+        "UGA",
+        "YEM",
+        "ZMB"
+      ]
+    },
+    "LLC": {
+      "name": "Landlocked developing countries: UN classification",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "ARM",
+        "AZE",
+        "BDI",
+        "BFA",
+        "BOL",
+        "BTN",
+        "BWA",
+        "CAF",
+        "ETH",
+        "KAZ",
+        "KGZ",
+        "LAO",
+        "LSO",
+        "MDA",
+        "MKD",
+        "MLI",
+        "MNG",
+        "MWI",
+        "NER",
+        "NPL",
+        "PRY",
+        "RWA",
+        "SSD",
+        "SWZ",
+        "TCD",
+        "TJK",
+        "TKM",
+        "UGA",
+        "UZB",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "LTE": {
+      "name": "Late-demographic dividend",
+      "type": "OTHER",
+      "countries": [
+        "ABW",
+        "ALB",
+        "ARE",
+        "ARM",
+        "AZE",
+        "BHS",
+        "BRA",
+        "BRN",
+        "CHL",
+        "CHN",
+        "COL",
+        "CRI",
+        "CYP",
+        "EST",
+        "FJI",
+        "GEO",
+        "GUM",
+        "GUY",
+        "IRL",
+        "ISL",
+        "JAM",
+        "KAZ",
+        "KGZ",
+        "KWT",
+        "LBN",
+        "LCA",
+        "LKA",
+        "LVA",
+        "MAR",
+        "MDA",
+        "MKD",
+        "MNE",
+        "MNG",
+        "MUS",
+        "MYS",
+        "NCL",
+        "OMN",
+        "POL",
+        "PRI",
+        "PRK",
+        "PYF",
+        "QAT",
+        "ROU",
+        "RUS",
+        "SRB",
+        "SVK",
+        "SYC",
+        "THA",
+        "TTO",
+        "TUN",
+        "URY",
+        "VCT",
+        "VIR",
+        "VNM"
+      ]
+    },
+    "NOC": {
+      "name": "High income: non OECD",
+      "type": "OTHER",
+      "countries": [
+        "ABW",
+        "AND",
+        "ARE",
+        "ASM",
+        "ATG",
+        "BHR",
+        "BHS",
+        "BMU",
+        "BRB",
+        "BRN",
+        "CHI",
+        "CUW",
+        "CYM",
+        "CYP",
+        "FRO",
+        "GIB",
+        "GRL",
+        "GUM",
+        "GUY",
+        "HKG",
+        "HRV",
+        "IMN",
+        "KNA",
+        "KWT",
+        "LIE",
+        "MAC",
+        "MAF",
+        "MCO",
+        "MLT",
+        "MNP",
+        "NCL",
+        "NRU",
+        "OMN",
+        "PAN",
+        "PRI",
+        "PYF",
+        "QAT",
+        "ROU",
+        "SAU",
+        "SGP",
+        "SMR",
+        "SXM",
+        "SYC",
+        "TCA",
+        "TTO",
+        "TWN",
+        "URY",
+        "VGB",
+        "VIR"
+      ]
+    },
+    "OEC": {
+      "name": "High income: OECD",
+      "type": "OTHER",
+      "countries": [
+        "AUS",
+        "AUT",
+        "BEL",
+        "CAN",
+        "CHE",
+        "CHL",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "GBR",
+        "GRC",
+        "HUN",
+        "IRL",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JPN",
+        "KOR",
+        "LTU",
+        "LUX",
+        "LVA",
+        "NLD",
+        "NOR",
+        "NZL",
+        "POL",
+        "PRT",
+        "SVK",
+        "SVN",
+        "SWE",
+        "USA"
+      ]
+    },
+    "OED": {
+      "name": "OECD members",
+      "type": "OTHER",
+      "countries": [
+        "AUS",
+        "AUT",
+        "BEL",
+        "CAN",
+        "CHE",
+        "CHL",
+        "COL",
+        "CRI",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "GBR",
+        "GRC",
+        "HUN",
+        "IRL",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JPN",
+        "KOR",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MEX",
+        "NLD",
+        "NOR",
+        "NZL",
+        "POL",
+        "PRT",
+        "SVK",
+        "SVN",
+        "SWE",
+        "TUR",
+        "USA"
+      ]
+    },
+    "OSS": {
+      "name": "Other small states",
+      "type": "OTHER",
+      "countries": [
+        "BHR",
+        "BRN",
+        "BTN",
+        "BWA",
+        "COM",
+        "CPV",
+        "CYP",
+        "DJI",
+        "EST",
+        "GAB",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "ISL",
+        "LSO",
+        "MDV",
+        "MLT",
+        "MNE",
+        "MUS",
+        "NAM",
+        "QAT",
+        "SMR",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TLS"
+      ]
+    },
+    "PRE": {
+      "name": "Pre-demographic dividend",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "AGO",
+        "BDI",
+        "BEN",
+        "BFA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "ERI",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "IRQ",
+        "KEN",
+        "LBR",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MWI",
+        "NER",
+        "NGA",
+        "SDN",
+        "SEN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "TCD",
+        "TGO",
+        "TLS",
+        "TZA",
+        "UGA",
+        "ZMB"
+      ]
+    },
+    "PSS": {
+      "name": "Pacific island small states",
+      "type": "OTHER",
+      "countries": [
+        "FJI",
+        "FSM",
+        "KIR",
+        "MHL",
+        "NRU",
+        "PLW",
+        "SLB",
+        "TON",
+        "TUV",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "PST": {
+      "name": "Post-demographic dividend",
+      "type": "OTHER",
+      "countries": [
+        "ATG",
+        "AUS",
+        "AUT",
+        "BEL",
+        "BGR",
+        "BIH",
+        "BLR",
+        "BRB",
+        "CAN",
+        "CHE",
+        "CUB",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "FIN",
+        "FRA",
+        "GBR",
+        "GRC",
+        "HKG",
+        "HRV",
+        "HUN",
+        "ITA",
+        "JPN",
+        "KOR",
+        "LTU",
+        "LUX",
+        "MAC",
+        "MLT",
+        "NLD",
+        "NOR",
+        "NZL",
+        "PRT",
+        "SGP",
+        "SVN",
+        "SWE",
+        "UKR",
+        "USA"
+      ]
+    },
+    "SDC": {
+      "name": "Southern African Development Community",
+      "type": "OTHER",
+      "countries": [
+        "AGO",
+        "BWA",
+        "COD",
+        "COM",
+        "LSO",
+        "MDG",
+        "MOZ",
+        "MUS",
+        "MWI",
+        "NAM",
+        "SWZ",
+        "SYC",
+        "TZA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "SID": {
+      "name": "Small island developing states: UN classification",
+      "type": "OTHER",
+      "countries": [
+        "ABW",
+        "AIA",
+        "ASM",
+        "ATG",
+        "BES",
+        "BHS",
+        "BLZ",
+        "BRB",
+        "COK",
+        "COM",
+        "CPV",
+        "CUB",
+        "CUW",
+        "DMA",
+        "DOM",
+        "FJI",
+        "FSM",
+        "GNB",
+        "GRD",
+        "GUM",
+        "GUY",
+        "HTI",
+        "JAM",
+        "KIR",
+        "KNA",
+        "LCA",
+        "MDV",
+        "MHL",
+        "MNP",
+        "MSR",
+        "MUS",
+        "NCL",
+        "NIU",
+        "NRU",
+        "PLW",
+        "PNG",
+        "PRI",
+        "PYF",
+        "SGP",
+        "SLB",
+        "STP",
+        "SUR",
+        "SXM",
+        "SYC",
+        "TLS",
+        "TON",
+        "TTO",
+        "TUV",
+        "VCT",
+        "VGB",
+        "VIR",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "SSB": {
+      "name": "Small states (IBRD only)",
+      "type": "OTHER",
+      "countries": [
+        "ATG",
+        "BLZ",
+        "BWA",
+        "GAB",
+        "GNQ",
+        "JAM",
+        "KNA",
+        "MNE",
+        "MUS",
+        "NAM",
+        "NRU",
+        "PLW",
+        "SUR",
+        "SWZ",
+        "SYC",
+        "TTO"
+      ]
+    },
+    "SSH": {
+      "name": "Small states (high income only)",
+      "type": "OTHER",
+      "countries": [
+        "BHR",
+        "BHS",
+        "BRB",
+        "BRN",
+        "CYP",
+        "EST",
+        "GUY",
+        "ISL",
+        "KNA",
+        "MLT",
+        "NRU",
+        "QAT",
+        "SMR",
+        "SYC",
+        "TTO"
+      ]
+    },
+    "SSI": {
+      "name": "Small states (IDA only)",
+      "type": "OTHER",
+      "countries": [
+        "BTN",
+        "COM",
+        "CPV",
+        "DJI",
+        "DMA",
+        "FJI",
+        "FSM",
+        "GMB",
+        "GNB",
+        "GRD",
+        "GUY",
+        "KIR",
+        "LCA",
+        "LSO",
+        "MDV",
+        "MHL",
+        "SLB",
+        "STP",
+        "TLS",
+        "TON",
+        "TUV",
+        "VCT",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "SST": {
+      "name": "Small states",
+      "type": "OTHER",
+      "countries": [
+        "ATG",
+        "BHR",
+        "BHS",
+        "BLZ",
+        "BRB",
+        "BRN",
+        "BTN",
+        "BWA",
+        "COM",
+        "CPV",
+        "CYP",
+        "DJI",
+        "DMA",
+        "EST",
+        "FJI",
+        "FSM",
+        "GAB",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "GRD",
+        "GUY",
+        "ISL",
+        "JAM",
+        "KIR",
+        "KNA",
+        "LCA",
+        "LSO",
+        "MDV",
+        "MHL",
+        "MLT",
+        "MNE",
+        "MUS",
+        "NAM",
+        "NRU",
+        "PLW",
+        "QAT",
+        "SLB",
+        "SMR",
+        "STP",
+        "SUR",
+        "SWZ",
+        "SYC",
+        "TLS",
+        "TON",
+        "TTO",
+        "TUV",
+        "VCT",
+        "VUT",
+        "WSM"
+      ]
+    },
+    "WA1": {
+      "name": "ESCWA: Gulf Cooperation Council (GCC)",
+      "type": "OTHER",
+      "countries": [
+        "ARE",
+        "BHR",
+        "KWT",
+        "OMN",
+        "QAT",
+        "SAU"
+      ]
+    },
+    "WA2": {
+      "name": "ESCWA: Mashreq subregion",
+      "type": "OTHER",
+      "countries": [
+        "EGY",
+        "IRQ",
+        "JOR",
+        "LBN",
+        "PSE",
+        "SYR"
+      ]
+    },
+    "WA3": {
+      "name": "ESCWA: Maghreb subregion",
+      "type": "OTHER",
+      "countries": [
+        "DZA",
+        "LBY",
+        "MAR",
+        "TUN"
+      ]
+    },
+    "WA4": {
+      "name": "ESCWA: Arab LDCs subregion",
+      "type": "OTHER",
+      "countries": [
+        "COM",
+        "DJI",
+        "MRT",
+        "SDN",
+        "SOM",
+        "YEM"
+      ]
+    },
+    "DM": {
+      "name": "Developed markets",
+      "type": "OTHER",
+      "countries": [
+        "AUS",
+        "AUT",
+        "BEL",
+        "CAN",
+        "CHE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "FIN",
+        "FRA",
+        "GBR",
+        "GRC",
+        "IRL",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JPN",
+        "KOR",
+        "LUX",
+        "NLD",
+        "NOR",
+        "NZL",
+        "PRT",
+        "QAT",
+        "SGP",
+        "SWE",
+        "USA"
+      ]
+    },
+    "G_COA": {
+      "name": "Coastal Countries",
+      "type": "OTHER",
+      "countries": [
+        "AGO",
+        "ALB",
+        "ARE",
+        "ARG",
+        "AUS",
+        "BEL",
+        "BEN",
+        "BGD",
+        "BGR",
+        "BHR",
+        "BIH",
+        "BLZ",
+        "BRA",
+        "BRN",
+        "CAN",
+        "CHL",
+        "CHN",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COL",
+        "CRI",
+        "CUB",
+        "CYP",
+        "DEU",
+        "DJI",
+        "DNK",
+        "DZA",
+        "ECU",
+        "EGY",
+        "ERI",
+        "ESH",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "GAB",
+        "GBR",
+        "GEO",
+        "GHA",
+        "GIB",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "GRC",
+        "GRD",
+        "GRL",
+        "GTM",
+        "GUF",
+        "GUY",
+        "HKG",
+        "HND",
+        "HRV",
+        "IDN",
+        "IND",
+        "IRL",
+        "IRN",
+        "IRQ",
+        "ISL",
+        "ISR",
+        "ITA",
+        "JOR",
+        "JPN",
+        "KEN",
+        "KHM",
+        "KOR",
+        "KWT",
+        "LBN",
+        "LBR",
+        "LBY",
+        "LKA",
+        "LTU",
+        "LVA",
+        "MAC",
+        "MAR",
+        "MCO",
+        "MDG",
+        "MEX",
+        "MMR",
+        "MNE",
+        "MOZ",
+        "MRT",
+        "MYS",
+        "NAM",
+        "NGA",
+        "NIC",
+        "NLD",
+        "NOR",
+        "NZL",
+        "OMN",
+        "PAK",
+        "PAN",
+        "PER",
+        "PHL",
+        "PNG",
+        "POL",
+        "PRK",
+        "PRT",
+        "PSE",
+        "QAT",
+        "ROU",
+        "RUS",
+        "SAU",
+        "SDN",
+        "SEN",
+        "SGP",
+        "SLE",
+        "SLV",
+        "SOM",
+        "SUR",
+        "SVN",
+        "SWE",
+        "SYR",
+        "TGO",
+        "THA",
+        "TUN",
+        "TUR",
+        "TWN",
+        "TZA",
+        "UKR",
+        "URY",
+        "USA",
+        "VEN",
+        "VNM",
+        "YEM",
+        "ZAF"
+      ]
+    },
+    "G_LLD": {
+      "name": "Landlocked Countries",
+      "type": "OTHER",
+      "countries": [
+        "AFG",
+        "AND",
+        "ARM",
+        "AUT",
+        "AZE",
+        "BDI",
+        "BFA",
+        "BLR",
+        "BOL",
+        "BTN",
+        "BWA",
+        "CAF",
+        "CHE",
+        "CZE",
+        "ETH",
+        "HUN",
+        "KAZ",
+        "KGZ",
+        "LAO",
+        "LIE",
+        "LSO",
+        "LUX",
+        "MDA",
+        "MKD",
+        "MLI",
+        "MNG",
+        "MWI",
+        "NER",
+        "NPL",
+        "PRY",
+        "RWA",
+        "SMR",
+        "SRB",
+        "SSD",
+        "SVK",
+        "SWZ",
+        "TCD",
+        "TJK",
+        "TKM",
+        "UGA",
+        "UZB",
+        "VAT",
+        "XKX",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "G_SIC": {
+      "name": "Small Island Countries",
+      "type": "OTHER",
+      "countries": [
+        "ABW",
+        "AIA",
+        "ALA",
+        "ANT",
+        "ASM",
+        "ATF",
+        "ATG",
+        "BES",
+        "BHS",
+        "BLM",
+        "BMU",
+        "BRB",
+        "BVT",
+        "CCK",
+        "COK",
+        "COM",
+        "CPV",
+        "CUW",
+        "CXR",
+        "CYM",
+        "DMA",
+        "DOM",
+        "FJI",
+        "FLK",
+        "FRO",
+        "FSM",
+        "GGY",
+        "GLP",
+        "GUM",
+        "HMD",
+        "HTI",
+        "IMN",
+        "IOT",
+        "JAM",
+        "JEY",
+        "KIR",
+        "KNA",
+        "LCA",
+        "MAF",
+        "MDV",
+        "MHL",
+        "MLT",
+        "MNP",
+        "MSR",
+        "MTQ",
+        "MUS",
+        "MYT",
+        "NCL",
+        "NFK",
+        "NIU",
+        "NRU",
+        "PCN",
+        "PLW",
+        "PRI",
+        "PYF",
+        "REU",
+        "SGS",
+        "SHN",
+        "SJM",
+        "SLB",
+        "SPM",
+        "STP",
+        "SXM",
+        "SYC",
+        "TCA",
+        "TKL",
+        "TLS",
+        "TON",
+        "TTO",
+        "TUV",
+        "UMI",
+        "VCT",
+        "VGB",
+        "VIR",
+        "VUT",
+        "WLF",
+        "WSM"
+      ]
+    },
+    "002": {
+      "name": "Africa",
+      "type": "CONTINENT",
+      "countries": [
+        "AGO",
+        "ATF",
+        "BDI",
+        "BEN",
+        "BFA",
+        "BWA",
+        "CAF",
+        "CIV",
+        "CMR",
+        "COD",
+        "COG",
+        "COM",
+        "CPV",
+        "DJI",
+        "DZA",
+        "EGY",
+        "ERI",
+        "ESH",
+        "ETH",
+        "GAB",
+        "GHA",
+        "GIN",
+        "GMB",
+        "GNB",
+        "GNQ",
+        "IOT",
+        "KEN",
+        "LBR",
+        "LBY",
+        "LSO",
+        "MAR",
+        "MDG",
+        "MLI",
+        "MOZ",
+        "MRT",
+        "MUS",
+        "MWI",
+        "MYT",
+        "NAM",
+        "NER",
+        "NGA",
+        "REU",
+        "RWA",
+        "SDN",
+        "SEN",
+        "SHN",
+        "SLE",
+        "SOM",
+        "SSD",
+        "STP",
+        "SWZ",
+        "SYC",
+        "TCD",
+        "TGO",
+        "TUN",
+        "TZA",
+        "UGA",
+        "ZAF",
+        "ZMB",
+        "ZWE"
+      ]
+    },
+    "150": {
+      "name": "Europe",
+      "type": "CONTINENT",
+      "countries": [
+        "ALA",
+        "ALB",
+        "AND",
+        "AUT",
+        "BEL",
+        "BGR",
+        "BIH",
+        "BLR",
+        "CHE",
+        "CZE",
+        "DEU",
+        "DNK",
+        "ESP",
+        "EST",
+        "FIN",
+        "FRA",
+        "FRO",
+        "GBR",
+        "GGY",
+        "GIB",
+        "GRC",
+        "HRV",
+        "HUN",
+        "IMN",
+        "IRL",
+        "ISL",
+        "ITA",
+        "JEY",
+        "LIE",
+        "LTU",
+        "LUX",
+        "LVA",
+        "MCO",
+        "MDA",
+        "MKD",
+        "MLT",
+        "MNE",
+        "NLD",
+        "NOR",
+        "POL",
+        "PRT",
+        "ROU",
+        "RUS",
+        "SJM",
+        "SMR",
+        "SRB",
+        "SVK",
+        "SVN",
+        "SWE",
+        "UKR",
+        "VAT",
+        "XKX"
+      ]
+    },
+    "142": {
+      "name": "Asia",
+      "type": "CONTINENT",
+      "countries": [
+        "AFG",
+        "ARE",
+        "ARM",
+        "AZE",
+        "BGD",
+        "BHR",
+        "BRN",
+        "BTN",
+        "CHN",
+        "CYP",
+        "GEO",
+        "HKG",
+        "IDN",
+        "IND",
+        "IRN",
+        "IRQ",
+        "ISR",
+        "JOR",
+        "JPN",
+        "KAZ",
+        "KGZ",
+        "KHM",
+        "KOR",
+        "KWT",
+        "LAO",
+        "LBN",
+        "LKA",
+        "MAC",
+        "MDV",
+        "MMR",
+        "MNG",
+        "MYS",
+        "NPL",
+        "OMN",
+        "PAK",
+        "PHL",
+        "PRK",
+        "PSE",
+        "QAT",
+        "SAU",
+        "SGP",
+        "SYR",
+        "THA",
+        "TJK",
+        "TKM",
+        "TLS",
+        "TUR",
+        "UZB",
+        "VNM",
+        "YEM"
+      ]
+    },
+    "005": {
+      "name": "South America",
+      "type": "CONTINENT",
+      "countries": [
+        "ARG",
+        "BOL",
+        "BRA",
+        "BVT",
+        "CHL",
+        "COL",
+        "ECU",
+        "FLK",
+        "GUF",
+        "GUY",
+        "PER",
+        "PRY",
+        "SGS",
+        "SUR",
+        "URY",
+        "VEN"
+      ]
+    },
+    "009": {
+      "name": "Oceania",
+      "type": "CONTINENT",
+      "countries": [
+        "ASM",
+        "AUS",
+        "CCK",
+        "COK",
+        "CXR",
+        "FJI",
+        "FSM",
+        "GUM",
+        "HMD",
+        "KIR",
+        "MHL",
+        "MNP",
+        "NCL",
+        "NFK",
+        "NIU",
+        "NRU",
+        "NZL",
+        "PCN",
+        "PLW",
+        "PNG",
+        "PYF",
+        "SLB",
+        "TKL",
+        "TON",
+        "TUV",
+        "UMI",
+        "VUT",
+        "WLF",
+        "WSM"
+      ]
+    }
+  },
+  "all_countries": [
+    "ABW",
+    "AFG",
+    "AGO",
+    "AIA",
+    "ALA",
+    "ALB",
+    "AND",
+    "ANT",
+    "ARE",
+    "ARG",
+    "ARM",
+    "ASM",
+    "ATF",
+    "ATG",
+    "AUS",
+    "AUT",
+    "AZE",
+    "BDI",
+    "BEL",
+    "BEN",
+    "BES",
+    "BFA",
+    "BGD",
+    "BGR",
+    "BHR",
+    "BHS",
+    "BIH",
+    "BLM",
+    "BLR",
+    "BLZ",
+    "BMU",
+    "BOL",
+    "BRA",
+    "BRB",
+    "BRN",
+    "BTN",
+    "BVT",
+    "BWA",
+    "CAF",
+    "CAN",
+    "CCK",
+    "CHE",
+    "CHI",
+    "CHL",
+    "CHN",
+    "CIV",
+    "CMR",
+    "COD",
+    "COG",
+    "COK",
+    "COL",
+    "COM",
+    "CPV",
+    "CRI",
+    "CUB",
+    "CUW",
+    "CXR",
+    "CYM",
+    "CYP",
+    "CZE",
+    "DEU",
+    "DJI",
+    "DMA",
+    "DNK",
+    "DOM",
+    "DZA",
+    "ECU",
+    "EGY",
+    "ERI",
+    "ESH",
+    "ESP",
+    "EST",
+    "ETH",
+    "FIN",
+    "FJI",
+    "FLK",
+    "FRA",
+    "FRO",
+    "FSM",
+    "GAB",
+    "GBR",
+    "GEO",
+    "GGY",
+    "GHA",
+    "GIB",
+    "GIN",
+    "GLP",
+    "GMB",
+    "GNB",
+    "GNQ",
+    "GRC",
+    "GRD",
+    "GRL",
+    "GTM",
+    "GUF",
+    "GUM",
+    "GUY",
+    "HKG",
+    "HMD",
+    "HND",
+    "HRV",
+    "HTI",
+    "HUN",
+    "IDN",
+    "IMN",
+    "IND",
+    "IOT",
+    "IRL",
+    "IRN",
+    "IRQ",
+    "ISL",
+    "ISR",
+    "ITA",
+    "JAM",
+    "JEY",
+    "JOR",
+    "JPN",
+    "KAZ",
+    "KEN",
+    "KGZ",
+    "KHM",
+    "KIR",
+    "KNA",
+    "KOR",
+    "KWT",
+    "LAO",
+    "LBN",
+    "LBR",
+    "LBY",
+    "LCA",
+    "LIE",
+    "LKA",
+    "LSO",
+    "LTU",
+    "LUX",
+    "LVA",
+    "MAC",
+    "MAF",
+    "MAR",
+    "MCO",
+    "MDA",
+    "MDG",
+    "MDV",
+    "MEX",
+    "MHL",
+    "MKD",
+    "MLI",
+    "MLT",
+    "MMR",
+    "MNE",
+    "MNG",
+    "MNP",
+    "MOZ",
+    "MRT",
+    "MSR",
+    "MTQ",
+    "MUS",
+    "MWI",
+    "MYS",
+    "MYT",
+    "NAM",
+    "NCL",
+    "NER",
+    "NFK",
+    "NGA",
+    "NIC",
+    "NIU",
+    "NLD",
+    "NOR",
+    "NPL",
+    "NRU",
+    "NZL",
+    "OMN",
+    "PAK",
+    "PAN",
+    "PCN",
+    "PER",
+    "PHL",
+    "PLW",
+    "PNG",
+    "POL",
+    "PRI",
+    "PRK",
+    "PRT",
+    "PRY",
+    "PSE",
+    "PYF",
+    "QAT",
+    "REU",
+    "ROU",
+    "RUS",
+    "RWA",
+    "SAU",
+    "SDN",
+    "SEN",
+    "SGP",
+    "SGS",
+    "SHN",
+    "SJM",
+    "SLB",
+    "SLE",
+    "SLV",
+    "SMR",
+    "SOM",
+    "SPM",
+    "SRB",
+    "SSD",
+    "STP",
+    "SUR",
+    "SVK",
+    "SVN",
+    "SWE",
+    "SWZ",
+    "SXM",
+    "SYC",
+    "SYR",
+    "TCA",
+    "TCD",
+    "TGO",
+    "THA",
+    "TJK",
+    "TKL",
+    "TKM",
+    "TLS",
+    "TON",
+    "TTO",
+    "TUN",
+    "TUR",
+    "TUV",
+    "TWN",
+    "TZA",
+    "UGA",
+    "UKR",
+    "UMI",
+    "URY",
+    "USA",
+    "UZB",
+    "VAT",
+    "VCT",
+    "VEN",
+    "VGB",
+    "VIR",
+    "VNM",
+    "VUT",
+    "WLF",
+    "WSM",
+    "XKX",
+    "YEM",
+    "ZAF",
+    "ZMB",
+    "ZWE"
+  ]
+}

src/data360/server.py

@@ -0,0 +1,374 @@
+import hashlib
+import json
+import logging
+import os
+import uuid
+
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from data360.mcp_server.resources import CORSStaticFiles
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request as StarletteRequest
+
+from data360.config import get_mcp_server_settings, setup_logging
+from data360.health import get_liveness_body, run_readiness
+from data360.http_client import aclose_shared_httpx_client
+from data360.otel_setup import (
+    configure_open_telemetry_for_server,
+    instrument_httpx_outbound,
+)
+
+_audit_logger = logging.getLogger("audit")
+_telemetry_client = None
+
+# Setup logging from configuration
+import sys
+
+_logger = logging.getLogger(__name__)
+mcp_settings = get_mcp_server_settings()
+
+# Parse port from argv, supporting both '--port 8021' and '--port=8021' forms.
+_parsed_port: int | None = None
+for _arg in sys.argv:
+    if _arg.startswith("--port="):
+        try:
+            _parsed_port = int(_arg.split("=", 1)[1])
+        except ValueError:
+            logging.warning("Could not parse port from argv argument '%s'; using default.", _arg)
+        break
+    if _arg == "--port":
+        _idx = sys.argv.index(_arg)
+        try:
+            _parsed_port = int(sys.argv[_idx + 1])
+        except (ValueError, IndexError):
+            logging.warning("Could not parse port after '--port' in argv; using default.")
+        break
+if _parsed_port is not None:
+    mcp_settings.port = _parsed_port
+
+setup_logging(
+    log_file=mcp_settings.log_file,
+    log_level=mcp_settings.log_level,
+    env=mcp_settings.env,
+    azure_connection_string=mcp_settings.azure_connection_string,
+)
+
+# Tracer export (Azure in deployed envs; optional OTLP/console when MCP_ENV=local) and httpx spans
+configure_open_telemetry_for_server(mcp_settings)
+instrument_httpx_outbound()
+
+# Import MCP after telemetry so the process uses an instrumented httpx from the first request.
+from data360.mcp_server import mcp  # noqa: E402
+
+_connection_string = mcp_settings.azure_connection_string or os.environ.get(
+    "APPLICATIONINSIGHTS_CONNECTION_STRING"
+)
+
+# Initialize OpenCensus TelemetryClient for custom events (forwarded to Splunk)
+if mcp_settings.env != "local" and _connection_string:
+    try:
+        from opencensus.ext.azure.log_exporter import (
+            AzureEventHandler,  # type: ignore[import-untyped]
+        )
+
+        # Create a dedicated logger for custom events
+        event_logger = logging.getLogger("customEvents")
+        event_logger.setLevel(logging.INFO)
+
+        # Add Azure handler that sends to customEvents table
+        azure_handler = AzureEventHandler(connection_string=_connection_string)
+        event_logger.addHandler(azure_handler)
+
+        _telemetry_client = event_logger
+    except ImportError:
+        pass
+
+
+class SecurityValidationMiddleware(BaseHTTPMiddleware):
+    """Validate MCP tool calls to prevent prompt injection and unauthorized access."""
+
+    async def dispatch(self, request: Request, call_next):
+        # Only validate MCP JSON-RPC tool calls (not health probes under /mcp/*)
+        if request.url.path in ("/mcp/health", "/mcp/ready"):
+            return await call_next(request)
+        if not request.url.path.startswith("/mcp"):
+            return await call_next(request)
+
+        try:
+            # Read and parse body
+            body_bytes = await request.body()
+            if not body_bytes:
+                return await call_next(request)
+
+            body = json.loads(body_bytes)
+            method = body.get("method", "")
+
+            # Log tools/list requests for monitoring (allowed but monitored)
+            if method == "tools/list":
+                client_ip = request.headers.get(
+                    "X-Forwarded-For",
+                    request.client.host if request.client else "unknown",
+                )
+                logging.info(f"tools/list called from IP: {client_ip}")
+
+            # Validate tools/call requests
+            if method == "tools/call":
+                from data360.mcp_server.security_validator import (  # noqa: PLC0415
+                    validate_search_arguments,
+                    validate_tool_call,
+                )
+
+                params = body.get("params", {})
+                tool_name = params.get("name", "")
+                arguments = params.get("arguments", {})
+
+                # Validate tool call
+                is_valid, error_msg = validate_tool_call(tool_name, arguments)
+                if not is_valid:
+                    logging.warning(
+                        f"Security violation: {error_msg} | Tool: {tool_name}"
+                    )
+                    return JSONResponse(
+                        status_code=403,
+                        content={
+                            "jsonrpc": "2.0",
+                            "id": body.get("id"),
+                            "error": {"code": -32001, "message": error_msg},
+                        },
+                    )
+
+                # Additional validation for all search term inputs
+                if tool_name == "data360_search_indicators":
+                    is_valid, error_msg = validate_search_arguments(arguments)
+                    if not is_valid:
+                        logging.warning(
+                            "Search query blocked: %s",
+                            str(arguments)[:200],
+                        )
+                        return JSONResponse(
+                            status_code=403,
+                            content={
+                                "jsonrpc": "2.0",
+                                "id": body.get("id"),
+                                "error": {"code": -32001, "message": error_msg},
+                            },
+                        )
+
+        except json.JSONDecodeError:
+            pass  # Let MCP handle invalid JSON
+        except Exception:
+            logging.error("Security validation error", exc_info=True)
+            # Continue on validation errors to avoid blocking legitimate requests
+
+        return await call_next(request)
+
+
+class AuditLogMiddleware(BaseHTTPMiddleware):
+    """Log structured audit entries for every MCP request."""
+
+    async def dispatch(self, request: Request, call_next):
+        # Only audit MCP JSON-RPC calls (not health probes)
+        if request.url.path in ("/mcp/health", "/mcp/ready"):
+            return await call_next(request)
+        if not request.url.path.startswith("/mcp"):
+            return await call_next(request)
+        session_id = str(uuid.uuid4())
+        requestor_id = request.headers.get(
+            "X-Forwarded-For", request.client.host if request.client else "unknown"
+        )
+        timestamp = datetime.now(UTC).isoformat()
+        # Read and restore body so downstream handlers still receive it
+        body_bytes = await request.body()
+        prompt = ""
+        prompt_hash = ""
+        try:
+            body = json.loads(body_bytes)
+            method = body.get("method", "")
+            params = body.get("params", {})
+            prompt = json.dumps(
+                {"method": method, "params": params}, separators=(",", ":")
+            )
+            prompt_hash = hashlib.sha256(prompt.encode()).hexdigest()[:16]
+        except Exception:
+            pass
+        response = await call_next(request)
+
+        properties = {
+            "session_id": session_id,
+            "requestor_id": requestor_id,
+            "timestamp": timestamp,
+            "prompt": prompt,
+            "prompt_hash": prompt_hash,
+            "status_code": str(response.status_code),
+            "path": request.url.path,
+        }
+
+        # Log to traces with custom dimensions
+        _audit_logger.info("mcp_audit", extra={"custom_dimensions": properties})
+
+        # Also log as custom event for Splunk forwarding
+        if _telemetry_client:
+            _telemetry_client.info(
+                "MCP_Request",
+                extra={
+                    "custom_dimensions": properties,
+                    "event_name": "MCP_Request",
+                },
+            )
+
+        return response
+
+
+from fastmcp import settings
+settings.stateless_http = True
+
+# NOTE: import to be able to run the server with all definitions loaded
+# path="/mcp" means the MCP endpoint lives at /mcp (no trailing slash needed)
+mcp_app = mcp.http_app(path="/mcp")
+
+
+async def health_check(request: StarletteRequest) -> JSONResponse:
+    """Liveness probe under the MCP URL prefix (GET /mcp/health)."""
+    del request
+    return JSONResponse(get_liveness_body())
+
+
+async def ready_check(request: StarletteRequest) -> JSONResponse:
+    """Readiness probe under the MCP URL prefix (GET /mcp/ready)."""
+    del request
+    status_code, body = await run_readiness()
+    return JSONResponse(content=body, status_code=status_code)
+
+
+# Starlette routes on mcp_app: paths are absolute from mount root (not nested under /mcp).
+# Use /mcp/health so probes sit beside the streamable HTTP endpoint at /mcp.
+mcp_app.add_route("/mcp/health", health_check, methods=["GET", "HEAD"])
+mcp_app.add_route("/mcp/ready", ready_check, methods=["GET", "HEAD"])
+
+
+@asynccontextmanager
+async def _lifespan_with_http_cleanup(app: FastAPI):
+    """Run MCP startup/shutdown, then close the shared httpx client."""
+    async with mcp_app.router.lifespan_context(mcp_app):
+        yield
+    await aclose_shared_httpx_client()
+
+
+# https://gofastmcp.com/deployment/http#asgi-application
+# redirect_slashes=False prevents 308 redirects between /mcp and /mcp/
+app = FastAPI(
+    title="Data360 MCP Server",
+    lifespan=_lifespan_with_http_cleanup,
+    redirect_slashes=False,
+)  # pyright: ignore[reportUnusedExpression]
+
+app.add_middleware(AuditLogMiddleware)
+# SecurityValidationMiddleware is enabled for incoming request validation.
+app.add_middleware(SecurityValidationMiddleware)
+
+from fastapi.middleware.cors import CORSMiddleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Instrument FastAPI for incoming request tracking
+if mcp_settings.env != "local" and _connection_string:
+    try:
+        from opentelemetry.instrumentation.fastapi import (
+            FastAPIInstrumentor,  # type: ignore[import-untyped]
+        )
+
+        FastAPIInstrumentor.instrument_app(app)
+    except ImportError:
+        pass
+
+
+@app.get("/")
+async def root():
+    return {
+        "service": "data360-mcp",
+        "health": "/mcp/health",
+        "ready": "/mcp/ready",
+        "mcp": "/mcp",
+    }
+
+
+
+class VizSpecRequest(BaseModel):
+    database_id: str
+    indicator_id: str
+    country_code: str | None = None
+    start_year: int | None = None
+    end_year: int | None = None
+    disaggregation_filters: dict[str, str | None] | None = None
+    chart_type: str | None = None
+    relevant_fields: list[str] | None = None
+    chart_title: str | None = None
+    series_labels: dict[str, str] | None = None
+
+
+@app.post("/api/viz-spec")
+async def get_viz_spec_endpoint(req: VizSpecRequest):
+    from data360 import visualization as data360_viz
+
+    try:
+        # Pass charts_api_url_override=None to force local static file storage,
+        # avoiding mutation of the shared @ft.cache singleton (which is a race condition
+        # under concurrent requests). The HTML app always wants local specs for direct
+        # file access; blob storage routing happens via the MCP tool path, not this endpoint.
+        res = await data360_viz.get_viz_spec(
+            database_id=req.database_id,
+            indicator_id=req.indicator_id,
+            country_code=req.country_code,
+            start_year=req.start_year,
+            end_year=req.end_year,
+            disaggregation_filters=req.disaggregation_filters,
+            chart_type=req.chart_type,
+            relevant_fields=req.relevant_fields,
+            chart_title=req.chart_title,
+            series_labels=req.series_labels,
+            charts_api_url_override=None,
+        )
+    except Exception as e:
+        return JSONResponse(status_code=500, content={"error": str(e)})
+
+    if res.get("error"):
+        return JSONResponse(status_code=400, content={"error": res.get("error")})
+
+    spec = res.get("spec")
+    if not spec:
+        return JSONResponse(status_code=500, content={"error": "Vega-Lite spec was not generated."})
+
+    return {k: v for k, v in {
+        "spec": spec,
+        "reason": res.get("reason"),
+        "strategy": res.get("strategy"),
+    }.items() if v is not None}
+
+
+
+
+if os.environ.get("PYTEST_CURRENT_TEST"):
+    static_dir = os.path.join(os.getcwd(), "static")
+else:
+    server_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.abspath(os.path.join(server_dir, "..", ".."))
+    static_dir = os.path.join(project_root, "static")
+os.makedirs(static_dir, exist_ok=True)
+app.mount("/static", CORSStaticFiles(directory=static_dir), name="static")
+# Mount MCP app at root — the path="/mcp" in http_app() handles the /mcp route
+app.mount("/", mcp_app)
+
+
+# Tools and other resources are automatically registered via imports in mcp_server/__init__.py
+# See src/data360/mcp_server/tools.py for tool definitions

src/data360/tool_contract.py

@@ -0,0 +1,20 @@
+"""Shared versioning between MCP tool JSON contracts and `@data360/tool-types` / UI packages."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+
+
+@lru_cache(maxsize=1)
+def get_tool_contract_version() -> str:
+    """Return the tool contract version (semver) shipped with this server build."""
+    raw = resources.files("data360").joinpath("tool_contract_version.json").read_text(
+        encoding="utf-8"
+    )
+    data = json.loads(raw)
+    version = data.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError("tool_contract_version.json: missing or invalid 'version'")
+    return version.strip()

src/data360/tool_contract_version.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.0.0",
+  "description": "Bump this and @data360/tool-types / UI packages when MCP tool JSON shapes change in a breaking way."
+}