datos.gob.do-MCP-server

English · Español

---

datosgobdo-mcp

ドミニカ共和国の公共データについて AI アシスタントに質問し、政府のどのファイルに基づく回答なのかをたどれます。

これは、ドミニカ共和国の公式オープンデータポータルである datos.gob.do 向けの Model Context Protocol サーバーです。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 はリファレンスと技術的な詳細です。同じ内容を手順形式で読みたい場合は、チュートリアル（Español）をお読みください。

---

目次

パート 1 — まずはこちらから（技術的な知識は不要です）

1. これは何か、わかりやすく説明
2. クイックスタート
3. 6 つのガイド付きプロンプト — /empezar_aqui から開始
4. 質問できること
5. 数値を引用する前にお読みください

パート 2 — MCP を理解する（学習編）

6. MCP とは？ ツール、リソース、プロンプト
7. datos.gob.do とは？

パート 3 — このサーバーが提供するもの

8. ツール（24 個、追加で 3 個は任意）
9. リソース（3 個）とリソーステンプレート 1 個
10. プロンプト（6 個）
11. どのプリミティブを使うか

パート 4 — このサーバーが存在する理由

12. ほかの CKAN MCP サーバーとの比較

パート 5 — 技術リファレンス

13. インストールとクライアント設定
14. 回答が示す情報
15. セキュリティと環境変数
16. アーキテクチャ
17. 測定された制限事項

パート 6 — 開発

18. 開発、テスト、MCP Inspector
19. コントリビューション、謝辞、引用方法、ライセンス
20. プライバシーポリシー

---

---

パート 1 — まずはこちらから

1. これは何か、簡単に言うと

ドミニカ共和国政府は、公共部門の給与、予算執行、病院の活動、移民の流れ、調達契約、電力損失、森林火災など、何千ものファイルを公開しています。すべて公開情報です。それでも、読む人はほとんどいません。266 の機関のうちどこが何を公開したのかを把握し、ファイルを見つけ、3 行目に見出しがあるスプレッドシートをダウンロードし、その後どうすればよいか知っていなければならないからです。

このサーバーが、その一連の作業を AI アシスタントに任せます。自分の言葉で質問するだけです。アシスタントがデータセットを見つけ、機関のサーバーからファイルをダウンロードし、列を把握して合計や平均を計算し、情報の出所と、対象から除外せざるを得なかったものを添えて回答します。

最初に知っておくとよいことが 3 つあります。これらが、このプロジェクト全体の設計に関わっています。

• 読み取り専用です。 ここからポータルの内容を変更したり、何かを公開したりすることはできません。ログインもパスワードも不要です。
• アシスタントと一緒に、あなたのコンピューター上で動作します。 質問がこのプロジェクトのサーバーを経由することはありません。
• データに問題がある場合は、そのことを伝えます。 カタログのおよそ半分は、プログラムからダウンロードできません。ツールは数値を捏造せず、その事実を伝えます。これは、末尾に小さく添える注意書きではなく、設計の根幹です。

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 はシェルの PATH を読み取りません。その後、Claude Desktop を完全に終了して（macOS ではウィンドウを閉じるだけでなく Cmd+Q を押して）、再度起動します。Settings → Developer に datosgobdo が実行中と表示されているはずです。

これで必要な作業は完了です。あとからネットワークガードやキャッシュディレクトリなどの設定を変更する場合は、シェルではなく、このファイル内の "env" ブロックに記述します。§13をご覧ください。

Claude Code。 1 行で設定できます。

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

その他のクライアント。 同様に、dominican-open-data-mcp を引数として uvx をコマンドに登録します。MCP クライアントの一覧では、各クライアントがサポートする機能を確認できます。開発版、ローカルクローン、ホストモードなど、すべてのオプションについては§13をご覧ください。

3. 6 つのガイド付きプロンプト — /empezar_aqui から始めましょう

ツールが 24 個あるからといって、すべてを使う必要はありません。このカタログを初めて見る人には、給与、予算執行、公的投資が、このカタログが最も得意とする 3 つの分野だとは分かりようがありません。

そのため、このサーバーには 6 つのプロンプト が用意されています。カタログ全体を監査して初めて身につく知識を反映した、すぐに使える質問です。Claude Code と Claude Desktop では、スラッシュコマンドとして表示されます。次のように入力してください。

