datos.gob.do-MCP-server

English · 西班牙语

---

datosgobdo-mcp

向 AI 助手询问有关多米尼加公共数据的问题，即可获得可追溯至其来源政府文件的答案。

这是一个用于 datos.gob.do 的 Model Context Protocol 服务。datos.gob.do 是多米尼加共和国的官方开放数据门户。它可以接入 Claude Desktop、Claude Code、Cursor、ChatGPT Desktop 或任何兼容 MCP 的客户端，让模型搜索目录、下载实际文件、解析文件并进行真实分析——无需编写代码、打开 URL 或下载电子表格。

官方来源。 官方仓库为 alcastaro/datos.gob.do-MCP-server。 唯一的官方分发渠道是 PyPI 包 dominican-open-data-mcp 和 MCP Registry 条目 io.github.alcastaro/datos.gob.do-MCP-server。 其他地方发布的副本并非由作者维护，且可能已经过时或被修改——安装前请对照此仓库进行验证。

本 README 按顺序编写。**第 1 部分无需任何技术知识。**第 2 部分以此服务为实例，讲解 MCP 的实际含义。第 3 至第 6 部分是参考资料和工程细节。如果你想通过引导式讲解了解相同内容，请阅读教程（西班牙语）。

---

目录

第 1 部分 — 从这里开始（无需技术知识）

1. 这是做什么的？简单来说
2. 快速开始
3. 六个引导式提示词——从 /empezar_aqui 开始
4. 你可以问什么
5. 引用数字前请先阅读

第 2 部分 — 了解 MCP（教学内容）

6. 什么是 MCP？工具、资源和提示词
7. 什么是 datos.gob.do？

第 3 部分 — 此服务提供的功能

8. 工具（24 个，另有 3 个可选工具）
9. 资源（3 个）和一个资源模板
10. 提示词（6 个）
11. 该使用哪种原语

第 4 部分 — 此服务的存在意义

12. 与其他 CKAN MCP 服务的比较

第 5 部分 — 技术参考

13. 安装和客户端配置
14. 答案如何说明自身信息
15. 安全性和环境变量
16. 架构
17. 已测量的限制

第 6 部分 — 开发

18. 开发、测试和 MCP Inspector
19. 贡献、致谢、引用方式和许可证
20. 隐私政策

---

---

第 1 部分 — 从这里开始

1. 简单来说，这是什么

多米尼加政府发布了数千份文件：公共部门工资单、预算执行情况、医院活动、人口迁移流向、采购合同、电力损耗、森林火灾等。这些信息都是公开的。但几乎没人会去读，因为要读懂它们，你得知道 266 家机构各自发布了什么，找到文件，下载一份表头位于第 3 行的电子表格，还得知道接下来该怎么做。

这个服务会把整个过程交给你的 AI 助手。你用自己的话提问。助手会找到数据集，从发布机构自己的服务器下载文件，识别列，计算总和或平均值，然后告诉你答案，并说明数据来源以及它不得不排除的内容。

有三点值得先了解，因为它们影响着其他所有设计：

• **它只读取数据。**这里的任何功能都无法修改门户网站或发布任何内容。它不需要登录，也不需要密码。
• 它运行在你的电脑上，与你的助手并行工作。你的问题不会经过本项目所有的服务器。
• **它会告诉你数据有问题。**目录中大约有一半的数据无法通过程序下载；工具会如实说明，而不是编造数字。这正是整个设计的核心，并非藏在末尾的免责声明。

2. 快速开始

你需要 uv，这是一个小型工具，无需安装其他内容即可运行 Python 程序。在 macOS 或 Linux 上，将以下内容粘贴到终端：

curl -LsSf https://astral.sh/uv/install.sh | sh

在 Windows 上，请参阅 uv 安装页面。

然后告知你的助手这个服务。

**Claude Desktop。**打开 Settings → Developer → Edit Config，或直接编辑该文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

粘贴以下内容，并将 YOUR_USERNAME 替换为你的用户名：

{
  "mcpServers": {
    "datosgobdo": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["dominican-open-data-mcp"]
    }
  }
}

使用 uvx 的完整路径——Claude Desktop 不会读取 shell 的 PATH。然后完全退出 Claude Desktop（在 macOS 上按 Cmd+Q，而不是仅关闭窗口），再重新打开。在 Settings → Developer 下，你应该能看到 datosgobdo 正在运行。

无需进行其他设置。如果之后想更改某项设置——例如网络保护或缓存目录——请将其放在本文件内的 "env" 块中，而不是 shell 中：参见 §13。

**Claude Code。**一行即可：

claude mcp add datosgobdo -- uvx dominican-open-data-mcp

**其他客户端。**方法相同：将 uvx 注册为命令，并将 dominican-open-data-mcp 作为参数。MCP 客户端目录列出了各客户端支持的功能。完整选项——开发版本、本地克隆、托管模式——请参见 §13。

3. 六个引导式提示词——从 /empezar_aqui 开始

24 个工具并不意味着你应该直接上手。第一次看到这个目录的人，根本无从得知它最擅长处理的三类事项是薪资、预算执行和公共投资。

因此，服务提供了 六个提示词：可直接使用的问题，凝聚了完整审查整个目录后才总结出的经验。在 Claude Code 和 Claude Desktop 中，它们会显示为斜杠命令。输入：

/empezar_aqui

助手就会向你介绍这个门户，说明它最擅长处理哪些内容，给出三个具体的后续问题，并提前提醒你哪些内容无法下载。

另外五个提示词各需要一个参数：

提示词	你提供的内容	功能
/empezar_aqui	—	介绍门户，并提供三个入门问题。
/serie_temporal	一个主题	按年份构建序列，说明实际覆盖的时间范围，并避免将年份列误当作度量值。
/auditar_nomina	一个机构	统计公共薪资的总额、平均值和薪资分布，并说明排除了多少行及其原因。
/verificar_fuente	一个资源 URL	在你使用文件之前，检查其范围、来源和格式。
/explorar_institucion	一个机构	汇总该机构发布的所有内容，并说明每个文件的实际下载状态。
/cruzar_fuentes	一个主题	交叉比对两个资源，并说明计量单位、时间范围和连接方式的局限。

如果你的客户端没有将提示词显示为斜杠命令，请查看 MCP 客户端目录中的对应条目——客户端对提示词的支持是可选的，而 MCP Inspector 始终可以显示并运行这些提示词。

4. 你可以询问什么

用西班牙语或英语直接提问。下面是一些现在就能用的问题：

datos.gob.do 门户上有多少个数据集？哪些机构发布的数据集最多？

找出五个最相关的预算数据集，并告诉我每个数据集由哪个机构发布。

司法部门在薪资方面的支出是多少？

农业部在 2026 年 4 月有多少名在职员工？请按雇佣状态细分。

最后这个问题值得停下来细说，因为它正是整个分析层存在的意义。农业部的薪资数据是一个 CSV 文件，包含 826,000 行，大小为 94 MB——太大了，无法直接粘贴到对话中。服务会下载一次，将其转换为列式缓存，然后通过分组聚合给出答案：6 种状态类型，约 8,915 名员工。首次调用大约需要 14 秒；之后再询问同一文件的问题，回答时间不到半秒。

比较 FONDOMARENA 过去三年的预算核定金额与执行金额。

内政部的车辆盗窃数据集包含哪些列？

