Ukrainian Stats MCP Server

🚀 ウクライナ統計MCPサーバー

このサーバーは、Model Context Protocol (MCP) を用いて、ウクライナ国家統計局（Державна служба статистики України）のSDMX API v3経由で、AIモデルにウクライナの統計データをシームレスに提供します。

✨ 主な機能

• 🇺🇦 公式のウクライナ政府統計データへのアクセス
• 📊 複数の統計分野（エネルギー、人口統計、貿易など）のサポート
• 🌐 双言語対応（ウクライナ語と英語）
• 🔍 柔軟なデータフィルタリングとクエリ機能
• 📈 包括的なメタデータ探索（データフロー、構造、コードリスト）
• ⚡ データ消費を容易にするための高速なXMLからJSONへの変換

📦 インストール

方法1: npmからのインストール（推奨）

MCPサーバーをインストールする最も簡単な方法は、npmを使用することです。

npm install -g ukrainian-stats-mcp-server

インストール後、Claude Desktopの設定に追加します。

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

Claude Desktopを再起動すると、サーバーを使用できるようになります！

⚠️ 重要提示

Linux/macOSでパーミッションの問題が発生した場合は、sudo npm install -g ukrainian-stats-mcp-server を使用するか、npmをユーザーディレクトリを使用するように設定する必要がある場合があります。

方法2: インストールスクリプトを使用したクイックインストール

ローカルにインストールする最も簡単な方法は、提供されているインストールスクリプトを使用することです。これらのスクリプトは、依存関係を自動的にインストールし、プロジェクトをビルドし、コマンドをグローバルに利用可能にします。

1. リポジトリをクローンする

git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server

2. インストールスクリプトを実行する

• Windows (PowerShell):

.\install.ps1

• Windows (Command Prompt):

install.bat

• Linux/macOS:

chmod +x install.sh
./install.sh

インストールスクリプトは以下のことを行います。

1. ✅ Node.jsのバージョン18以上がインストールされていることを確認
2. 📦 すべての依存関係をインストール
3. 🔨 プロジェクトをビルド
4. 🔗 コマンドをグローバルにリンク（ukrainian-stats-mcp をシステム全体で利用可能にする）

インストールスクリプトを実行した後、Claude Desktopの設定に追加します。

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

Claude Desktopを再起動すると、サーバーを使用できるようになります！

⚠️ 重要提示

Linux/macOSでパーミッションの問題が発生した場合は、sudo ./install.sh を実行するか、npmをユーザーディレクトリを使用するように設定する必要がある場合があります（スクリプトが指示を提供します）。

方法3: GitHubからのインストール

1. GitHubからnpmを介してグローバルにインストールする

npm install -g git+https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git

2. Claude Desktopの設定に追加する

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

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "ukrainian-stats-mcp"
    }
  }
}

3. Claude Desktopを再起動する - サーバーが使用可能になります！

方法4: ローカル開発用のインストール

1. リポジトリをクローンする

git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server

2. 依存関係をインストールする

npm install

3. プロジェクトをビルドする

npm run build

4. Claude Desktopの設定に追加する（絶対パスを使用）

{
  "mcpServers": {
    "ukrainian-stats": {
      "command": "node",
      "args": ["/absolute/path/to/ukrainian-stats-mcp-server/build/index.js"]
    }
  }
}

💻 使用例

利用可能なツール

1. list_dataflows

ウクライナ統計局から利用可能なすべてのデータフロー（データセット）をリストします。

• 目的: 利用可能な統計分野（エネルギー、貿易、人口統計など）を発見する。
• パラメーター:
  • detail (オプション): 詳細レベル - full, allstubs, または referencestubs（デフォルト: full）
• 例:

Please list all available dataflows from Ukrainian statistics.

2. get_dataflow

特定のデータフローに関する詳細情報を取得します。

• 目的: 特定のデータセットの構造とメタデータを理解する。
• パラメーター:
  • dataflow_id (必須): データフロー識別子（例: DF_SUPPLY_USE_ENERGY）
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）
• 例:

Get information about the DF_SUPPLY_USE_ENERGY dataflow.

3. get_data_structure

データセットのData Structure Definition (DSD) を取得します。

• 目的: データをクエリするために必要な次元、属性、および測定値を理解する。
• パラメーター:
  • dsd_id (必須): データ構造定義ID（例: DSD_SUPPLY_USE_ENERGY）
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）
  • references (オプション): 参照を含める - none, parents, children, descendants, all（デフォルト: descendants）
• 例:

Get the data structure for DSD_SUPPLY_USE_ENERGY.

4. get_concept_scheme

概念スキーム定義を取得します。

• 目的: 統計データで使用される概念を理解する。
• パラメーター:
  • concept_scheme_id (必須): 概念スキームID
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）

5. list_codelists

利用可能なすべてのコードリスト（制御語彙）をリストします。

• 目的: 次元（国、指標など）の利用可能な参照リストを発見する。
• パラメーター:
  • detail (オプション): 詳細レベル - full または allstubs（デフォルト: full）