/empezar_aqui

するとアシスタントがポータルについて紹介し、得意な分野を説明したうえで、次に尋ねられる具体的な質問を 3 つ提案し、ダウンロードできないものについて事前に注意を促します。

残りの 5 つには、それぞれ 1 つの引数を渡します。

プロンプト	渡すもの	機能
/empezar_aqui	—	ポータルの概要と、最初に試す 3 つの質問を紹介します。
/serie_temporal	トピック	年ごとの時系列を作成し、実際に対象となる期間を明示するとともに、年の列を測定値として扱うことを避けます。
/auditar_nomina	機関	公共機関の給与について合計、平均、給与分布を算出し、除外した行数とその理由を明示します。
/verificar_fuente	リソース URL	ファイルを利用する前に、対象範囲、出所、形式を確認します。
/explorar_institucion	機関	その機関が公開しているすべての情報を一覧にし、各ファイルの実際のダウンロード状況を示します。
/cruzar_fuentes	トピック	2 つのリソースを突き合わせ、単位、期間、結合の限界を明示します。

クライアントでプロンプトがスラッシュコマンドとして表示されない場合は、MCP クライアントディレクトリにある該当項目を確認してください。プロンプトのサポートはクライアントでは任意です。また、MCP Inspectorを使えば、いつでもプロンプトを表示して実行できます。

4. できること

スペイン語または英語で、自然な質問を入力できます。現在、次のような質問に対応しています。

datos.gob.do ポータルにはデータセットがいくつあり、どの機関が最も多く公開していますか？

予算に関する最も重要なデータセットを 5 つ見つけ、それぞれを公開している機関を教えてください。

司法府は給与にいくら支出していますか？

2026 年 4 月時点で、農業省の現職職員は何人ですか？雇用形態別に教えてください。

この最後の質問は、この分析レイヤーが何のためにあるのかをよく示しているので、少し詳しく見てみましょう。農業省の給与データは 826,000 行、94 MB の CSV で、会話に貼り付けるには大きすぎます。サーバーは一度ダウンロードして列指向キャッシュに変換し、グループ化集計で回答します。雇用形態は 6 種類で、職員数は約 8,915 人です。最初の呼び出しには約 14 秒かかりますが、同じファイルに関するそれ以降の質問には 0.5 秒未満で回答します。

過去 3 年間の FONDOMARENA の承認済み予算と執行済み予算を比較してください。

内務省の車両盗難データセットには、どのような列がありますか？

最終更新日が新しい順に、データセットを 10 件挙げてください。

役立つ可能性が高い人： スクレイパーを自作せずに済ませたいデータジャーナリスト、プログラムからのアクセスが必要な研究者、予算執行や調達を追跡する透明性向上団体、公共データを使ってプロトタイプを作る開発者、自機関がすでに公開している情報を確認する公務員、そして国が実際にどのように運営されているかに関心のあるすべての人。

5. 数値を引用する前にお読みください

このカタログには実際の不具合があり、測定されています。2026-08-08 に全体を対象として実施した調査では、実際の MCP セッションを通じて、各データセットにつき 1 リソース、合計 1,056 リソースを調べました。以下の 4 つの調査結果を踏まえて、この先の数値を読み取ってください。

カタログの約半分は、プログラムからダウンロードできません。 1,056 リソース中 561 件（53.1 %）は読み取り可能です。前回調査時の 540 件から増加しています。0.14.0 のフォーマット対応により 21 件を復旧し、2026-08-13 に稼働中のポータルで再測定しました。残りのリソースが読み取れない最大の原因は、このサーバーではなく、どのバージョンでも解決できません。98 の機関が提供する 360 リソースは、各機関がオープンデータとして公開しているファイルのプログラムによるダウンロードを拒否するサイト設定の背後にあります。同じアドレスから、同じ CDN を経由する他の 21 の政府ホストには通常どおりアクセスできます。そのため、原因はネットワークではなくサイトごとの設定です。さらに、リンク切れが 15 件、どのエンコーディングでも読み取れないファイルが 6 件あります。