列出最近更新的十个数据集。

**通常适用人群：**原本需要编写爬虫的数据记者；需要程序化访问数据的研究人员；跟踪预算执行和采购情况的透明度组织；基于公共数据制作原型的开发者；希望核实本机构已经发布哪些数据的公职人员；以及任何想了解国家实际运作方式的人。

5. 引用数字前请先阅读

本目录确实存在缺陷，而且这些缺陷经过了测量——在 2026-08-08 对整个目录进行了普查，每个数据集抽取一项资源，通过真实的 MCP 会话检查了 1,056 项资源。以下四项发现会影响你对这里任何数字的解读：

约一半的目录无法通过程序下载。 1,056 项资源中有 561 项可读取（53.1 %），高于上次普查的 540 项：0.14.0 的格式处理工作修复了其中 21 项，并于 2026-08-13 根据实时数据门户重新测量。其余资源无法读取的最大单一原因不在本服务，任何版本的本服务都无法解决：98 家机构的 360 项资源位于某种网站配置之后，该配置会拒绝以程序方式下载这些机构作为开放数据发布的文件。从同一地址访问时，另外 21 个使用同一 CDN 的政府主机都能正常响应——因此这是单个网站的配置问题，而非我们的网络问题。另有 15 个链接已失效，6 个文件在任何编码下都无法读取。

三分之一的多格式数据集相互矛盾。 在 528 个可比较格式的数据集中，176 个在行数或列数上不一致。例如，财政部的 recaudaciones-sirite-2021-2025 数据集以 CSV 格式提供 971,818 行，以 ODS 格式提供 197,338 行。下载 ODS 文件的市民与下载 CSV 文件的记者，会从同一官方数据集中引用出不同的数字。实用原则：发布总数前，请检查不止一种格式。

数字通常以文本形式存储。 该次普查中，可读取的 540 项资源里有 93 项将数值列存储为文本，通常是因为少数单元格中写有 N/A 或 #REF!。只要列中的值允许，工具就会将其读取为数字，并报告由此造成的影响——请参阅 §14。引用总数前，请先查看 values_excluded。

没有数据集声明更新频率。 所有 1,056 项资源的 periodicidad 字段均为空。标注为“2018-2026”的数据集，可能上个月才更新过，也可能两年前就已停止更新；你必须根据实际包含数据的最后一个时间段推断其新鲜度。

这些都不是不使用本目录的理由，而是提醒你准确引用——这正是 /verificar_fuente 和自描述响应字段的用途。

---

---

第 2 部分——了解 MCP

6. 什么是 MCP？工具、资源和提示词

Model Context Protocol 是一项开放标准，由 Anthropic 创建，如今已被整个行业采用，用于将语言模型连接到外部数据和能力。无需每个应用都发明自己的插件格式，面向模型的应用（即客户端，例如 Claude Desktop）可以通过同一种协议与任意数量的服务通信。

服务可以提供三类内容。区分它们很重要，因为这决定了使用时由谁决定：

原语	由谁控制	内容	在此服务中的实现
工具	模型	模型可以调用的函数，带有类型化参数。由模型选择何时调用以及使用哪些参数。	24 个函数：搜索、下载、聚合、查询……
资源	应用	应用可以附加为上下文的数据，通过 URI 寻址。没有副作用，也无需花费成本进行推理。	3 份文档 + 1 个 URI 模板
提示词	用户	用户主动调用的模板，通常作为斜杠命令使用。	6 个引导式工作流

flowchart LR
    subgraph HOST["Your app — the host"]
        U["You"] --> M["The model"]
        M <--> C["MCP client"]
    end
    subgraph SRV["datosgobdo-mcp — the server"]
        T["24 tools<br/><i>the model calls these</i>"]
        R["3 resources + 1 template<br/><i>the app attaches these</i>"]
        P["6 prompts<br/><i>you invoke these</i>"]
    end
    C -- "JSON-RPC 2.0 over stdio" --> T
    C --> R
    C --> P
    T --> CK["datos.gob.do<br/>CKAN API"]
    T --> FS["273 institutional<br/>web servers"]
    U -. "/empezar_aqui" .-> P
    style T fill:#E6F4EA,stroke:#34A853
    style R fill:#FEF7E0,stroke:#FBBC04
    style P fill:#E8F0FE,stroke:#4285F4

虚线体现了关键区别：这里由你发起的只有提示词。 模型不会调用提示词，应用也不会调用工具。

该协议还定义了客户端侧的原语——sampling、elicitation、roots——但此服务不会使用它们。

概念指南：工具、资源、提示词。如果你想构建一个服务，可以从构建服务开始，并阅读教程第 3 部分，了解本项目在构建过程中的经验。

此服务在连接时声明的内容，已于 2026-08-12 通过实时会话验证：

{
  "serverInfo": { "name": "datosgobdo-mcp", "version": "0.14.0" },
  "protocolVersion": "2025-11-25",
  "capabilities": {
    "tools":     { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false },
    "prompts":   { "listChanged": false }
  }
}

listChanged: false 和 subscribe: false 是如实声明，并非遗漏：工具列表在启动时固定，此处没有任何资源变化频繁到值得订阅。

关于两个版本号。 上面的规范链接指向当前规范 2026-07-28。此服务协商使用的是 2025-11-25，升级到 0.15.0 中的 v2 SDK 并未改变这一点——这是在真实握手中测得的，并非从常量中读取。2026-07-28 并未引入新的握手字符串：无论 v1 还是 v2，2025-11-25 都是 SDK 会协商的最新版本。v2 SDK 改变的是此服务所依赖的 API（FastMCP 改为 MCPServer，旧导入路径被直接删除，而非弃用），因此现在的版本限制是 mcp>=2.1,<3，两端的版本范围都不可或缺——在 mcp 1.x 上，这段代码根本无法导入。

7. datos.gob.do 是什么？

多米尼加政府的官方开放数据门户，由 OGTIC 运营。该门户运行 CKAN 2.11.3——data.gov（美国）、data.gov.uk 以及拉丁美洲许多门户背后的同一平台。

门户声明的数据（于 2026-08-12 实时查询）：

数据集	1,061
已注册组织	266
主题分组	11
标签	874
已加载的 CKAN 扩展	activity、datosgobdo_theme

2026-08-08 审计测得的数据——这是另一回事，两者之间的差距很能说明问题：

目录中的资源（文件）	3,826
实际拥有数据集的组织	266 个已注册组织中的 261 个
已测试的资源（每个数据集一个）	1,056
机器可读资源	561（53.1%）——2026-08-08 普查发现 540 个，另有 21 个由 0.14.0 恢复
已下载并缓存的行数	普查中有 13,371,601 行，另有 82,490 行恢复——普查范围外的同组文件中还有 846,388 行
托管在 datos.gob.do 本身的资源	66——其余资源位于另外 273 个域名上

最后一行揭示了本项目大部分问题背后的结构性事实。这个门户是链接目录，而不是文件仓库。 每个机构都将自己的文件保存在自己的 Web 服务器上，因此可用性、格式规范程度和访问规则都由门户无法控制的 273 个地方决定。

还要注意，扩展列表中没有什么：这里没有安装 CKAN 的 DataStore。 这一点正是该服务器呈现出目前这种形式的原因——请参阅§12。

