Govdata Mcp

GovData MCP

一个模型上下文协议（MCP）服务，让 AI Agent 可以从各国官方政府数据门户中搜索、探索和获取开放数据集。通过统一的工具接口，覆盖美国、英国、加拿大和澳大利亚，同时由通用适配器层处理各门户的特有情况（API 迁移、身份验证限制、双语元数据、过时的 DataStore 标记）。

专为典型的 Agent 工作流打造：“有没有关于 X 的政府数据集？” → 查找候选数据集 → 查看文件 → 预览行或获取下载链接，然后继续下一步。

主要功能

• 四个国家级门户，一个接口。 美国（data.gov v4 / DCAT）、英国（data.gov.uk / CKAN）、加拿大（open.canada.ca / CKAN）、澳大利亚（data.gov.au / CKAN + DataStore）。
• 从设计上减少令牌消耗。 描述会去除 HTML 并截断，搜索结果采用精简摘要，大型文件不会意外以内联方式返回。
• 行级预览。 在可用时使用 CKAN DataStore（澳大利亚），其他情况下则透明地回退到读取 CSV/TSV 文件的开头部分。
• 适合 Agent 的错误处理方式。 错误会以可操作的文本返回（“改用 get_download_link”、“使用 dataset_id 重试”、“可用门户：…”），而不会返回原始回溯信息。
• 可扩展注册表。 添加另一个基于 CKAN 的门户只需添加一个配置项；非 CKAN 门户则通过一个小型适配器类接入。
• 双传输方式。 为本地客户端（如 Claude Desktop）提供 stdio，为无服务器部署（Google Cloud Run）提供无状态的 streamable-http。

支持的门户

要求

• Python 3.11+
• 美国门户需要 api.data.gov API 密钥（免费；其他门户无需凭据）

安装

git clone https://github.com/YOUR_ORG/Gov-Stat-MCP-Server.git
cd Gov-Stat-MCP-Server

# pip
pip install -e ".[dev]"

# or conda
conda env create -f environment.yml
conda activate opendata-mcp

将 .env.example 复制为 .env 并设置密钥：

DATAGOV_API_KEY=your-api-data-gov-key

入门

适用于大多数 MCP 客户端的标准配置（stdio 传输）：

{
  "mcpServers": {
    "govdata": {
      "command": "govdata-mcp",
      "env": {
        "DATAGOV_API_KEY": "your-api-data-gov-key"
      }
    }
  }
}

claude mcp add govdata -e DATAGOV_API_KEY=your-key -- govdata-mcp

MCP_TRANSPORT=http govdata-mcp

{
  "mcpServers": {
    "govdata": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

预期的 Agent 工作流：list_portals → search_datasets → get_dataset → preview_resource / fetch_resource / get_download_link。

配置

所有设置均为环境变量（或本地 .env 文件）：

Docker

make docker-build          # build image
make docker-run            # run on :8080, exactly as Cloud Run would

此镜像以无状态模式运行 HTTP 传输，已准备好部署到无服务器平台（deploy/ 下附带 Google Cloud Run 部署脚本）。

开发

make run          # stdio mode
make run-http     # HTTP mode on :8080
make inspect      # MCP Inspector interactive UI (requires Node.js)
make test         # offline unit tests
make test-live    # live end-to-end tests against all four real portals
make lint         # ruff check + format check

实时测试套件（pytest -m live）会针对每个国家/地区验证完整的搜索 → 探索 → 预览 → 获取流程，以及特定门户的行为（加拿大的双语规范化、英国按数据集范围查找资源、澳大利亚的 DataStore 路径）。部署前请运行测试——政府门户可能会在不另行通知的情况下发生变更。

架构

src/govdata_mcp/
├── server.py            # FastMCP instance + tool registration
├── config.py            # env-driven settings
├── ckan/                # generic async CKAN client, models, typed errors
├── portals/
│   ├── registry.py      # portal registry — single source of truth
│   ├── base.py          # Portal config + default (vanilla CKAN) adapter
│   ├── us.py            # data.gov v4 DCAT adapter (auth, cursor paging)
│   ├── uk.py            # dataset-scoped resource lookup
│   └── ca.py            # bilingual metadata normalization
├── tools/               # MCP tools: search, explore, fetch
└── utils/               # formatting (token economy), CSV-head preview

添加门户： 对于标准 CKAN 门户，只需在 portals/registry.py 中添加一条 Portal(...) 条目即可。对于有特殊情况的门户，可继承 PortalAdapter 并重写范围较小的钩子（normalize_dataset、build_search_params），或者对于非 CKAN API，重写操作方法本身（完整的自定义适配器示例见 us.py）。

TODO / 路线图

• 🇨🇳 中国门户支持——目前没有统一的国家级开放数据 API；计划开发自定义适配器，通过现有的统计软件包访问国家统计局数据，并支持优雅降级。
• 🇯🇵 日本门户支持——e-Gov Data Portal (data.e-gov.go.jp) 兼容 CKAN，应可接入现有注册表；功能更丰富的 e-Stat 统计 API（需要 app-ID 身份验证，元数据为日语）计划通过专用适配器支持。
• 使用已记录的门户测试数据（respx）构建离线单元测试套件，以供 CI 使用
• Google Cloud Run 部署指南（服务已可通过容器部署；脚本位于 deploy/）
• US v4 发布者/格式搜索筛选器（等待 API 文档）
• 更多 CKAN 门户（新西兰 data.govt.nz 几乎可以零成本添加）
• 内容类型嗅探，以处理格式标签错误的资源

安全说明

• 此服务对门户采用只读访问——没有任何工具可以创建、修改或删除内容。
• fetch_resource 和 preview_resource 会从门户元数据中包含的 URL 下载内容；返回给模型前会限制内容大小并检查是否为二进制内容，但请将获取的内容视为不可信输入。
• 服务本身没有身份验证。远程部署时，请将其置于身份验证代理或平台级身份验证之后（例如，在 Cloud Run 中使用 --no-allow-unauthenticated）。
• 请将 DATAGOV_API_KEY 保存在 .env / Secret Manager 中——切勿提交。

许可证

MIT