複数の形式があるデータセットの 3 分の 1 は、形式間で内容に食い違いがあります。 形式を比較できた 528 データセットのうち、176 件で行数または列数が一致しません。たとえば、財務省の recaudaciones-sirite-2021-2025 は、CSV では 971,818 行、ODS では 197,338 行です。ODS をダウンロードした市民と CSV をダウンロードしたジャーナリストは、同じ公式データセットについて異なる数値を引用することになります。実務上のルール：合計値を公表する前に、複数の形式を確認してください。

数値がテキストとして保存されていることがよくあります。 この調査で読み取り可能だった 540 リソースのうち 93 件では、数値列がテキストとして保存されています。多くの場合、一部のセルに N/A や #REF! といった値が含まれているためです。ツールは、各値が数値として扱える場合はその列を数値として読み取り、その際に生じた影響を報告します。詳しくは§14をご覧ください。合計値を引用する前に、values_excluded を確認してください。

どのデータセットも、更新頻度を明示していません。 periodicidad フィールドは 1,056 件すべてで空です。「2018-2026」とラベル付けされたデータセットが先月更新されたのか、2 年前に更新が止まったのかは分かりません。実際にデータが存在する最後の期間から、鮮度を推測する必要があります。

これらは、カタログを使うべきでないという理由にはなりません。正確に引用すべき理由です。そのためのものが /verificar_fuente と、応答に含まれる自己説明フィールドです。

---

---

パート 2 — MCP を理解する

6. MCP とは？ ツール、リソース、プロンプト

Model Context Protocol は、Anthropic が作成し、現在は業界全体で採用されているオープン標準です。言語モデルを外部のデータや機能に接続するためのものです。アプリケーションごとに独自のプラグイン形式を考案する代わりに、モデルとやり取りするアプリ（クライアント。例：Claude Desktop）が、1 つのプロトコルを介して任意の数のサーバーと通信します。

サーバーは 3 種類のものを提供できます。この違いは、何かが使用されるときに誰が決めるのかを左右するため重要です。

プリミティブ	制御する側	内容	このサーバーでの例
ツール	モデル	モデルが呼び出せる、型付き引数を持つ関数です。いつ、何を使って呼び出すかはモデルが選びます。	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

点線が、この仕組みの要点です。ここであなたが開始するのはプロンプトだけです。 モデルがプロンプトを呼び出すことはなく、アプリケーションがツールを呼び出すこともありません。

このプロトコルでは、クライアント側のプリミティブであるサンプリング、エリシテーション、ルートも定義されていますが、このサーバーでは使用していません。

概念ガイド：ツール、リソース、プロンプト。自分で構築する場合は、サーバーを構築するから始め、このプロジェクトでの経験についてはチュートリアルのパート 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 は、宣言漏れではなく実態に即した宣言です。ツールの一覧は起動時に固定され、このサーバーのリソースにはサブスクリプションを利用する価値があるほど頻繁に変更されるものはありません。

2 つのバージョン番号について。 上記の仕様へのリンクは、現行の仕様である 2026-07-28 を指しています。サーバーがネゴシエートするのは 2025-11-25 で、0.15.0 で v2 SDK に移行しても変わりませんでした。定数を確認したのではなく、実際のハンドシェイクで測定しています。2026-07-28 では新しいハンドシェイク文字列は導入されていません。2025-11-25 は、v1 と v2 のどちらでも 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件）	1,056
機械可読	561（53.1 %）— 2026-08-08 の調査で540件、さらに0.14.0で21件を復旧
ダウンロードしてキャッシュした行数	調査で 13,371,601 行、さらに 82,490 行を復旧 — 調査対象外の関連ファイルには、さらに 846,388 行
datos.gob.do 自体でホストされているリソース	66 — 残りは 273 個の他のドメインにあります

この最後の行は、このプロジェクトの大半を左右する構造上の事実です。このポータルはリンクのカタログであり、リポジトリではありません。 各機関は自らのファイルをそれぞれのウェブサーバーに保存しているため、可用性、フォーマットの整備状況、アクセスルールは、ポータルの管理外にある273か所で決められています。

また、拡張機能の一覧に含まれていないものにも注目してください。ここには CKAN の DataStore がインストールされていません。 この事実だけで、このサーバーの仕組みがわかります。詳しくは§12をご覧ください。

このプロジェクトは datagouv-mcp（フランスの Etalab）に着想を得ていますが、datos.gob.do は udata ではなく CKAN を実行しているため、実装は独自のものです。

---

---

パート3 — このサーバーが公開するもの