本项目受 datagouv-mcp（法国 Etalab）启发，但 datos.gob.do 运行的是 CKAN，而不是 udata，因此本项目采用了独立的实现。

---

---

第 3 部分——此服务提供的内容

8. 工具（24 个，另有 3 个可选工具）

带类型的函数，分为五类。生成数据的工具（分析、预览、缓存）会返回带类型的 outputSchema / structuredContent，以便宿主验证结果；导航元数据工具则返回 JSON。每个面向门户的工具都标注为 readOnlyHint: true；面向网络的工具标注为 openWorldHint: true。

每个工具都以一个对象作答。 列表会说明其中包含的内容并给出数量——{organizations, count, limit_reached}、{tags, count, limit_reached}、{groups, count}、{suggestions, count, kind, query}。limit_reached 很重要，因为上限低于目录中的实际数量：266 个机构中最多返回 200 个；不带 query 的标签列表则只是从 874 个标签中抽取的样本。

发现

工具	功能
search_datasets	按关键词、组织、标签或分组搜索数据集。支持组合筛选和分页。
get_dataset	获取数据集的完整元数据：标题、描述、许可证、作者，以及每个资源的直接下载 URL。
list_recent_datasets	按最近修改时间排序的数据集。适用于监控门户更新。
get_site_stats	门户范围内的统计数据（数据集、组织、分组、标签）。

资源文件

工具	功能
get_resource	获取单个资源的元数据（URL、格式、大小、日期）。
search_resources	按名称搜索资源。
download_resource_preview	下载文件并返回 N 行。支持 CSV、TSV、XLSX、XLS、ODS、JSON。大小上限为 5 MB。采样模式：head / tail / random。
check_resources	最多检查 25 个 URL，确认其文件是否确实可下载，而不下载文件。每个 URL 会返回一个类别——可访问、浏览器验证、站点规则、链接失效、无响应——因为目录中有记录并不能证明文件仍然存在。

分析

基于持久化 Parquet 缓存运行 DuckDB。每个资源的首次调用会下载并缓存（最多 100 MB）；后续调用可在 1 秒内完成。根据实测中位数，缓存带来的性能提升约为 44 倍。

工具	功能
get_resource_schema	列名、推断类型和示例值。在进行任何聚合前进行低成本侦察。
summarize_resource	自动分析：行数、每列的空值数和不同值数、数值列的最小值/最大值/平均值，以及分类列的前 N 个值。
filter_resource	类型化 WHERE / SELECT / ORDER BY / LIMIT。运算符：=、!=、<、<=、>、>=、in、not_in、contains、starts_with、ends_with、is_null、is_not_null。
aggregate_resource	类型化 GROUP BY + 聚合 + HAVING + ORDER BY。函数：count、count_distinct、sum、avg、mean、median、min、max、stddev、variance。
quantiles_resource	数值列的百分位数分布（p25/p50/p75/p90/p95/p99）。
find_duplicates_resource	查找指定列（或所有列）中重复的行。对于工资单和人口普查数据质量检查至关重要。
detect_outliers_resource	查找数值列中位于 IQR 范围之外的行，并按与中位数的距离排序。
query_resource	高级用户的备用选项：对表 data 执行只读 SQL。仅允许 SELECT/WITH；拒绝 DDL/DML/COPY/PRAGMA/ATTACH/LOAD，并在沙箱中运行（参见 §15）。
save_query_to_csv	将筛选结果或 SQL 结果写入本地 CSV。可指定绝对路径，也可使用默认路径 ~/Downloads/datosgobdo-exports/。托管模式下禁用。
get_cache_stats	磁盘上的 Parquet 缓存统计信息，以及服务自身的标识和有效安全模式。total_bytes 表示磁盘占用，而非索引占用：orphan_entries 统计索引中未列出的 Parquet 文件——这些文件可能由缓存锁定丢失记账信息的调用写入，也可能由在记录文件前退出的进程写入；该值非零表示存在争用，而非缓存运行正常。
clear_cache	清除本地 Parquet 缓存。服务中唯一的非只读工具（destructiveHint: true）。托管模式下禁用。

目录

工具	功能
list_organizations	发布机构及其各自的数据集数量。
get_organization	某个机构的详细信息（描述、数据集数量、URL）。
list_groups	主题分类及其数量。
list_tags	标签，可按前缀筛选。

自动补全

工具	功能
autocomplete	查询数据集、机构、分组或标签的不完整名称，适用于用户只提供部分名称的情况。

GCP 管道（可选）

安装 pip install 'dominican-open-data-mcp[gcp]' 后，如果检测到 Google Cloud 库，会自动注册三个额外工具，工具总数增至 27。它们使此服务成为 BigQuery 管道的数据导入部分：在此处发现数据，加载到 BigQuery，然后使用 Google 自己的 BigQuery MCP 查询，以执行本地 DuckDB 缓存无法完成的跨数据集 JOIN。

工具	功能
load_resource_to_bigquery	资源 → Parquet 缓存 → 上传到 GCS → BigQuery 外部表（默认，无 ETL）或加载作业。
list_bigquery_exports	列出 BigQuery 数据集中的表。
get_bigquery_table_info	获取表的架构、行数和来源 URI。

设置 DATOSGOBDO_GCS_BUCKET，即可避免每次调用都传入存储桶。预览状态： 这三个工具不在稳定性承诺范围内，且尚未在实际项目中测试。

9. 资源（3 个）和一个资源模板

资源通过 URI 寻址，由应用程序读取，而不是由模型调用。它们用于存放那些内容简短、稳定，且不值得为此调用工具的事实。三者均为只读，且不会产生副作用。

URI	类型	内容
datosgobdo://catalog/overview	application/json	门户总览：数据集、机构、分组和标签数量。
datosgobdo://catalog/institutions	application/json	每个发布机构及其数据集数量——在进行任何查询之前，回答“是哪个机构？”
datosgobdo://guide/verification	text/markdown	让数字可核查的四个字段，以及缺少这些字段时该怎么做。

最后一个特意设为资源而不是提示词：它不是行动请求，而是值得在工作时放入上下文的参考文本。

一个资源模板——一种带参数的 URI 模式，因此一个定义就能指向目录中的每个数据集：

模板	填入内容	返回内容
datosgobdo://dataset/{dataset_id}	数据集 ID 或 slug	该数据集的元数据，可作为上下文附加。

示例：datosgobdo://dataset/nomina-poder-judicial。

如何使用。 在 Claude Desktop 中，连接到服务的对话会在附件菜单中显示资源。在其他客户端中，请查看客户端目录——资源支持是可选的。在所有客户端中，Inspector 的 Resources 面板都会列出这些资源并显示原始负载，包括展开模板。

10. 提示词（6 个）

提示词由用户控制：只有你可以调用它们。这里的每个提示词都融入了目录审计过程中痛苦学到的经验——这也是即使你已经熟悉这些工具，仍值得使用它们的原因。

提示词	参数	融入的经验
empezar_aqui	—	先了解情况再开始探索，并提前说明下载警告，而不是等到之后才发现。
serie_temporal	tema（必填）	声明数据实际覆盖的时间段，而不是标题中的时间段；绝不要把年份列当作度量值。
auditar_nomina	institucion（必填）	报告任何薪资总额时，同时说明被排除的行及其来源。
verificar_fuente	url（必填）	在依赖文件之前，先检查范围、来源和结构。
explorar_institucion	institucion（必填）	清点每个文件的实际下载状态，而不只是目录中的条目。
cruzar_fuentes	tema（必填）	在交叉分析两个来源之前，说明单位、时间段和连接限制。

