Development Indicators MCP

Development Indicators MCP

一个优先保障来源可追溯性的模型上下文协议网关，用于查询官方国际发展指标。

托管的 MCP 端点： https://indicatorsmcp.impactengines.ai/mcp

本项目旨在让 AI Agent 通过统一的接口，发现并查询世界银行、联合国机构、FAO、WHO、UNICEF、ILO 和 DHS Program 等机构的权威指标。它会保留定义、单位、维度、来源代码和引用信息，而非返回没有引用的文字内容。

当前里程碑

该仓库包含一个可运行的纵向切片：

• 支持远程连接的 MCP 服务，使用 Streamable HTTP，并支持本地客户端通过 stdio 连接；
• 描述 API、身份验证和功能的来源注册表；
• 规范化的指标和观测数据架构；
• 可实时调用的 World Bank、WHO GHO、UNICEF、FAOSTAT、ILOSTAT、IMF、UNSD SDG、UNESCO UIS、OECD 和 ADB 适配器；
• 按需进行 FAOSTAT 身份验证，不进行后台令牌刷新；
• 动态发现 FAOSTAT 领域、国家、项目和要素；
• 加权实时目录搜索，支持别名、匹配说明、检索健康信号、有时限的提供方等待和 15 分钟查询缓存；
• 支持部分失败的比较、类型化错误、原生结构化输出和精简响应；
• 部分成功的地理位置解析，并提供结构化的未解析国家错误；
• 规范化的 ILOSTAT 频率标签和 FAOSTAT 维度排序依据；
• 用于解析国家名称、检查元数据和检索观测数据的工具；
• 用于验证规范化和来源行为的单元测试。

这是一个公开测试版，并非生产级统计服务。托管实例供评估使用；你也可以运行或部署自己的副本。

MCP 工具

• 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)

系列引用采用 source_id:series_code 的形式，例如 world_bank:SP.POP.TOTL。 观测数据调用接受 ISO 3166-1 alpha-3 代码，例如 GHA 和 KEN；如果提示词提供的是国家名称，请使用 resolve_geographies。混合批次会同时返回 resolved 和 unresolved 条目，而不会导致整个请求失败。

本地开发

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

在 macOS 或 Linux 上，使用 source .venv/bin/activate 激活环境。

运行实时来源冒烟测试基准：

python -m benchmarks.run

在配置 FAOSTAT_USER 和 FAOSTAT_PASSWORD 之前，将跳过 FAOSTAT 检查；所有公共来源检查均无需凭据即可运行。

默认传输方式为 stdio。若要运行类似托管服务的 HTTP 端点：

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

随后，MCP 端点将通过 /mcp 提供。生产部署必须在应用程序或网关层添加 HTTPS、身份验证、速率限制和审计日志。

在 Codex 中安装

托管服务使用 Streamable HTTP：

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

添加后重启 Codex，然后使用 /mcp 确认服务及其工具可用。同一台 Codex 主机上的 Codex CLI、IDE 扩展和 ChatGPT 桌面应用共享相同的 MCP 配置。

等效的 ~/.codex/config.toml 配置：

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

测试提示词示例：使用 Development Indicators，从 FAOSTAT 查找官方玉米产量序列，并获取乌干达和肯尼亚 2020–2023 年的观测值，同时保留单位、标记和引文。

Cloudflare 部署

此代码库包含 Cloudflare Worker 和 Container 配置。它会将公开的 HTTPS 请求路由到经过相同测试的 Python 镜像；MCP 端点仍为 /mcp。生产部署应先使用隔离的 workers.dev 主机名，待客户端验证后再绑定自定义域名。

npm install
npm run deploy

若要使用其他 Worker 名称或主机名部署，请编辑 wrangler.jsonc 中的 name 和 routes。如果只需要 workers.dev 端点，请移除 routes 块。运行部署命令前，请使用你自己的 Cloudflare 帐户验证 Wrangler；此代码库不包含 Impact Engines 凭据。

可以向 Worker 添加可选的提供方凭据，而无需将其提交到代码库：

npx wrangler secret put FAOSTAT_USER
npx wrangler secret put FAOSTAT_PASSWORD
npx wrangler secret put UN_POPULATION_TOKEN

请参阅 docs/deployment.md，了解部署架构、验证清单和非 Cloudflare Docker 说明。

使用 Docker 运行

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

该端点将在 http://localhost:8000/mcp 提供服务。在将其暴露到公共互联网之前，请将其置于 HTTPS 和适当的访问控制之后。

参与贡献

欢迎提交问题和拉取请求。提交更改前，请运行 ruff check .、pytest 和 npm run typecheck。完整的开发工作流请参阅 CONTRIBUTING.md，私下报告漏洞的指南请参阅 SECURITY.md。

Cloudflare Containers 需要 Workers 付费计划。如配置了 FAOSTAT 凭据，必须使用 Wrangler secrets 存储，不得提交到代码库。

架构

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

初期仅应在本地存储元数据和少量请求缓存。观测值从官方来源获取，并在保留原始来源标识符的同时，以通用封装格式返回。

计划中的来源顺序

当前启用的观测值连接器：World Bank Indicators、WHO GHO、UNICEF SDMX、FAOSTAT、ILOSTAT、IMF DataMapper、UNSD SDG、UNESCO UIS、OECD SDMX 和 ADB SDMX。UN Population 指标发现功能已启用；其观测值端点需要由门户签发的 bearer token。DHS、MICS、IPUMS 和 World Bank Microdata Library 仍是目录发现集成，而非观测值 API。

安全性与统计完整性

• MCP 绝不会编造或推断数值。
• 相似指标不会被悄然合并。
• 保留提供方代码和规范 URL。
• 如果元数据允许，必须标明观测值、调查估算值、模型值和预测值。
• 发现微观数据目录并不代表获准下载受限文件。
• 大型结果应导出，而不是直接放入模型上下文。

许可证

本软件依据 MIT License 发布。上游数据仍受各发布方的条款、许可证和署名要求约束。