8. ツール（24個、オプションで3個追加）

5つのカテゴリに分かれた、型付き関数です。データを生成するツール（分析、プレビュー、キャッシュ）は、ホストが結果を検証できるよう、型付きの outputSchema / structuredContent を返します。ナビゲーション用のメタデータツールは JSON を返します。ポータルにアクセスするすべてのツールには readOnlyHint: true、ネットワークにアクセスするツールには openWorldHint: true が注釈されています。

すべてのツールは1つのオブジェクトで応答します。 一覧取得ツールは、含まれる項目とその数を示します — {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）。2 回目以降の呼び出しは 1 秒未満で完了します。実測した中央値では、キャッシュによって約 44 倍高速化されます。

ツール	機能
get_resource_schema	列名、推定された型、サンプル値を取得します。集計を行う前の、手軽な事前調査に使います。
summarize_resource	自動プロファイルを実行します。行数、列ごとの null 数と一意の値の数、数値列の最小値・最大値・平均値、カテゴリ列の上位 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 キャッシュ統計と、サーバー自身の ID および有効なセキュリティモードを取得します。total_bytes はインデックスの使用量ではなく、ディスク使用量を表します。orphan_entries はインデックスに記録されていない Parquet ファイルの数です。キャッシュロックを取得できず、記録処理が失われた呼び出しや、記録前に終了したプロセスによって書き込まれたファイルが該当します。この値が 0 以外の場合、正常なキャッシュではなく、競合が発生していることを意味します。
clear_cache	ローカルの Parquet キャッシュを消去します。サーバー内で唯一の読み取り専用ではないツールです（destructiveHint: true）。ホストモードでは無効です。

カタログ

ツール	機能
list_organizations	データセット数とともに、公開機関を一覧表示します。
get_organization	1 つの機関の詳細（説明、データセット数、URL）を取得します。
list_groups	件数とともに、テーマ別カテゴリを一覧表示します。
list_tags	タグを一覧表示します。必要に応じて、プレフィックスで絞り込めます。

オートコンプリート

ツール	機能
autocomplete	データセット、機関、グループ、タグの部分的な名前から候補を特定します。ユーザーが名前の一部しか指定していない場合に使います。

GCP パイプライン（オプション）

pip install 'dominican-open-data-mcp[gcp]' でインストールします。Google Cloud ライブラリが存在すると、追加の 3 つのツールが自動的に登録され、ツール数は 27 になります。これらのツールを使うと、このサーバーを BigQuery パイプラインの取り込み側として利用できます。ここでデータを見つけて BigQuery に読み込み、その後、ローカルの DuckDB キャッシュでは実行できないデータセット間 JOIN を、Google 独自の BigQuery MCP でクエリします。

ツール	機能
load_resource_to_bigquery	リソース → Parquet キャッシュ → GCS アップロード → BigQuery 外部テーブル（既定、ETL なし）またはロードジョブ。
list_bigquery_exports	BigQuery データセット内のテーブルを一覧表示します。
get_bigquery_table_info	テーブルのスキーマ、行数、ソース URI を取得します。

各呼び出しでバケットを渡さずに済むよう、DATOSGOBDO_GCS_BUCKET を設定してください。プレビュー段階： この 3 つのツールは安定性の保証の対象外であり、稼働中のプロジェクトでの動作確認は行われていません。

9. リソース（3 件）とリソーステンプレート 1 件

リソースは URI で指定され、モデルから呼び出されるのではなく、アプリケーションによって読み取られます。ここでは、サイズが小さく安定していて、ツール呼び出しを費やすのが無駄な情報のために用意されています。3 件とも読み取り専用で、副作用はありません。

URI	種類	含まれる内容
datosgobdo://catalog/overview	application/json	データセット、機関、グループ、タグのポータル全体の合計。
datosgobdo://catalog/institutions	application/json	データセット数を含む、すべての公開機関。「どの機関か」を問い合わせる前に確認できます。
datosgobdo://guide/verification	text/markdown	数値を検証可能にする 4 つのフィールドと、それらが欠けている場合の対処方法。

最後の項目をあえてプロンプトではなくリソースにしているのは、何かを実行するための依頼ではなく、作業中にコンテキストとして参照できる価値のあるテキストだからです。

リソーステンプレートが 1 件あります。パラメーターを含む URI パターンなので、1 つの定義でカタログ内のすべてのデータセットを指定できます。

テンプレート	入力する値	返される内容
datosgobdo://dataset/{dataset_id}	データセット ID またはスラッグ	添付可能なコンテキストとして、そのデータセットのメタデータ。

例：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（必須）	2 つの情報源を結合する前に、単位、期間、結合の制約を明示すること。

呼び出し方。 Claude Code と Claude Desktop では、スラッシュコマンドとして呼び出します。例：/empezar_aqui、または /serie_temporal を入力し、尋ねられたらトピックを入力します。メニューに表示するクライアントもあります。Inspector の Prompts パネルには、それぞれのプロンプトが引数とともに一覧表示され、モデルに送信する前に展開後のテキストが表示されます。プロンプトの動作を正確に確認する最も確実な方法です。

11. どのプリミティブを使うか

したいこと…	使用するもの	理由
データに関する具体的な質問に回答する	通常の会話を通じてツールを使う	モデルがツールを選択して組み合わせます。
ゼロから始める、または厳密な手順に従う	プロンプト	注意点があらかじめ組み込まれた 6 つのワークフローがあります。
アシスタントに常時参照する背景情報を与える	リソース	一度添付すれば、ツール呼び出しも、選択のために消費するトークンも不要です。
1 つのデータセットをコンテキストとして固定する	リソーステンプレート	datosgobdo://dataset/{id}。
型指定されたツールでは対応できないことをする	query_resource	読み取り専用の SQL をサンドボックス内で実行します。最初の手段ではなく、最後の手段です。

---

---

第 4 部 — このサーバーが存在する理由

12. 他の CKAN MCP サーバーとの比較

CKAN は数百の政府ポータルを支えているため、汎用的な CKAN MCP サーバーを作るのは自然な発想であり、優れたアイデアでもあります。最も開発が進んでいるのは ondata/ckan-mcp-server（MIT、TypeScript、イタリアのデジタル庁である 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 エンドポイントもなく、リソースは1つも読み込まれていません。汎用的な CKAN MCP サーバーをここに接続すれば、メタデータは問題なく検索できますが、データの行を1行も読み取れません。これはサーバーの欠陥ではありません。CKAN ではこの拡張機能は任意であり、このポータルでは有効化されていないのです。

そのため、2つのプロジェクトは明確な境界で役割が分かれます。

	DataStore があるポータル	ファイルカタログであるポータル
データの場所	CKAN に読み込まれ、API からクエリ可能	273の機関のウェブサーバー上にあるファイル
読み取り方法	datastore_search_sql	ダウンロード、文字コードの判定、解析、キャッシュ、クエリ
最適なツール	ondata/ckan-mcp-server	このプロジェクト

このコードベースが CKAN API ラッパーより大きくなっているのは、すべて右側の列に対応するためです。復元できるスペイン語を基準にスコアリングする文字コード検出、メモリ使用量が約580倍になる全 DOM 読み込みを避けるストリーミング ODS 解析、パーサーのビルドをキーにした Parquet キャッシュ、除外した値を明示する数値変換、HTML を返す37件の 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 を構築して実行します。初回の実行には数秒かかりますが、2回目以降はすぐに起動します。

≤ 0.7.0 からアップグレードする場合： これらのリリースでは mcp>=1.9.0 に上限を設けず固定していました。MCP Python SDK 2.0（2026-07-28）で mcp.server.fastmcp のインポートパスが削除されたため、新規インストールは ModuleNotFoundError で失敗します。v2 SDK に対応し、mcp>=2.1,<3 を固定している 0.15.0 以降をインストールしてください。古いリリースを使い続けるには、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"
      }
    }
  }
}