如何调用。 在 Claude Code 和 Claude Desktop 中，可将它们作为斜杠命令调用：/empezar_aqui，或先输入 /serie_temporal，然后按提示输入主题。部分客户端会改为在菜单中显示它们。在 Inspector 中，Prompts 面板会列出每个提示词及其参数，并在发送给模型之前显示展开后的文本——这是查看提示词具体作用最可靠的方式。

11. 应该使用哪种原语

你想要……	使用	原因
回答有关数据的具体问题	通过普通对话使用工具	模型会选择并组合它们。
从零开始，或遵循严谨的方法	提示词	六种工作流已内置注意事项。
为助手提供长期背景信息	资源	附加一次即可；无需调用工具，也无需花费 token 来决定。
将某个数据集固定为上下文	资源模板	datosgobdo://dataset/{id}。
执行类型化工具未涵盖的操作	query_resource	只读 SQL，经过沙箱隔离。它是备用通道，而非首选。

---

---

第 4 部分——此服务为何存在

12. 与其他 CKAN MCP 服务的比较

CKAN 为数百个政府门户提供支持，因此开发一个通用的 CKAN MCP 服务显然是个好主意。目前最成熟的是 ondata/ckan-mcp-server（MIT、TypeScript，已被 AgID 采用，AgID 是意大利的数字机构）：支持使用完整 Solr 语法搜索数据集、搜索组织和组、跨约 950 个门户发现数据，以及通过 CKAN 的 DataStore API 访问表格数据。它通过 server_url 参数连接任意门户。如果你的门户已填充 DataStore，请使用它——它的功能范围比本项目更广，发布也更活跃。

区别不在于质量，而在于数据存放的位置。以下数据于 2026-08-12 在线核验：

GET /api/3/action/status_show   → extensions: ["activity", "datosgobdo_theme"]
GET /api/3/action/datastore_search
  → 400  "Action name not known: datastore_search"
resources with datastore_active: 0 / 254 sampled

datos.gob.do 没有 DataStore。 它没有 datastore_search，没有 SQL 端点，也没有任何资源加载到其中。指向该门户的通用 CKAN MCP 服务可以完美搜索元数据，却无法读取任何一行数据。这并不是它的缺陷——CKAN 中该扩展是可选的，而此门户从未启用它。

因此，这两个项目的适用范围泾渭分明：

	有 DataStore 的门户	作为文件目录的门户
数据存放位置	加载到 CKAN 中，可通过 API 查询	存放在 273 个机构的 Web 服务器上的文件
读取方式	datastore_search_sql	下载、检测编码、解析、缓存、查询
最佳工具	ondata/ckan-mcp-server	本项目

本代码库之所以比 CKAN API 封装更庞大，全是因为右栏中的情况：依据还原出的西班牙语评分来检测编码、流式解析 ODS（加载完整 DOM 会使内存占用增加约 580 倍）、使用解析器构建版本作为键的 Parquet 缓存、明确说明排除了哪些内容的数字类型转换、为 37 个返回 HTML 的 URL 解析页面到文件的对应关系、用于保护下载免受 273 个第三方主机 SSRF 攻击的防护，以及一个可选的存档副本回退机制（始终会说明何时触发）。

**如果你正在为其他拉美门户构建服务，**请先检查 status_show。如果没有 DataStore——多米尼加共和国的情况就是如此——你需要的正是本仓库中的文件读取流水线，教程 对其作了说明，便于复用。

---

---

第 5 部分 — 技术参考

13. 安装和客户端配置

选项 A — 从 PyPI 使用 uvx（推荐）

软件包：dominican-open-data-mcp。

uvx dominican-open-data-mcp

此外还提供一个简短别名二进制文件——两者启动的是同一个服务：

uvx --from dominican-open-data-mcp datosgobdo-mcp

uvx 会下载软件包、构建隔离的 venv 并运行它。首次运行需要几秒钟，之后则会立即启动。

从 ≤ 0.7.0 升级？ 这些版本将 mcp>=1.9.0 固定为最低版本，但没有设置上限；MCP Python SDK 2.0（2026-07-28）移除了 mcp.server.fastmcp 导入路径，因此全新安装会失败并报错 ModuleNotFoundError。请安装 0.15.0 或更高版本，它们基于 v2 SDK 编写，并将 mcp 固定为 mcp>=2.1,<3。若要继续使用较旧版本，请自行固定 SDK：uvx --with "mcp<2" --from dominican-open-data-mcp datosgobdo-mcp。

选项 B — 从 GitHub 使用 uvx（开发版本）

uvx --from git+https://github.com/alcastaro/datos.gob.do-MCP-server.git datosgobdo-mcp

选项 C — 本地克隆（用于开发）

git clone https://github.com/alcastaro/datos.gob.do-MCP-server.git
cd datos.gob.do-MCP-server
uv sync
uv run datosgobdo-mcp   # stdio; Ctrl+C to exit

macOS 说明： 不要在 ~/Library/CloudStorage/GoogleDrive-* 或类似目录中克隆项目。macOS 会阻止从云同步路径执行二进制文件（TCC 限制）。请使用 ~/code/ 或类似目录。

客户端配置

Claude Desktop 和 Claude Code 的配置见§2。要在 Claude Desktop 中跟踪开发版本，请将 args 替换为 ["--from", "git+https://github.com/alcastaro/datos.gob.do-MCP-server.git", "datosgobdo-mcp"]；在 Claude Code 中使用 claude mcp add datosgobdo -- uvx --from git+https://github.com/alcastaro/datos.gob.do-MCP-server.git datosgobdo-mcp。

对于 Cursor 和其他客户端，原则相同——将 uvx 注册为命令。各客户端的配置文件位置请查阅其文档；MCP 客户端目录提供了索引。

向服务传递设置：env 块

本 README 中的所有 DATOSGOBDO_* 变量都应放在客户端配置中的 "env" 对象内：

{
  "mcpServers": {
    "datosgobdo": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["dominican-open-data-mcp"],
      "env": {
        "DATOSGOBDO_NETGUARD": "strict",
        "DATOSGOBDO_CACHE_DIR": "/Users/YOUR_USERNAME/.cache/datosgobdo-mcp"
      }
    }
  }
}

在 shell 中执行 export DATOSGOBDO_NETGUARD=strict 不会将设置传给服务。 由客户端启动的 stdio MCP 服务只能继承一部分受平台影响的环境变量——MCP 调试指南对此有明确说明。在 shell 中设置变量后，服务仍会以默认模式启动，而你却以为它已受到限制。这一点对作为安全控制项的 DATOSGOBDO_NETGUARD 尤为重要（见 §15）。

这一事实会带来两个后果，在提交错误报告前都值得了解：

• 所有路径类型的设置都使用绝对路径。 客户端启动的服务的工作目录未定义——在 macOS 上是 /。DATOSGOBDO_ARCHIVE_DIR=mi-archivo 无法解析到任何位置，服务现在会记录 is not a directory … Archive fallback stays off，而不是悄无声息地忽略问题。DATOSGOBDO_CACHE_DIR 也一样；save_query_to_csv 的 dest 参数同样如此，它会直接拒绝相对路径。
• 在终端中运行 uv run datosgobdo-mcp 时情况不同——此时工作目录就是运行命令的位置，shell 环境变量也会生效。只在客户端中出现的错误，通常就是这个原因。

