内容
# 政府数据MCP
一个模型上下文协议（MCP）服务器，允许AI代理**搜索、探索和获取来自官方政府数据门户的开放数据集**。在美国、英国、加拿大和澳大利亚范围内提供统一的工具接口，每个门户都有其特定的适配层以吸收差异。
为典型的代理工作流而设计： *"是否有关于X的政府数据集？"* → 查找候选数据集 → 检查文件 → 预览行或获取下载链接并继续。
### 主要功能
- **四个国家门户，一个接口。** 美国（data.gov v4 / DCAT），英国（data.gov.uk / CKAN），加拿大（open.canada.ca / CKAN），澳大利亚（data.gov.au / CKAN + DataStore）。
- **设计上节省令牌。** 描述信息经过HTML剥离和截断，搜索结果是紧凑的摘要，大文件永远不会意外内联。
- **行级预览。** 在可用时使用CKAN DataStore（澳大利亚），并在其他地方透明地回退到读取CSV/TSV文件的头部。
- **代理友好型故障模式。** 错误以可操作的文本返回（"使用 `get_download_link` 代替"，"重试 `dataset_id`"，"可用门户：…"）- 永远不会出现原始回溯。
- **可扩展的注册表。** 添加另一个基于CKAN的门户是一个配置项；非CKAN门户通过一个小型适配器类插件。
- **双重传输。** `stdio` 用于本地客户端（Claude Desktop等），无状态 `streamable-http` 用于无服务器部署（Google Cloud Run）。
### 支持的门户
| 代码 | 门户 | API | 搜索 | 探索 | 行预览 | 备注 |
|------|--------|-----|:------:|:-------:|:-----------:|-------|
| `us` | [data.gov](https://catalog.data.gov) | data.gov v4 (DCAT) | ✅ | ✅ | CSV fallback | 需要免费的 [api.data.gov](https://api.data.gov/signup/) 密钥 |
| `uk` | [data.gov.uk](https://www.data.gov.uk) | CKAN | ✅ | ✅ | CSV fallback | 资源查找需要父 `dataset_id` |
| `ca` | [open.canada.ca](https://open.canada.ca/en/open-data) | CKAN | ✅ | ✅ | CSV fallback | 双语标题标准化为英文 |
| `au` | [data.gov.au](https://data.gov.au) | CKAN + DataStore | ✅ | ✅ | ✅ DataStore | 使用文本过滤的全行查询 |
### 要求
- Python 3.11+
- 美国门户的 [api.data.gov](https://api.data.gov/signup/) API密钥（免费；其他门户不需要凭证）
### 安装
```bash
git clone https://github.com/YOUR_ORG/Gov-Stat-MCP-Server.git
cd Gov-Stat-MCP-Server
# pip
pip install -e ".[dev]"
# 或 conda
conda env create -f environment.yml
conda activate opendata-mcp
```
复制 `.env.example` 到 `.env` 并设置您的密钥：
```bash
DATAGOV_API_KEY=您的-api-data-gov密钥
```
### 入门指南
**大多数MCP客户端的标准配置**（stdio传输）：
```json
{
"mcpServers": {
"govdata": {
"command": "govdata-mcp",
"env": {
"DATAGOV_API_KEY": "您的-api-data-gov密钥"
}
}
}
}
```
<details>
<summary>Claude 代码</summary>
```bash
claude mcp add govdata -e DATAGOV_API_KEY=您的密钥 -- govdata-mcp
```
</details>
<details>
<summary>Claude 桌面版</summary>
按照MCP安装 [指南](https://modelcontextprotocol.io/quickstart/user) 并使用上面的标准配置。注意：`govdata-mcp` 必须位于Claude Desktop使用的PATH中 - 如果需要，在虚拟环境/conda环境中提供可执行文件的绝对路径，例如 `/path/to/envs/mcp-env/bin/govdata-mcp`。
</details>
<details>
<summary>Cursor / Windsurf / 其他 JSON 配置客户端</summary>
在客户端的MCP设置文件中，使用上面的标准配置。
</details>
<details>
<summary>HTTP传输（远程/长时间运行的服务器）</summary>
在HTTP模式下运行服务器：
```bash
MCP_TRANSPORT=http govdata-mcp
```
然后将您的客户端指向该端点：
```json
{
"mcpServers": {
"govdata": {
"url": "http://localhost:8080/mcp"
}
}
}
```
</details>
### 工具
预期的代理流程：`list_portals` → `search_datasets` → `get_dataset` → `preview_resource` / `fetch_resource` / `get_download_link`。
<details>
<summary><b>发现</b></summary>
- **list_portals**
- 描述：列出可用的政府开放数据门户及其功能。
- 参数：无
- 只读：**true**
- **search_datasets**
- 描述：对门户上的数据集进行全文搜索。返回带有数据集ID的紧凑摘要。
- 参数：
- `portal`（字符串）：门户代码 - `us`，`uk`，`ca`，`au`
- `query`（字符串）：搜索词，例如 `"空气质量监测"`
- `limit`（数字，可选）：最大结果数（默认10，最大50）
- `org`（字符串，可选）：发布者/组织过滤器（CKAN门户）
- `format`（字符串，可选）：资源格式过滤器，例如 `"CSV"`（CKAN门户）
- 只读：**true**
</details>
<details>
<summary><b>探索</b></summary>
- **get_dataset**
- 描述：完整的数据集元数据 - 组织、许可证、标签、描述和可下载资源的列表及其ID、格式和大小。
- 参数：
- `portal`（字符串）：门户代码
- `dataset_id`（字符串）：来自 `search_datasets` 的数据集ID/_slug
- 只读：**true**
- **preview_resource**
- 描述：从表格资源预览行。首先尝试门户的DataStore（行数 + 文本过滤）；回退到读取CSV/TSV文件的头部。非表格格式无法预览。
- 参数：
- `portal`（字符串）：门户代码
- `resource_id`（字符串）：来自 `get_dataset` 的资源ID
- `rows`（数字，可选）：返回的行数（默认20，最大100）
- `query`（字符串，可选）：全文行过滤器（仅限DataStore支持的资源）
- `dataset_id`（字符串，可选）：父数据集ID - 推荐；在 `uk` 上需要
- 只读：**true**
</details>
<details>
<summary><b>检索</b></summary>
- **fetch_resource**
- 描述：下载一个小的文本资源（CSV/JSON/XML/...）并返回其内容内联，截断到一个干净的换行边界上的大小上限。 二进制内容被拒绝，并指向下载URL。
- 参数：
- `portal`（字符串）：门户代码
- `resource_id`（字符串）：来自 `get_dataset` 的资源ID
- `max_kb`（数字，可选）：内联的最大千字节数（默认256，最高512）
- `dataset_id`（字符串，可选）：父数据集ID - 推荐；在 `uk` 上需要
- 只读：**true**
- **get_download_link**
- 描述：返回资源的直接下载URL、格式和大小，以便代理可以自行继续。适用于任何格式，包括大文件/二进制文件。
- 参数：
- `portal`（字符串）：门户代码
- `resource_id`（字符串）：来自 `get_dataset` 的资源ID
- `dataset_id`（字符串，可选）：父数据集ID - 推荐；在 `uk` 上需要
- 只读：**true**
</details>
### 配置
所有设置都是环境变量（或本地 `.env` 文件）：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | `stdio`（本地客户端）或 `http`（streamable-http服务器） |
| `PORT` | `8080` | HTTP传输的监听端口（在Cloud Run上自动注入） |
| `DATAGOV_API_KEY` | — | 美国门户的api.data.gov密钥；回退到 `DEMO_KEY`（~30 req/hr） |
| `LOG_LEVEL` | `INFO` | 日志详细程度（始终写入stderr） |
| `HTTP_TIMEOUT_SECONDS` | `30` | 门户请求的超时时间 |
| `HTTP_MAX_RETRIES` | `2` | 暂态门户错误（5xx / 传输）的重试次数，指数退避 |
| `SEARCH_DEFAULT_LIMIT` | `10` | 默认搜索结果数 |
| `NOTES_TRUNCATE_CHARS` | `200` | 搜索摘要中的描述截断长度 |
| `FETCH_MAX_BYTES` | `524288` | 内联资源内容的硬上限 |
### Docker
```bash
make docker-build # 构建镜像
make docker-run # 在 :8080 上运行，类似于 Cloud Run
```
镜像以无状态模式运行HTTP传输，适用于无服务器平台（Google Cloud Run部署脚本包含在 `deploy/` 下）。
### 开发
```bash
make run # stdio 模式
make run-http # HTTP 模式在 :8080
make inspect # MCP Inspector 交互式 UI（需要 Node.js）
make test # 离线单元测试
make test-live # 对所有四个真实门户的实时端到端测试
make lint # ruff 检查 + 格式检查
```
实时测试套件（`pytest -m live`）验证每个国家的完整搜索 → 探索 → 预览 → 获取链以及门户特定的行为（加拿大的双语标准化，英国的数据集范围内的资源查找，澳大利亚的DataStore路径）。在部署前运行它 - 政府门户可能会在没有通知的情况下更改。
### 架构
```text
src/govdata_mcp/
├── server.py # FastMCP 实例 + 工具注册
├── config.py # 环境驱动的设置
├── ckan/ # 通用异步 CKAN 客户端，模型，类型错误
├── portals/
│ ├── registry.py # 门户注册 - 统一源
│ ├── base.py # 门户配置 + 默认（香草 CKAN）适配器
│ ├── us.py # data.gov v4 DCAT 适配器（身份验证，光标分页）
│ ├── uk.py # 数据集范围内的资源查找
│ └── ca.py # 双语元数据标准化
├── tools/ # MCP 工具：搜索，探索，获取
└── utils/ # 格式化（令牌经济），CSV 头预览
```
**添加门户：** 对于标准CKAN门户，在 `portals/registry.py` 中添加一个 `Portal(...)` 条目即可。对于具有特殊功能的门户，子类化 `PortalAdapter` 并重写狭窄的钩子（`normalize_dataset`，`build_search_params`）或对于非CKAN API，操作方法本身（参见 `us.py` 中的完整自定义适配器）。
### 待办事项/路线图
- [ ] **中国门户支持** - 没有统一的国家开放数据API；计划作为一个自定义适配器，针对国家统计局数据（通过现有的统计数据包）并具有优雅的降级。
- [ ] **日本门户支持** - e-Gov Data Portal ([data.e-gov.go.jp](https://data.e-gov.go.jp)) 与CKAN兼容，应该可以直接接入现有的注册表；更丰富的e-Stat统计API（应用ID身份验证，日语元数据）计划作为专用适配器。
- [ ] 离线单元测试套件，带有记录的门户fixtures（respx）用于CI
- [ ] Google Cloud Run部署指南（服务已容器化； `deploy/`下有脚本）
- [ ] 美国v4发布者/格式搜索过滤器（待API文档）
- [ ] 更多CKAN门户（新西兰 [data.govt.nz](https://data.govt.nz) 是一个近乎免费的补充）
- [ ] 内容类型嗅探，以挽救错误标记的资源格式
### 安全注意事项
- 该服务器**只读**面向门户 - 没有工具可以创建，修改或删除任何内容。
- `fetch_resource` 和 `preview_resource` 从门户元数据中下载的URL下载内容；内容大小限制并经过二进制检查后再返回给模型，但请将获取的内容视为不受信任的输入。
- 服务器本身没有身份验证。对于远程部署，请将其置于身份验证代理或平台级身份验证（例如Cloud Run with `--no-allow-unauthenticated`）后面。
- 将 `DATAGOV_API_KEY` 保存在 `.env` / 秘密管理器中 - 永远不要提交它。
### 许可证
MIT