• 例:

List all available codelists.

6. get_codelist

特定のコードリストとすべての値および翻訳を取得します。

• 目的: データをフィルタリングするために必要な次元の許可された値を理解する。
• パラメーター:
  • codelist_id (必須): コードリストID（例: CL_SUPPLY_USE_ENERGY_INDICATOR）
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）
• 例:

Get the codelist CL_SUPPLY_USE_ENERGY_INDICATOR with all values.

7. get_data

柔軟なフィルタリングで統計データを取得します。

• 目的: 実際の統計時系列データと観測値を取得する。
• パラメーター:
  • resource_id (必須): リソース/データフローID
  • context (オプション): コンテキストタイプ - dataflow, datastructure, provisionagreement（デフォルト: dataflow）
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）
  • key (オプション): ワイルドカード付きのデータキー（デフォルト: * すべてのデータ）
  • start_period (オプション): 開始期間（例: 2020-01）
  • end_period (オプション): 終了期間（例: 2023-12）
  • dimension_filters (オプション): 次元フィルターをオブジェクトとして（例: {"FREQ": "A", "INDICATOR": "ENERGY_PRODUCTION"}）
• 例:

Get annual energy data from DF_SUPPLY_USE_ENERGY for 2020 to 2023.

8. check_data_availability

データを取得せずに、利用可能なデータを確認します。

• 目的: 大規模なデータセットをクエリする前に、利用可能な次元と値を探索する。
• パラメーター:
  • resource_id (必須): リソース/データフローID
  • context (オプション): コンテキストタイプ（デフォルト: dataflow）
  • agency_id (オプション): 機関ID（デフォルト: SSSU）
  • version (オプション): バージョン（デフォルト: latest）
  • key (オプション): ワイルドカード付きのデータキー（デフォルト: *）
• 例:

Check data availability for DF_SUPPLY_USE_ENERGY.

一般的な使用ワークフロー

ワークフロー1: 新しいデータセットの探索

1. データフローをリストする - 興味深いデータセットを見つける

List all dataflows

2. データフローの詳細を取得する - データセットに含まれる内容を理解する

Get dataflow DF_SUPPLY_USE_ENERGY

3. データ構造を取得する - 次元と属性を確認する

Get data structure DSD_SUPPLY_USE_ENERGY

4. コードリストを取得する - 次元の許可された値を確認する

Get codelist CL_SUPPLY_USE_ENERGY_INDICATOR

5. 適切なフィルターでデータを取得する

Get data from DF_SUPPLY_USE_ENERGY for 2020-2023

ワークフロー2: 迅速なデータ取得

すでにデータフローIDがわかっている場合:

Get energy supply and use data from DF_SUPPLY_USE_ENERGY for the last 3 years

AIは適切なツールを使用してデータを取得します。

📚 ドキュメント

データ形式

すべてのレスポンスは、元のSDMX XMLレスポンスから変換されたJSON形式で返されます。JSON構造は、属性が @_ で始まるSDMX標準に従います。

API情報

このMCPサーバーは、以下のSDMX API v3を使用しています。

• APIドキュメント: https://stat.gov.ua/uk/development-api/sdmx-api-v3
• 例: https://stat.gov.ua/uk/development-api/step-by-step-example
• ベースURL: https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0

トラブルシューティング

Claude Desktopにサーバーが表示されない場合

1. claude_desktop_config.json のパスが正しいことを確認する
2. npm run build でプロジェクトをビルドしたことを確認する
3. Claude Desktopを再起動する
4. Claude Desktopのログを確認してエラーを確認する

APIリクエストが失敗する場合

• ウクライナ統計APIにはレート制限がある場合があります。
• 一部のデータセットは一時的に利用できない場合があります。
• stat.gov.uaへのネットワーク接続が必要です。

XML解析エラーが発生する場合

XML解析エラーが発生した場合は、APIレスポンス形式が変更された可能性があります。これを問題として報告してください。

開発

プロジェクト構造

stat-mcp/
├── src/
│   ├── index.ts              # メインのMCPサーバーエントリポイント
│   ├── api-client.ts         # ウクライナ統計APIクライアント
│   └── tools/
│       ├── dataflows.ts      # データフローツール
│       ├── data-structures.ts # DSDと概念スキームツール
│       ├── codelists.ts      # コードリストツール
│       └── data.ts           # データ取得ツール
├── build/                    # コンパイルされたJavaScript（生成される）
├── package.json
└── tsconfig.json

開発モードでの実行

# ウォッチモード - 変更時に自動再構築
npm run watch

# 別のターミナルで
node build/index.js

📄 ライセンス

MIT

コントリビューション

コントリビューションは歓迎されます！問題やプルリクエストを自由に提出してください。

お問い合わせ

ウクライナ統計APIに関する質問は、公式ドキュメント https://stat.gov.ua/uk/development-api/ を参照してください。