对于 Claude Code，请使用 -e 传递变量：claude mcp add datosgobdo -e DATOSGOBDO_NETGUARD=strict -- uvx dominican-open-data-mcp。

托管模式（实验性）

DATOSGOBDO_TRANSPORT=streamable-http 会通过 HTTP 提供 MCP 服务（无状态，支持水平扩展），而不是使用 stdio。在此模式下，save_query_to_csv 和 clear_cache 会被禁用——它们会访问服务的文件系统和共享缓存；缓存统计信息也不会包含服务路径。

此模式下，日志需要由你自行处理。 使用 stdio 时，客户端会捕获服务的 stderr 并将其写入文件，供你通过 tail 查看；而使用 Streamable HTTP 时则不会。请自行收集 stderr，或接入 OpenTelemetry，并使用常规 HTTP 工具（curl、浏览器的 Network 面板）检查请求和 SSE 流。

变量	默认值	含义
DATOSGOBDO_TRANSPORT	stdio	托管部署使用 streamable-http。
DATOSGOBDO_HOST / DATOSGOBDO_PORT	127.0.0.1 / 8000	HTTP 绑定地址。
DATOSGOBDO_DUCKDB_MEMORY	2GB	每个连接的 DuckDB 内存上限。
DATOSGOBDO_DUCKDB_THREADS	4	DuckDB 线程数上限。
DATOSGOBDO_QUERY_TIMEOUT	0（关闭）	中断 DuckDB 运行前的墙钟时间（秒）。适用于 query_resource SQL，以及将刚下载的文件转换为 Parquet 的过程。

14. 答案会告诉你哪些信息

当服务不得不执行调用方未要求的操作时，响应中会出现三个字段。每个字段存在的原因都是：用于审计的工具不应悄悄掩盖数据缺陷。

numeric_coercion——以文本形式存储的列被读取为数字。 此目录中最常见的缺陷是：在 2026-08-08 的普查中，可读取的 540 个资源里有 93 个资源将数字列存为文本，因为少数单元格写着 N/A 或 #REF!，就足以让整列工资数据变成非数字。aggregate_resource、quantiles_resource 和 detect_outliers_resource 会在每个值可解析的情况下将此类列作为数字读取，并报告为此付出的代价：

"numeric_coercion": [{
  "column": "SUELDO BRUTO (RD$)", "coerced": true,
  "values_used": 21469, "values_excluded": 37,
  "excluded_values": [{"value": "N/A", "count": 21}, {"value": "#REF!", "count": 16}]
}]

引用总数之前，先查看 values_excluded。 如果某列可解析的比例低于 90 %，就会保留为文本，并说明原因，而不是根据任意一部分行来回答有关某项指标的问题。count 和 count_distinct 从不进行强制转换。

linked_files —— URL 返回的是网页，而网页链接到了数据文件。

目录中的 37 个资源返回的是网页，而不是文件。如果某个链接文件明显符合请求，就会获取该文件，并由 cache.resolved_from 记录 {page, followed}——你请求了一个 URL，却收到了另一个 URL 中的数据；回复会说明这一点，而不会隐瞒。如果有多个候选文件无法区分，它们会以 linked_files 的形式连同名称和评分一并返回，供你选择并再次调用。此目录中同时存在名为 clss.csv 和 xls.csv 的文件；在两者之间猜测，就等于凭空捏造。

网页通过 JavaScript 打开的文件也算作链接文件。有些门户只在 onclick="window.location.assign('…')" 中放置地址——Tribunal Constitucional 就是这样发布全部三种格式的——因此，只读取锚点会报告“此网页上没有数据文件”，但任何人都可以一键从该网页下载文件。

cache.format_corrected —— 目录中声明的格式有误，回复会说明格式被更正为何种格式。

目录中的格式是对文件的声明，而 1,595 个同类资源中有 83 个的声明有误，两个方向的错误都有：注册为 CSV 的电子表格，以及注册为 ODS 的 CSV。容器类型根据内部内容识别——ODS 看 mimetype 成员，XLSX 看工作簿组件——绝不会只凭文件签名判断，因为两者开头都是 PK。只包含一个数据文件的 ZIP 会被解压，并由 detected_from 标明其成员；包含多个文件的 ZIP 则保持原样，因为决定哪个才是“数据文件”就等于凭空捏造。source_sha256 始终针对门户提供的原始内容计算，因此即使解析的是归档文件中的内容，也可以通过重新下载来进行比对。

无法读取 2007 年之前的 .xls（BIFF/OLE2）文件，系统会明确说明这一点，并告知应向发布方索取什么格式。这是目录中支持情况最差的格式：22 个资源中只有 12 个可读取。

关于 save_query_to_csv 写入的 CSV 的说明。 文件采用 UTF-8 编码，使用 CRLF 换行，且不带 BOM。这是正确的 CSV，但在西班牙语 Windows 上，Excel 仍会将其作为 cp1252 打开，并把 Año 显示成 Año，因为没有 BOM 时 Excel 就会这样假定。文件没有问题；问题在于大多数用户会用 Excel 打开它。可通过两种方式解决：使用 Excel 的 Data → From Text/CSV 打开，它会询问编码；或者使用 LibreOffice，它能检测 UTF-8。在 Windows 11 上测得：4E 6F 6D 62 72 65 2C 41 C3 B1 6F 0D — Nombre,Año\r，为有效的 UTF-8，不含 EF BB BF。

cache.provenance —— 答案来自归档副本，而不是门户。

政府链接会失效：2026-08-08 的普查发现，已有 15 个资源 URL 失效，还有 98 家机构的网站拒绝程序化访问，因此你今天引用的数字明年可能就无法核查。将 DATOSGOBDO_ARCHIVE_DIR 指向一个包含 manifest.json 及其 Parquet 文件的目录；如果无法访问门户，服务就会使用归档副本作答。此功能默认关闭，始终优先尝试门户，且回复始终会明确说明——cache.provenance 会记录抓取日期、sha256、许可证，以及未使用原始来源的原因。如果工具悄悄把昨天的副本当作今天的数据返回，就无法再用于审计了。 归档文件只能保存已下载的内容，因此不包含门户拒绝提供的资源。这是很自然的假设，但它是错的。

变量	默认值	含义
DATOSGOBDO_ARCHIVE_DIR	未设置（关闭）	包含 manifest.json 和 Parquet 副本的目录的绝对路径，用作回退。

在客户端的 env 块中设置此变量（见§13），并使用绝对路径。如果目录不存在，服务会记录警告并关闭回退功能——不会假装已启用。

15. 安全性和环境变量

完整的策略、威胁模型和报告流程：SECURITY.md。简要说明：