シェルで export DATOSGOBDO_NETGUARD=strict を実行しても、サーバーには渡りません。 クライアントが起動する stdio MCP サーバーが引き継ぐ環境変数は、プラットフォームによって異なる一部の変数に限られます。MCP のデバッグに関するガイダンスにも明記されています。シェルで変数を設定しても、サーバーはデフォルトのモードで起動するため、制限されていると思い込んでしまいます。これはセキュリティ制御である DATOSGOBDO_NETGUARD について特に重要です（§15）。

同じ事実から生じる、バグを報告する前に知っておくべき点が 2 つあります。

• パスを値とする設定には、すべて絶対パスを使用してください。 クライアントが起動するサーバーの作業ディレクトリは未定義です。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 は挙動が異なります。 この場合、作業ディレクトリは実行した場所であり、シェルの環境変数も適用されます。クライアント経由でのみ発生するバグは、たいていこれが原因です。

Claude Code では、-e を使って渡します：claude mcp add datosgobdo -e DATOSGOBDO_NETGUARD=strict -- uvx dominican-open-data-mcp。

ホストモード（実験的）

DATOSGOBDO_TRANSPORT=streamable-http を設定すると、stdio の代わりに HTTP 経由で MCP を提供します（ステートレスで、水平スケーリングに対応します）。このモードでは、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 (off)	DuckDB の実行を中断するまでの経過時間（秒）です。query_resource の SQL と、ダウンロード直後のファイルを Parquet に変換する処理の両方が対象です。

