# UNdata

CLI **and** MCP server for the [UNdata SDMX REST API](https://data.un.org/Host.aspx?Content=API) —
UN Statistics Division open data. Query World Development Indicators, Millennium Development Goals and
other UN datasets from your terminal, from analysis pipelines, or from any MCP client (Claude,
Antigravity). No API key required.

## Features

- **`undata` CLI** — terminal access with `table` / `json` / `csv` / `parquet` output, runnable from anywhere
- **Full CLI ↔ MCP parity**: the 7 tools, 3 prompts, and 3 reference docs are all reachable from both interfaces
- **7 MCP tools**: list dataflows, WDI data, country profile, series search, MDG data, generic query, multi-country compare
- **3 prompts**: economic analysis, development goals progress, country comparison — also via `undata prompt`
- **3 resources**: API guide, country codes, WDI series catalog — also via `undata guide|countries|catalog`
- **Disk cache** so repeated research queries are instant across runs
- **Declarative dataflow registry** — add a dataset with one entry, no new code
- **Built for humans *and* AIs**: pretty tables + Markdown for people; clean JSON/CSV and `--raw` for agents and pipelines

## Install (one command)

Requires [uv](https://docs.astral.sh/uv/). Installs both `undata` (CLI) and `undata-mcp` (server) onto your PATH.

```bash
# Windows (PowerShell)
./install.ps1                 # add -Export for Parquet support

# macOS / Linux
./install.sh                  # add --export for Parquet support
```

Or directly:

```bash
uv tool install .             # or:  uv tool install '.[export]'
```

After `uv tool install`, both commands live in uv's tool bin (e.g. `~/.local/bin`), which uv puts on
your PATH — so `undata` and `undata-mcp` run **from any directory**. If your shell can't find them yet,
run `uv tool update-shell` and reopen the terminal.

Run without installing:

```bash
uvx --from . undata wdi PER
```

> **PyPI (future):** the package is metadata-complete and ready to publish. Once published, install
> anywhere with `pipx install undata-mcp` / `uvx undata-mcp`. Publishing is a deliberate, public step
> (`uv build && uv publish`) and is intentionally left for you to trigger.

## CLI usage

```bash
undata dataflows                                   # list available datasets (live)
undata datasets                                    # registered datasets + aliases (offline)

undata wdi PER --years 2015:2023                   # WDI for one country
undata wdi PER --series NY_GDP_PCAP_CD --format table
undata profile PER --year 2022                     # latest snapshot, all indicators
undata search education --country BRA              # find WDI series codes
undata mdg PER --years 2000:2020                   # Millennium Development Goals

undata compare PER COL BRA --series NY_GDP_PCAP_CD # multi-country comparison
undata compare PER COL --format csv -o out.csv     # export to CSV for analysis
undata compare PER COL --format parquet -o out.parquet

undata query wdi A..PER --years 2020:2023          # generic SDMX query (alias or id)

# Reference docs (same content the MCP serves as resources)
undata guide                                       # API guide (Markdown in a terminal, raw when piped)
undata countries --raw                             # ISO-3 country codes
undata catalog                                     # common WDI series codes by topic

# Guided analysis prompts (same templates the MCP exposes)
undata prompt                                      # list prompts
undata prompt country_economic_analysis -c PER --year 2022
undata prompt compare_countries -c PER,COL,BRA

undata mcp-config                                  # print an MCP client config snippet
undata --version
undata serve                                       # start the MCP server (= undata-mcp)
```

Global flags on every data command: `--format table|json|csv|parquet` (default `table`) and
`--output/-o FILE`. Reference commands take `--raw` for plain-text (AI/pipeline) output.

## MCP usage

Point your MCP client at the `undata-mcp` command. Example (`.antigravity.json`, already included):

```json
{
  "mcpServers": {
    "undata": {
      "command": "uv",
      "args": ["--directory", "C:\\Users\\USER\\source\\MCPs\\UNdata-mcp", "run", "undata-mcp"]
    }
  }
}
```

`undata-mcp` and `undata serve` are equivalent.

| Tool | Description |
|------|-------------|
| `undata_list_dataflows` | List available datasets |
| `undata_get_wdi_data` | World Development Indicators for a country |
| `undata_get_country_profile` | Latest snapshot across all WDI indicators |
| `undata_search_wdi_series` | Find series codes by keyword |
| `undata_get_mdg_data` | Millennium Development Goals data |
| `undata_compare_countries` | Compare WDI indicators across countries |
| `undata_query` | Generic SDMX query for any dataflow |

## Architecture

The logic lives in a shared **service layer**; the CLI and the MCP tools are thin adapters over it, so
there is zero duplication between the two interfaces.

```
services/   core async logic (get_wdi_data, compare_countries, …)  ← single source of truth
  ↑     ↑
tools/    cli/     thin adapters (MCP tools / Typer commands)
registry.py   declarative DataflowSpec + build_key() — add datasets by config
cache.py      pluggable CacheBackend: MemoryCache (server) / DiskCache (CLI)
client.py     async httpx client, cache injected
formatters.py pure CSV → dict shaping
```

Adding a new dataset = one `DataflowSpec` entry in `registry.py` (and, if its output shape differs,
one small service function). New interfaces (REST API, notebooks) can reuse `services/` unchanged.

## Configuration

Copy `.env.example` to `.env` (all optional):

```
UNDATA_CACHE_TTL=600           # response cache seconds (0 = disabled)
UNDATA_TIMEOUT=60              # HTTP timeout seconds (SDMX can be slow)
UNDATA_CACHE_BACKEND=memory   # memory | disk (CLI forces disk automatically)
UNDATA_CACHE_DIR=...          # override the disk cache location
```

## Tests

```bash
uv run pytest tests/ -v
```