• 对门户只读。 不进行身份验证，不调用 package_create 或 resource_create。唯一会修改数据的工具是 clear_cache，且只作用于本地缓存。
• 两个注入入口，均已封堵。 用户输入的值进入 CKAN fq 筛选器前会经过 Solr 转义；传入 DuckDB 的每个列标识符都会先通过白名单正则表达式和用于拦截注释及终止符子串的黑名单检查，然后再用双引号括起来。
• query_resource 在沙箱中运行。 除了验证语句为单条只读 SELECT/WITH 外，资源会先被物化到内存表中，随后在用户 SQL 执行前设置 enable_external_access=false 和 lock_configuration=true——因此 DuckDB 表函数（read_text、read_csv、glob 等）无法访问文件系统或网络。
• 对每次下载进行 SSRF 防护，包括初始 URL 和每次重定向：仅允许 http/https，且主机名解析出的每个地址都必须是全局可路由地址。云元数据地址（169.254.169.254）、环回地址、RFC-1918 地址、链路本地地址和 IPv6 ULA 均会被阻止。防护路径同时涵盖元数据 HEAD 探测和实际下载。
• 对远程获取的数据设置字节数上限（预览为 5 MB，分析为 100 MB），并以流式方式处理，以限制内存占用和解压炸弹风险。
• save_query_to_csv 要求目标路径为绝对 .csv/.tsv 路径，拒绝 .. 和系统路径，并使用 O_NOFOLLOW 写入。

变量	值	含义
DATOSGOBDO_NETGUARD	public-only（默认）/ strict / off	strict 将主机限制为 datos.gob.do 及其子域名；off 会禁用防护。
DATOSGOBDO_ALLOW_HOSTS	逗号分隔，支持 *. 通配符	由运维人员信任的主机——为指向其他 CKAN 门户的分支版本提供例外通道。

请在客户端的 env 块中设置这些变量，而不是在 shell 中——§13 展示了准确的 JSON 配置。stdio 服务只会继承环境变量中的有限子集，因此执行 export DATOSGOBDO_NETGUARD=strict 后，服务仍会使用默认防护模式。对此不会发出警告，因为从服务端来看，什么都没有发生。要检查实际模式：get_cache_stats 会通过 server.netguard_mode 报告当前生效的模式，客户端日志中的启动行也会记录生效模式。

默认设置不是主机白名单：正如§7所示，合法资源分布在 273 个部委网站、存储桶和 CDN 上。

**关于新增的基础功能：**这里的提示词是静态模板，参数会插入文本中——不会执行任何 I/O。资源仅用于只读读取门户元数据。两者都不会新增写入路径。

16. 架构

src/datosgobdo_mcp/
  server.py        MCPServer: 24 tools, 3 resources, 1 template, 6 prompts
  ckan.py          CKAN client: requests, Solr escaping, formatters, provenance
  analytics.py     DuckDB layer: typed query builders, coercion, SQL validation
  download.py      Capped streaming download, fetch headers, encoding detection
  cache.py         Parquet cache + index, keyed on source and parser build
  preview.py       Row-level preview parsers (CSV/TSV/XLSX/XLS/ODS/JSON)
  pagelink.py      Resolves a page URL to the data file it links
  archive.py       Archived-copy fallback with declared provenance
  reachability.py  check_resources: classifies why a URL cannot be read
  netguard.py      SSRF guard for URLs and every redirect hop
  models.py        Pydantic output models (typed outputSchema)
  gcp.py           Optional BigQuery/GCS pipeline tools

一个问题的处理过程

从“2024 年登记了多少辆车？”到得出答案，中间会发生什么。

flowchart TD
    Q["Your question"] --> M["The model picks tools"]
    M --> S["search_datasets<br/><small>ckan.py</small>"]
    S --> G["get_dataset<br/><small>ckan.py</small>"]
    G --> SC["get_resource_schema<br/><small>analytics.py</small>"]
    SC --> QR["query_resource<br/><small>analytics.py</small>"]
    QR --> A["Answer + source_sha256 + the SQL"]
    S -.-> CK["CKAN API<br/><i>metadata only</i>"]
    SC -.-> DL["The institution's server<br/><i>the actual file</i>"]
    style A fill:#E6F4EA,stroke:#34A853

前三个步骤读取目录。只有第四步会访问文件——而这是 CKAN 封装器在此处无法完成的步骤，因为此门户没有 DataStore（见§12）。

一个文件的处理过程

资源从 URL 到得出答案所经历的路径。每个菱形都代表审计真实目录时发现的缺陷，并非假设。

flowchart TD
    URL["Resource URL"] --> NG{"netguard<br/>is this address safe?"}
    NG -- no --> STOP["Refused"]
    NG -- yes --> CACHE{"Is it in the<br/>Parquet cache?"}
    CACHE -- yes --> SQL
    CACHE -- no --> DL["Download, capped at 100 MB<br/><small>download.py</small>"]
    DL --> HTML{"Is it a web page?"}
    HTML -- yes --> PL["pagelink: find the file<br/>the page links or opens"]
    PL --> SNIFF
    HTML -- no --> SNIFF{"Do the bytes match<br/>the declared format?"}
    SNIFF -- no --> FIX["Correct it and say so<br/><small>format_corrected</small>"]
    SNIFF -- yes --> ENC["Score the encoding<br/><small>A¤o → Año</small>"]
    FIX --> ENC
    ENC --> PQ["Parse to Parquet<br/>+ sha256 of the source"]
    PQ --> SQL["DuckDB runs the SQL"]
    SQL --> OUT["Answer + provenance"]
    style STOP fill:#FCE8E6,stroke:#EA4335
    style OUT fill:#E6F4EA,stroke:#34A853
    style FIX fill:#FEF7E0,stroke:#FBBC04

设计决策

• 选择 MCPServer，而非底层 SDK。 工具是用 @mcp.tool() 装饰的函数，并通过 Pydantic 定义类型：样板代码更少，还能自动验证参数。（在 SDK 2.0 之前，这个类名为 FastMCP。）
• 选择 DuckDB + Parquet，而非 pandas。 列式缓存、SQL 引擎、从磁盘流式读取。对于 94 MB 的工资数据，缓存预热后，分组聚合查询耗时不到 1 秒，内存占用也保持有界。
• 缓存键包含解析器构建版本——包括软件包版本和 DuckDB 版本，因为 DuckDB 的嗅探器决定列类型。解析器升级后，不得继续提供由旧版本推断出的类型。
• 没有 DataStore，因此由客户端解析文件。 请参阅 §12。这是其余架构决策的根本依据。
• 对编码进行评分，而不是猜测。 根据还原出的西班牙语内容为候选解码结果排序，而不是相信置信度数值——这解决了 A¤o 这样的线上乱码问题，本应为 Año。
• 通过流式解析 content.xml 来处理 ODS。 加载完整 DOM 会让一个 0.70 MB 的文件占用 0.41 GB RSS；ODS 约占本目录的三分之一，因此朴素方案无法接受。
• 将阻塞任务放到 asyncio.to_thread 中运行（ODS 转码、编码检测、Parquet COPY），避免长时间解析阻塞事件循环。
• 采用防御性截断。 部分机构为每个组织发布超过 5 KB 的长描述；在列表响应中将其截断至 300 个字符，避免一次调用耗尽数千个上下文令牌。
• 重新设计 list_recent_datasets。 CKAN 提供 recently_changed_packages_activity_list，但它返回未经填充的活动记录（{object_id: "uuid", activity_type: "changed package"}），模型无法解读。我们使用 package_search?sort=metadata_modified+desc，一次调用即可返回格式化后的数据集。
• 所有日志都写入 stderr，绝不通过协议发送。 根据 MCP 调试指南，stdio 服务绝不能写入 stdout，否则会破坏协议流。这里从未使用协议自身的日志通道（notifications/message）；截至规范版本 2026-07-28，该通道已弃用：规范现在建议使用 stderr。无需迁移——但不要通过添加协议日志来“改进”这一点。