14. 回答が自身について伝える情報

サーバーが呼び出し元の依頼にない処理を行う必要があった場合、応答に 3 つのフィールドが表示されます。監査に使われるツールが、データの欠陥を黙って取り繕うことがないよう、それぞれ設けられています。

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 は、3 つすべての形式をこの方法で公開しています。アンカーだけを読むと、ワンクリックで誰でもダウンロードできるページに対して「データファイルがありません」と報告してしまいます。

cache.format_corrected — カタログに記載された形式が間違っていた場合、返信でどの形式に修正したかを説明します。

カタログの形式はファイルについての申告ですが、関連する 1,595 件のリソースのうち 83 件では、スプレッドシートが CSV として、CSV が ODS として登録されるなど、どちらの方向にも誤りがあります。コンテナーの形式は、ODS の mimetype メンバーや XLSX のワークブック部分など、中身から特定します。両方とも PK で始まるため、シグネチャだけでは判定しません。データファイルが 1 つだけ含まれる ZIP は展開し、detected_from にメンバー名を記録します。複数のファイルが含まれる ZIP はそのままにします。どれが「データ」なのかを選ぶのは、事実の捏造になるためです。source_sha256 は常にポータルから提供されたファイルの内容を対象とするため、解析したデータがアーカイブ内のものでも、再ダウンロードしたファイルと照合できます。

2007 年より前の .xls（BIFF/OLE2）はまったく読み取れず、その旨と、公開元に何を依頼すべきかを伝えます。カタログ内で最も提供状態の悪い形式で、22 件中、読み取り可能なのは 12 件です。

save_query_to_csv が書き出す CSV に関する注意点です。 文字コードは UTF-8、改行コードは CRLF で、BOM はありません。これは正しい CSV ですが、スペイン語版 Windows の Excel では、BOM がないと cp1252 として開くため、Año が Año と表示されます。ファイルに問題はありません。このファイルを開く人の大半が使うツールに問題があります。対処法は 2 つあります。Excel の「データ → テキストまたは CSV から」で開けば文字コードを指定できます。または、UTF-8 を自動判定する LibreOffice を使ってください。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 の調査では、リソース URL のうち 15 件がすでに無効で、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 です。
• インジェクションの攻撃対象は 2 つあり、どちらも対策済みです。 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 ブロックに設定してください — 正確な JSON は §13 をご覧ください。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

最初の 3 つのステップではカタログを読み取ります。ファイルに触れるのは 4 つ目だけです。そして、このポータルには DataStore がないため（§12）、ここでは CKAN ラッパーでは実行できないステップです。

ファイルの流れ

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

設計上の決定

