内容
# UN数据
CLI **和** MCP 服务器，用于 [UN数据 SDMX REST API](https://data.un.org/Host.aspx?Content=API) —
联合国统计司开放数据。查询世界发展指标、千年发展目标和其他联合国数据集，从您的终端、分析管道或任何 MCP 客户端（Claude，
Antigravity）。无需 API 密钥。
## 功能
- **`undata` CLI** — 终端访问，支持 `table` / `json` / `csv` / `parquet` 输出，可在任何地方运行
- **完整的 CLI ↔ MCP 对等性**：7 个工具、3 个提示和 3 个参考文档均可从两个接口访问
- **7 个 MCP 工具**：列出数据流、WDI 数据、国家概况、序列搜索、MDG 数据、通用查询、多国比较
- **3 个提示**：经济分析、发展目标进展、国家比较 — 也可以通过 `undata prompt`
- **3 个资源**：API 指南、国家代码、WDI 序列目录 — 也可以通过 `undata guide|countries|catalog`
- **磁盘缓存**，以便重复研究查询在运行之间立即生效
- **声明式数据流注册** — 添加数据集，只需一个条目，无需新代码
- **适用于人类和 AI**：漂亮的表格 + Markdown 适用于人类；干净的 JSON/CSV 和 `--raw` 适用于代理和管道
## 安装（一条命令）
需要 [uv](https://docs.astral.sh/uv/)。安装 `undata`（CLI）和 `undata-mcp`（服务器）到您的 PATH。
```bash
# Windows (PowerShell)
./install.ps1 # 添加 -Export 以支持 Parquet
# macOS / Linux
./install.sh # 添加 --export 以支持 Parquet
```
或直接安装：
```bash
uv tool install . # 或：uv tool install '.[export]'
```
`uv tool install` 后，两个命令都位于 uv 的工具 bin 中（例如 `~/.local/bin`），uv 会将该目录添加到您的 PATH 中 — 因此 `undata` 和 `undata-mcp` 可以在**任意目录**下运行。如果您的 shell 无法找到它们，请运行 `uv tool update-shell` 并重新打开终端。
无需安装即可运行：
```bash
uvx --from . undata wdi PER
```
> **PyPI（未来）**：该软件包已完成元数据，准备发布。一旦发布，即可在任何地方使用 `pipx install undata-mcp` / `uvx undata-mcp` 安装。发布是一个刻意且公开的步骤（`uv build && uv publish`），因此故意留给您触发。
## CLI 用法
```bash
undata dataflows # 列出可用数据集（实时）
undata datasets # 已注册数据集 + 别名（离线）
undata wdi PER --years 2015:2023 # 一个国家的 WDI 数据
undata wdi PER --series NY_GDP_PCAP_CD --format table
undata profile PER --year 2022 # 最新快照，所有指标
undata search education --country BRA # 查找 WDI 序列代码
undata mdg PER --years 2000:2020 # 千年发展目标
undata compare PER COL BRA --series NY_GDP_PCAP_CD # 多国比较
undata compare PER COL --format csv -o out.csv # 导出到 CSV 进行分析
undata compare PER COL --format parquet -o out.parquet
undata query wdi A..PER --years 2020:2023 # 通用 SDMX 查询（别名或 ID）
# 参考文档（MCP 服务器提供的资源内容相同）
undata guide # API 指南（终端中的 Markdown，管道输出时为原始文本）
undata countries --raw # ISO-3 国家代码
undata catalog # 按主题分类的常用 WDI 序列代码
# 引导式分析提示（MCP 暴露的模板相同）
undata prompt # 列出提示
undata prompt country_economic_analysis -c PER --year 2022
undata prompt compare_countries -c PER,COL,BRA
undata mcp-config # 打印 MCP 客户端配置片段
undata --version
undata serve # 启动 MCP 服务器（= undata-mcp）
```
每个数据命令的全局标志：`--format table|json|csv|parquet`（默认为 `table`）和 `--output/-o FILE`。参考命令使用 `--raw` 进行纯文本（AI/管道）输出。
## MCP 用法
将您的 MCP 客户端指向 `undata-mcp` 命令。示例（`.antigravity.json`，已包含）：
```json
{
"mcpServers": {
"undata": {
"command": "uv",
"args": ["--directory", "C:\\Users\\USER\\source\\MCPs\\UNdata-mcp", "run", "undata-mcp"]
}
}
}
```
`undata-mcp` 和 `undata serve` 是等效的。
| 工具 | 描述 |
|------|-------------|
| `undata_list_dataflows` | 列出可用数据集 |
| `undata_get_wdi_data` | 一个国家的世界发展指标 |
| `undata_get_country_profile` | 所有 WDI 指标的最新快照 |
| `undata_search_wdi_series` | 按关键词查找序列代码 |
| `undata_get_mdg_data` | 千年发展目标数据 |
| `undata_compare_countries` | 跨国比较 WDI 指标 |
| `undata_query` | 任何数据流的通用 SDMX 查询 |
## 架构
逻辑位于**服务层**；CLI 和 MCP 工具是其上的薄适配器，因此两个接口之间**没有重复**。
```
services/ 核心异步逻辑（get_wdi_data, compare_countries, …）← 单一事实来源
↑ ↑
tools/ cli/ 薄适配器（MCP 工具 / Typer 命令）
registry.py 声明式 DataflowSpec + build_key() — 通过配置添加数据集
cache.py 可插拔的 CacheBackend：MemoryCache（服务器）/ DiskCache（CLI）
client.py 异步 httpx 客户端，注入缓存
formatters.py 纯 CSV → dict 转换
```
添加新数据集 = 在 `registry.py` 中添加一个 `DataflowSpec` 条目（如果输出形状不同，则添加一个小服务函数）。新接口（REST API，笔记本）可以**无需修改**地重用 `services/`。
## 配置
复制 `.env.example` 到 `.env`（所有配置均为可选）：
```
UNDATA_CACHE_TTL=600 # 响应缓存秒数（0 = 禁用）
UNDATA_TIMEOUT=60 # HTTP 超时秒数（SDMX 可能较慢）
UNDATA_CACHE_BACKEND=memory # memory | disk（CLI 强制使用磁盘缓存）
UNDATA_CACHE_DIR=... # 覆盖磁盘缓存位置
```
## 测试
```bash
uv run pytest tests/ -v
```