技术栈

mcp（官方 Python SDK v2，MCPServer）· duckdb · httpx · openpyxl（只读流式 XLSX）· pydantic · 标准库 csv、json、xml.etree（流式 ODS）。

17. 实测限制

于 2026-08-08 针对整个目录进行实测——包含 1,056 个资源，每个数据集对应一个资源，测试通过真实 MCP 会话进行——而非估算。在 0.14.0 的格式支持更新后，于 2026-08-13 再次针对线上门户实测所有因本服务可控原因而无法读取的资源；对于网站拒绝访问和 4xx 响应则未重试，因为我们这边没有任何可能影响这些问题的改动。

并非所有已发布内容都能访问。 1,056 个资源中有 561 个可读取——普查时为 540 个，另有 0.14.0 恢复的 21 个，共计 82,490 行。恢复结果是精确值而非估算值，因此分类也随之变化：原先提供网页的 37 个资源中，有 19 个现在会解析到网页链接的文件，剩下 18 个；8 个无法读取的文件中，有 2 个现在可以解析，剩下 6 个。

原因	资源数	此服务能修复吗？
站点配置拒绝程序化下载	360，涉及 98 家机构	不能。从同一地址访问时，同一 CDN 后的另外 21 个政府主机都能正常为我们提供服务，因此这是单个站点的配置问题，而非我们的网络问题。
传输层失败（无法归因）	85	尚未确定
提供的网页上没有数据文件	18	不能——目录条目指向的是着陆页
链接失效	15	不能
文件无法读取	6	其中两个是 2007 年之前的 .xls 文件，需要新的读取器
源站无响应的 CDN	6	不能
门户错误	5	不能

561 + 495 = 1,056。360 个拒绝访问的资源不受这些改动影响，而且此服务的任何版本都无法改变这一点。

第二类恢复未计入上述数量，而且规模更大。 0.14.0 还会读取 11 个同级文件——这些是同一数据集的第二种或第三种格式，而该数据集的一个代表文件已计入统计——共计 846,388 行，其中包括 SeNaSa 的 ODS 文件中的 622,630 行，以及 MAP、MIVHED 和 MESCyT 以 JSON 发布的薪资和住房文件。它们有意排除在 561 之外：这项普查按每个数据集只计算一个资源，若将同级文件也计入，就会与一个从未将它们纳入的分母进行比较。实际意义是，CSV 无法读取的数据集现在可能可以通过另一种格式读取——§14 解释了这种情况发生时，cache.format_corrected 如何说明这一点。

已经确定的是：从测量所用的地址访问时，这些站点会拒绝对其开放数据进行程序化访问。尚未确定的是：在圣多明各使用浏览器的人是否会遭到拒绝。要进行这项测试，需要从多米尼加住宅网络环境进行访问，而这项测试尚未开展。

格式。 对于 CSV、XLSX 和 ODS，读取成功率都约为下载成功率的 93 %。在 0.14.0 之前，JSON 的表现远远最差——read_json_auto 会将这些门户实际发布的内容判定为格式错误，而这些内容通常是用元数据封装的记录数组，或是每行一个对象——2026-08-13 恢复的文件大多属于这类情况。旧版 .xls（BIFF/OLE2）仍然最难处理，完全无法读取：22 个中有 12 个无法读取。不会解析 PDF；只会公开其下载 URL。

大小。 download_resource_preview 的上限为 5 MB；分析工具的上限为 100 MB。单个值大于 16 MB 会超出 DuckDB 的限制，文件也就无法解析。

结构。 有 41 个资源在真实表头行上方放置了标题或徽标，导致自动检测的架构错乱——请使用 download_resource_preview 检查，并显式指定要选取的列。25 个资源返回了通用列名（column00、未命名）。93 个资源将数字保存为文本，处理方式和声明方法见§14。

不同格式之间可能存在差异。 在 528 个可比较的多格式数据集中，有 176 个的行数或列数不同；其中 11 个数据集的一种格式为空，而另一种格式包含完整表格。只读取一种格式，不能证明数据集实际包含哪些内容。

编码问题基本已解决：普查中的 540 个文件里，仍有一个文件的重音符号显示异常，而且该文件同时使用了两种代码页，因此不存在适用于它的单一正确读取方式。

无法从元数据读取数据的新鲜度。 所有 1,056 个数据集的 periodicidad 字段均为空。 Windows：于 2026-08-13 测试，以下是确切的测试范围。 Windows 11（build 26200）、Python 3.13、已开启 Defender 实时保护、非管理员账户。测试套件全部通过——518 项通过，5 项跳过，其中唯一跳过的是仅适用于 POSIX 的 O_NOFOLLOW 测试。编码端到端保持完整：以 cp1252 编码的工资数据返回时，Año 和 UREÑA 完好无损；200 个机构名称中有 135 个包含非 ASCII 字符，没有一个乱码；带重音符号和空格的路径也能正常使用。对一份包含 108,038 行的工资数据进行汇总，结果与独立的 Decimal 重新计算结果精确到美分。Defender 未造成可测量的影响——读取 40 MB 冷数据时，速度主要受发布方约 1 MB/s 的限制；多次原始下载之间的波动，比 Windows 与 macOS 之间的差异还大。

Windows 上仍未测试、因此不作保证的内容： 用户配置文件本身含重音符号（C:\Users\José Pérez\，在多米尼加共和国很常见——只测试了带重音符号的子文件夹）、重定向到 OneDrive 的 Downloads 文件夹、Claude Desktop 客户端（传输测试使用的是另一个 MCP 客户端）、Windows 安装在 C: 以外的驱动器上，以及前后对比测量 Defender 排除项的影响（这需要管理员权限）。缓存锁的 Windows 专用分支也尚未在 Windows 上运行测试：其重试策略已测试，但其中四行的 msvcrt 垫片尚未测试。

尚未测试，因此不作保证的内容： 在真实负载下托管的 streamable-http 传输、针对实时项目的 3 个 GCP 工具，以及超过 4 个进程的并发使用。

---

---

第 6 部分——开发

18. 开发、测试与 MCP Inspector

本地设置

git clone https://github.com/alcastaro/datos.gob.do-MCP-server.git
cd datos.gob.do-MCP-server
uv sync
uv run pytest          # hermetic by default: no network required

MCP Inspector

MCP Inspector 是 MCP 协议自带的开发工具。它直接使用 MCP 通信，因此能显示服务实际暴露的内容，中间不会经过模型——这是按协议本身的方式查看工具、资源、模板和提示词的最佳方式。需要 Node 22.19+，且不会永久安装任何内容：

# The published package — no clone needed
npx -y @modelcontextprotocol/inspector uvx dominican-open-data-mcp

它会打印一个包含一次性令牌的 URL。打开后可看到 4 个面板：

• 工具——全部 24 个工具及其架构。调用工具后可查看原始 structuredContent，包括 numeric_coercion、source_sha256 和 computation。
• 资源——3 个 URI 和 datosgobdo://dataset/{dataset_id} 模板，以及原始载荷。
• 提示词——6 个提示词及其参数，在内容传递给模型之前，会先渲染为展开后的文本。
• 监控——双向实时 JSON-RPC 流量。