• 低レベル SDK ではなく MCPServer を採用します。 ツールは @mcp.tool() でデコレートした関数として定義し、Pydantic で型付けします。ボイラープレートが少なく、引数の検証も自動で行われます。（SDK 2.0 より前は、このクラスは FastMCP と呼ばれていました。）
• pandas ではなく DuckDB と Parquet を採用します。 列指向キャッシュ、SQL エンジン、ディスクからのストリーミングが可能です。94 MB の給与データでも、ウォーム状態ならグループ化集計が 1 秒未満で完了し、メモリ使用量も一定範囲に収まります。
• キャッシュキーにはパーサーのビルド情報を含めます — パッケージのバージョンと DuckDB のバージョンです。DuckDB のスニファーが列の型を決定するためです。パーサーをアップグレードした場合、古いパーサーが推論した型を提供してはなりません。
• DataStore がないため、ファイルはクライアント側で解析します。 §12 を参照してください。これは、残りのアーキテクチャの方針を決める唯一の判断です。
• エンコーディングは推測ではなく、スコアで判定します。 信頼度の数値に頼るのではなく、候補となるデコードを、復元できるスペイン語の内容に基づいて順位付けします。これは、Año が A¤o になるような、実際に発生している文字化けへの対策です。
• ODS は content.xml をストリーミングして解析します。 DOM 全体を読み込むと、0.70 MB のファイルで RSS が 0.41 GB に達しました。ODS はこのカタログのおよそ 3 分の 1 を占めるため、単純な方法では実用に耐えませんでした。
• ブロッキング処理は asyncio.to_thread で実行します （ODS の変換、エンコーディングの検出、Parquet の COPY）。長時間の解析でイベントループが停止することはありません。
• 防御的に切り詰めます。 一部の機関は組織ごとに 5 KB を超える説明を公開しています。リスト応答では長い説明を 300 文字に切り詰めるため、1 回の呼び出しでコンテキストのトークンを何千個も消費することはありません。
• list_recent_datasets の取得方法を変更しています。 CKAN が提供する recently_changed_packages_activity_list は、モデルが解釈できない未取得のアクティビティ（{object_id: "uuid", activity_type: "changed package"}）を返します。そこで package_search?sort=metadata_modified+desc を使い、整形済みのデータセットを 1 回の呼び出しで返します。
• すべてのログは 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 件のリソース（データセットごとに 1 件）を対象に、実際の MCP セッションで測定しました。推定値ではありません。このサーバー側で制御可能な理由により取得に失敗していたリソースはすべて、0.14.0 でフォーマット対応を行った後の 2026-08-13 に、ライブポータルで再測定しました。サイト側の拒否と 4xx は再試行していません。こちら側で、それらに影響する変更がなかったためです。

公開されているものすべてにアクセスできるわけではありません。 1,056 件中 561 件 のリソースを読み取れます。内訳は、調査で確認した 540 件と、0.14.0 で復旧した 21 件 で、合計 82,490 行です。復旧数は推定ではなく正確な値のため、内訳もそれに応じて変わります。ウェブページを返した 37 件のうち、19 件 はページがリンクしているファイルを取得できるようになり、残りは 18 件です。読み取り不能だったファイル 8 件のうち、2 件 は解析できるようになり、残りは 6 件です。

原因	リソース数	このサーバーで解決できますか？
サイト設定によりプログラムからのダウンロードが拒否される	98 機関で 360	いいえ。同じ CDN 配下のほかの政府機関のホスト 21 件は、同じアドレスから正常にデータを提供しています。そのため、原因はネットワークではなくサイトごとの設定です。
転送レベルで失敗（原因を特定できず）	85	確認できていません
データファイルのないウェブページを提供している	18	いいえ — カタログのエントリーがランディングページを指しています
リンク切れ	15	いいえ
読み取り不能なファイル	6	うち 2 件は 2007 年より前の .xls で、新しいリーダーが必要です
オリジンサーバーが応答しない CDN	6	いいえ
ポータルエラー	5	いいえ

561 + 495 = 1,056。360 件の拒否はこれらの影響を一切受けておらず、このサーバーではどのバージョンでも変更できません。

この件数に含まれていない、さらに大きな 2 つ目の復旧分があります。 0.14.0 は 11 件の関連ファイル も読み取ります。これは、1 データセットにつき 1 つだけ代表としてすでに集計されているデータセットの 2 つ目または 3 つ目の形式にあたり、846,388 行に相当します。その中には、SeNaSa の ODS に含まれる 622,630 行や、MAP、MIVHED、MESCyT が JSON で公開している給与および住宅関連ファイルも含まれます。これらを 561 件に含めていないのは意図的です。調査ではデータセットごとに 1 つのリソースを対象としており、関連ファイルを数えると、そもそも含まれていないものまで分母に加えることになるためです。実際には、CSV が読み取り不能なデータセットでも、別の形式なら読み取れる場合があります。そうなったときに cache.format_corrected がそれを示す仕組みについては、§14 で説明します。

