# Development Indicators MCP

A provenance-first Model Context Protocol gateway for official international-development indicators.

**Hosted MCP endpoint:** `https://indicatorsmcp.impactengines.ai/mcp`

[![CI](https://github.com/lbruce-wq/development-data-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lbruce-wq/development-data-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

The project aims to let AI agents discover and query authoritative indicators across institutions such as the World Bank, UN agencies, FAO, WHO, UNICEF, ILO and the DHS Program through one consistent interface. It preserves definitions, units, dimensions, source codes and citations rather than returning uncited prose.

## Current milestone

The repository contains a working vertical slice:

- remote-capable MCP server using Streamable HTTP, with stdio support for local clients;
- source registry describing APIs, authentication and capabilities;
- normalized indicator and observation schemas;
- live World Bank, WHO GHO, UNICEF, FAOSTAT, ILOSTAT, IMF, UNSD SDG,
  UNESCO UIS, OECD and ADB adapters;
- on-demand FAOSTAT authentication with no background token refresh;
- dynamic FAOSTAT domain, country, item and element discovery;
- weighted live catalogue search with aliases, match explanations, retrieval-health signals,
  bounded provider waits and a 15-minute query cache;
- partial-failure comparisons, typed errors, native structured outputs and compact responses;
- partial-success geography resolution with structured unresolved-country errors;
- normalized ILOSTAT frequency labels and FAOSTAT dimension-ranking evidence;
- tools to resolve country names, inspect metadata and retrieve observations;
- unit tests for normalization and source behaviour.

This is a public beta, not a production statistical service. The hosted instance is provided for evaluation; you can also run or deploy your own copy.

## MCP tools

- `list_sources(topic=None)`
- `get_source_setup(source_id)`
- `search_indicators(query, source_ids=None, limit=10)`
- `get_indicator_metadata(series_ref)`
- `get_observations(series_ref, country_codes, start_year=None, end_year=None, latest_only=False, include_original=False)`
- `compare_observations(series_refs, country_codes, ...)`
- `find_microdata(query, country=None)`
- `faostat_list_domains(limit=50, cursor=0, group_code=None, status=None, include_archived=False)`
- `faostat_search_dimension(dataset, dimension, query, limit=20, cursor=0)`
- `resolve_geographies(names_or_codes)`

Series references use the form `source_id:series_code`, for example `world_bank:SP.POP.TOTL`.
Observation calls accept ISO 3166-1 alpha-3 codes such as `GHA` and `KEN`; use
`resolve_geographies` when a prompt supplies country names. Mixed batches return both
`resolved` and `unresolved` entries instead of failing the entire request.

## Local development

```powershell
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest
development-data-mcp
```

For macOS or Linux, activate the environment with `source .venv/bin/activate`.

Run the live-source smoke benchmark with:

```powershell
python -m benchmarks.run
```

The FAOSTAT check is skipped until `FAOSTAT_USER` and `FAOSTAT_PASSWORD` are
configured; all public-source checks run without credentials.

The default transport is `stdio`. To run a hosted-style HTTP endpoint:

```powershell
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "127.0.0.1"
$env:MCP_PORT = "8000"
development-data-mcp
```

The MCP endpoint is then exposed at `/mcp`. Production deployment must add HTTPS, authentication, rate limiting and audit logging at the application or gateway layer.

## Install in Codex

The hosted service uses Streamable HTTP:

```powershell
codex mcp add development-indicators --url https://indicatorsmcp.impactengines.ai/mcp
codex mcp list
```

Restart Codex after adding it, then use `/mcp` to confirm the server and its
tools are available. The same MCP configuration is shared by the Codex CLI,
IDE extension and ChatGPT desktop app on the same Codex host.

Equivalent `~/.codex/config.toml` configuration:

```toml
[mcp_servers.development-indicators]
url = "https://indicatorsmcp.impactengines.ai/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 180
```

Example test prompt: `Using Development Indicators, find an official maize
production series from FAOSTAT and retrieve 2020–2023 observations for Uganda
and Kenya, preserving units, flags and citations.`

## Cloudflare deployment

The repository includes a Cloudflare Worker and Container configuration. It
routes public HTTPS requests to the same tested Python image; the MCP endpoint
remains `/mcp`. A production deployment should initially use its isolated
`workers.dev` hostname, then attach a custom domain after client verification.

```powershell
npm install
npm run deploy
```

To deploy under a different Worker name or hostname, edit `name` and `routes` in
`wrangler.jsonc`. Remove the `routes` block if you only want a `workers.dev`
endpoint. Authenticate Wrangler with your own Cloudflare account before running
the deploy command; the repository contains no Impact Engines credentials.

Optional provider credentials can be added to your Worker without committing
them:

```powershell
npx wrangler secret put FAOSTAT_USER
npx wrangler secret put FAOSTAT_PASSWORD
npx wrangler secret put UN_POPULATION_TOKEN
```

See [docs/deployment.md](docs/deployment.md) for the deployment architecture,
verification checklist and non-Cloudflare Docker instructions.

## Run with Docker

```bash
docker build -t development-data-mcp .
docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  development-data-mcp
```

The endpoint will be available at `http://localhost:8000/mcp`. Put it behind
HTTPS and suitable access controls before exposing it to the public internet.

## Contributing

Issues and pull requests are welcome. Please run `ruff check .`, `pytest`, and
`npm run typecheck` before submitting a change. See [CONTRIBUTING.md](CONTRIBUTING.md)
for the full development workflow and [SECURITY.md](SECURITY.md) for private
vulnerability reporting guidance.

Cloudflare Containers require a Workers paid plan. FAOSTAT credentials, when
configured, must be stored with Wrangler secrets rather than committed.

## Architecture

```text
AI client
   |
Remote MCP gateway
   |
Metadata registry and source router
   |
Provider adapters (REST / SDMX / OData / specialist)
   |
Official publisher APIs
```

Only metadata and modest request caches should be stored locally at first. Observations are retrieved from official sources and returned in a common envelope while preserving the original source identifiers.

## Planned source sequence

Active observation connectors: World Bank Indicators, WHO GHO, UNICEF SDMX,
FAOSTAT, ILOSTAT, IMF DataMapper, UNSD SDG, UNESCO UIS, OECD SDMX and ADB SDMX.
UN Population indicator discovery is active; its observation endpoint requires
a portal-issued bearer token. DHS, MICS, IPUMS and World Bank Microdata Library
remain catalogue-discovery integrations rather than observation APIs.

## Safety and statistical integrity

- Values are never invented or inferred by the MCP.
- Similar indicators are not silently merged.
- Provider codes and canonical URLs are retained.
- Observed, survey-estimated, modelled and projected values must be labelled when metadata permits.
- Microdata catalogue discovery does not imply permission to download restricted files.
- Large results should be exported rather than placed directly in model context.

## License

The software is released under the [MIT License](LICENSE). Upstream data remain
subject to each publisher's terms, licences and attribution requirements.