在克隆的仓库中，scripts/inspector.sh 可封装以下两种情况：

./scripts/inspector.sh                                        # published package
./scripts/inspector.sh dist/dominican_open_data_mcp-*.whl     # a local build
./scripts/inspector.sh --cli --method tools/list --format json

本地构建路径需要使用该封装脚本：Inspector 会将服务器命令之后的所有内容都当作自己的标志，因此 uvx --from ./dist/….whl … 会因 --from 未传递给 uvx 而报错 Connection closed。

CLI 模式会以有意义的状态码退出——0 表示成功，3 表示需要身份验证，4 表示无法访问，5 表示工具返回错误——因此可直接接入 CI：

npx -y @modelcontextprotocol/inspector --cli uvx dominican-open-data-mcp \
  --method tools/list  --format json | jq -r '.result.tools[].name'
npx -y @modelcontextprotocol/inspector --cli uvx dominican-open-data-mcp \
  --method prompts/list --format json | jq -r '.result.prompts[].name'
npx -y @modelcontextprotocol/inspector --cli uvx dominican-open-data-mcp \
  --method resources/templates/list --format json

日志

Claude Desktop 会为每个服务写入一个日志文件，此外还会写入自己的日志：

tail -f ~/Library/Logs/Claude/mcp-server-datosgobdo.log   # macOS — this server
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log              # macOS — all servers + the client

type "$env:AppData\Claude\logs\mcp*.log"                  # Windows

服务会将启动信息（端点、传输方式、网络防护模式、归档开启或关闭）、缓存命中和未命中、页面→文件替换、可疑的解析结构、配置错误的环境变量、附带回溯信息的致命错误以及关闭信息全部写入 stderr，客户端会捕获这些内容。在 DATOSGOBDO_TRANSPORT=streamable-http 模式下则不会写入：请参阅 §13。

日志包含资源 URL、缓存键和目标路径。不包含任何凭据——服务不会持有门户的凭据——可选的 GCP 工具则通过你自己的 ADC 进行身份验证，且绝不会记录 ADC。

当问题出在客户端而非服务时，Claude Desktop 可以打开 Chrome DevTools：将 {"allowDevTools": true} 写入 ~/Library/Application Support/Claude/developer_settings.json，然后按 Cmd-Option-I。Console 面板会显示客户端错误，Network 面板则会显示消息负载和时间信息。

迭代

1. 提交更改并推送到 main。
2. 清除 uvx 缓存以强制刷新：uv cache clean dominican-open-data-mcp（缓存键基于发行包名称，而非二进制文件名称）。
3. 重启 MCP 客户端。

如需更快地迭代，可将客户端指向你的克隆版本：command: /path/to/clone/.venv/bin/datosgobdo-mcp。

根据实时 API 进行手动检查

uv run python -c "
import asyncio
from datosgobdo_mcp import ckan
print(asyncio.run(ckan.get_site_stats()))
asyncio.run(ckan.close_client())
"

19. 贡献、致谢、引用方式、许可证

贡献

欢迎提交拉取请求。以下方向尤其需要帮助：

• 表头检测。 41 个资源在实际表头行上方有横幅。在 XLSX 中，这可能导致整个文件无法读取：precios_productos_primera_necesidad（PROCONSUMIDOR）包含 890 行，所在工作表声明 dimension A1:K890，但由于单元格 A1 是标题，最终被识别为 1 列、0 行。CSV 版本可以恢复全部 890 行，但列名为 column00…column10。若能检测并跳过横幅，就能恢复真实数据。
• 跨格式核验。 对于提供多种格式的数据集，选择可信的格式，而不是直接采用列表中的第一种。
• JSON 解析，这是目前最薄弱的格式。
• 泛化 ckan_endpoint，让同一文件读取流程也能用于该地区其他未启用 DataStore 的门户。
• Windows 测试，目前尚无人负责。

致谢

由 Alberto Castillo Aroca（@alcastaro）开发，Juana Casique（@juanacasique）参与贡献。

数据由多米尼加国家机构通过 datos.gob.do 发布，该门户由 OGTIC 运营。

本项目受 datagouv-mcp（法国政府 Etalab）启发。对于启用了 DataStore 的 CKAN 门户，建议改用 ondata/ckan-mcp-server，它是参考实现——请参阅 §12。

引用方式

如果你在文章、报告、数据集或演讲中使用了此服务，或使用了通过此服务获取的数据，请注明引用。GitHub 的 “Cite this repository” 按钮会读取 CITATION.cff，并直接提供 APA 和 BibTeX 格式。

Castillo Aroca, A. (2026). dominican-open-data-mcp: an MCP server for datos.gob.do [Computer software]. OLDS — Observatorio Latinoamericano de Desarrollo Sostenible. https://github.com/alcastaro/datos.gob.do-MCP-server

这是请求，不是许可证条款：MIT 条款未作任何修改，因此这里的内容不会限制你的使用。引用之所以重要，另有原因——目录中的数据会附带说明（数值转换排除了哪些内容、哪些文件根本无法下载），引用能帮助读者找到这些说明。

也请引用发布数据的机构。 此服务负责读取数据，而非生成数据。每项数据都归属于发布它的多米尼加政府机构，get_dataset 会返回该机构的名称，正是为了方便引用。

许可证

MIT。请参阅 LICENSE。

通过此 MCP 访问的数据受各多米尼加机构在 datos.gob.do 上发布数据时所采用的许可证约束。已核验整个目录：1,020 个数据集采用 ODbL 许可证，15 个采用 CC-BY，6 个采用 PDDL，3 个采用其他公有领域条款，另有 12 个未声明任何许可证——这 12 个数据集不应被重新分发。

20. 隐私政策

全文：docs/PRIVACY.md · 西班牙语：docs/PRIVACIDAD.md · 联系方式：[email protected]

无账户、无凭据、无遥测。 服务端没有用户注册表，也不会向其作者发送任何信息。它读取的所有内容都是政府公开数据。

您的搜索词会离开您的设备。 搜索词会发送到 https://datos.gob.do/api/3/action，因为搜索就在该处执行——该门户由 OGTIC 运营，并受其自身条款约束。

连接目标。 一个目录 API（datos.gob.do）和 273 个不同的文件托管主机，因为各机构会在自己的站点上发布文件。根据 2026 年 8 月的普查数据（1,056 项资源，258 个机构）：1,033 项（97.8 %）托管在多米尼加域名下；23 项不在——9 项托管在 drive.google.com，10 项托管在 Microsoft SharePoint/Azure Blob/Office Online，2 项托管在 Firebase。读取其中任何一项，都意味着 Google 或 Microsoft 会看到该请求。完整清单。

存储内容。 下载的公开文件会缓存为 Parquet 格式（~/.cache/datosgobdo-mcp，达到大小上限后会清除，可通过 clear_cache 移除）。提示词、问题和结果绝不会被存储。save_query_to_csv 只会写入您指定的位置。

托管模式。 无账户，也不会记录提示词，但缓存位于临时容器磁盘上，运行日志会包含已获取的 URL，基础设施提供商会根据其自身政策处理连接元数据。此模式下会禁用文件系统工具。

公开数据集可能包含个人数据——例如工资表、员工名册。服务端既不会对这些数据进行补充，也不会交叉比对；相关责任由发布机构承担。