確認されていること：測定に使用したアドレスから、これらのサイトが自らのオープンデータへのプログラムからのアクセスを拒否しています。確認されていないこと：サント・ドミンゴでブラウザーを使う人が拒否されるかどうかです。このテストにはドミニカ共和国の一般家庭用インターネット回線からの接続環境が必要ですが、まだ実施されていません。

形式。 CSV、XLSX、ODS はいずれも、ダウンロード可能なものの約 93 % を読み取れます。JSON は 0.14.0 以前、ほかの形式と比べて大きく劣っていました。read_json_auto は、ポータルが実際に公開している形式のファイルを不正な形式として拒否していました。それらは多くの場合、メタデータのエンベロープで囲まれたレコード配列、または 1 行ごとに 1 つのオブジェクトという形式です。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 ファイルで破損して見えます。このファイルは 2 つのコードページが同時に使われているため、どちらか一方の読み取り方だけでは正しく読み取れません。

メタデータから更新状況は読み取れません。 periodicidad は 1,056 件すべてのデータセットで空です。 Windows：2026-08-13 にテスト済みで、確認できた範囲は以下のとおりです。 Windows 11（ビルド 26200）、Python 3.13、Defender のリアルタイム保護が有効、標準ユーザーアカウントで実行しました。テストスイートはすべて成功し、518 件が合格、5 件がスキップされました。スキップされた 1 件は 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 クライアントで動作させました）、C: 以外のドライブへの Windows のインストール、そして管理者権限が必要な Defender の除外設定前後の測定です。キャッシュロックの Windows 専用ブランチも、まだ Windows での実行待ちです。再試行ポリシーはテスト済みですが、4 行の 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 と直接通信するため、間にモデルを挟まずに、サーバーが実際に公開している内容を確認できます。プロトコルから見えるツール、リソース、テンプレート、プロンプトを確認する最適な方法です。Node 22.19+ が必要で、永続的なインストールは不要です。

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

ワンタイムトークンを含む URL が出力されます。URL を開くと、4 つのパネルが表示されます。

• Tools — スキーマとともに 24 個すべてが表示されます。いずれかを呼び出して、numeric_coercion、source_sha256、computation を含む生の structuredContent を確認できます。
• Resources — 3 つの URI と datosgobdo://dataset/{dataset_id} テンプレートが生のペイロードとともに表示されます。
• Prompts — 6 つのプロンプトが引数とともに表示され、モデルに渡される前に展開後のテキストが表示されます。
• Monitoring — 双方向の 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 モードは意味のある終了コードを返すため、そのまま CI に組み込めます。0 は成功、3 は認証が必要、4 は到達不能、5 はツールがエラーを返したことを示します。

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 はサーバーごとに1つのログファイルを書き込み、独自のログファイルも書き込みます。

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）には、dimension A1:K890 と宣言されたシートに890行ありますが、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 の 「このリポジトリを引用」 ボタンは 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 が運営しています。

接続先。 1 つのカタログ API（datos.gob.do）と、273 の異なるファイルホストに接続します。各機関が独自のサイトでファイルを公開しているためです。2026 年 8 月の調査（1,056 件のリソース、258 機関）では、1,033 件（97.8 %）がドミニカ共和国のドメイン上にあります。23 件は該当しません。内訳は、drive.google.com 上の 9 件、Microsoft SharePoint／Azure Blob／Office Online 上の 10 件、Firebase 上の 2 件です。これらのいずれかを読み取ると、Google または Microsoft にリクエストが認識されます。全件の一覧。

保存されるデータ。 ダウンロードした公開ファイルは Parquet としてキャッシュされます（~/.cache/datosgobdo-mcp。サイズ上限に達すると削除され、clear_cache で消去できます）。プロンプト、質問、結果は保存されません。save_query_to_csv は、指定した場所にのみ書き込みます。

ホストモード。 アカウントやプロンプトのログ記録はありませんが、キャッシュは一時的なコンテナディスクに保存され、運用ログには取得した URL が含まれます。また、インフラストラクチャプロバイダーは、独自のポリシーに基づいて接続メタデータを処理します。このモードでは、ファイルシステムツールは無効です。

公開データセットには個人データが含まれる場合があります。給与データや職員名簿などです。サーバーがデータを追加情報で補完したり、相互参照したりすることはありません。責任を負うのは、公開元の機関です。