内容
# sunat-datos-abiertos-mcp
MCP 服务器（Model Context Protocol），用于公开 **SUNAT** 在 [国家开放数据平台](https://www.datosabiertos.gob.pe) 上发布的数据集（包括 RUC 登记册，经济活动分类 CIIU，电子支付凭证，增值税扣缴/征收代理人等）。
## 要求
- Node.js 18+
## 安装
```bash
npm install
npm run build
```
## 可用工具（MCP）
| 工具 | 描述 |
|---|---|
| `sunat_listar_datasets` | 列出可用的 SUNAT 数据集（slug，标题，资源数量）。本地缓存。 |
| `sunat_obtener_dataset` | 获取指定 slug 数据集的详细信息和资源列表。本地缓存。 |
| `sunat_obtener_recurso` | 获取指定资源 ID 的元数据和实际下载 URL。 |
| `sunat_previsualizar_recurso` | 预览指定资源的前几行（csv 或 zip 中的 csv），无需完整下载。 |
| `sunat_descargar_recurso` | 将资源完整下载到磁盘，并返回下载路径和大小。 |
典型流程：`sunat_listar_datasets` → `sunat_obtener_dataset`（选择数据集）→ `sunat_previsualizar_recurso` 或 `sunat_descargar_recurso`（选择资源 ID）。
### 本地缓存
`sunat_listar_datasets` 和 `sunat_obtener_dataset`（及其在 CLI 中的等价命令 `list`/`show`）会在 `~/.sunat-mcp-cache` 缓存结果，因为 SUNAT 目录很少更改。默认 TTL 为 6 小时，可通过环境变量 `SUNAT_CACHE_TTL_MS` 调整（毫秒；`0` 禁用缓存）。手动清除缓存：`sunat cache clear`。
### 关于门户的说明
该门户的 API 是 CKAN，但有两点特殊之处，已针对真实 API 进行验证：
- `package_search` 和 `organization_list` 已禁用（返回 404）；因此，MCP 服务器通过 SUNAT 组（`group_package_show`）导航，而不是按关键词搜索。
- `package_show` 和 `group_package_show` 将结果封装在单个元素的附加数组中，与 `package_list`/`resource_show` 不同。MCP 服务器已处理此问题。
- 资源的 `formato` 字段并不总是可靠的：许多声明为 `csv` 的资源实际上是一个包含 csv 的 `.zip` 文件。`sunat_previsualizar_recurso` 检测到这一点并在流式传输中解压缩，仅在收集所需行时才下载。
## 与 Claude Desktop / Claude Code 结合使用
在 MCP 服务器配置（`claude_desktop_config.json` 或等效文件）中添加：
```json
{
"mcpServers": {
"sunat-datos-abiertos": {
"command": "node",
"args": ["C:\\source\\mcp-sunat\\build\\index.js"]
}
}
}
```
## 在终端作为 CLI 使用
除了 MCP 服务器外，该软件包还安装了一个 `sunat` 命令，可直接在终端中使用，无需通过 MCP 客户端。
```bash
npm run build
npm link # 全局安装 `sunat` 命令（本地构建的符号链接）
```
之后，`sunat` 可从任何目录使用：
```bash
sunat list # 列出 SUNAT 数据集
sunat show <dataset> # 数据集详细信息和资源
sunat resource <resource_id> # 资源元数据和 URL
sunat preview <resource_id> -n 50 # 预览行（默认 20）
sunat download <resource_id> -o ./padron.csv # 完整下载资源
sunat cache clear # 清除数据集的本地缓存
```
全局标志：
- `--json`：以原始 JSON 格式打印响应（适用于脚本/管道），而不是表格。
- `--no-color`：在输出中禁用颜色。
要卸载全局命令：`npm unlink -g sunat-datos-abiertos-mcp`（或 `npm ls -g --depth=0` 显示的名称）。
## 开发
```bash
npm run build # 将 TypeScript 编译到 build/
npm start # 运行编译后的 MCP 服务器（build/index.js）
node build/cli.js list # 运行 CLI，无需 npm link
```
