Ukrainian Stats MCP Server

🚀 烏克蘭統計MCP服務器

這是一個模型上下文協議（MCP）服務器，可讓AI模型通過烏克蘭國家統計局（Державна служба статистики України）的SDMX API v3無縫訪問烏克蘭統計數據。

🚀 快速開始

本服務器能助力AI模型便捷訪問烏克蘭官方統計數據。你可按需選擇以下安裝方式，完成安裝並配置到Claude Desktop後，重啟Claude Desktop即可使用。

✨ 主要特性

• 🇺🇦 可訪問烏克蘭政府官方統計數據。
• 📊 支持多個統計領域（能源、人口統計、貿易等）。
• 🌐 提供雙語支持（烏克蘭語和英語）。
• 🔍 支持靈活的數據過濾和查詢。
• 📈 可全面探索元數據（數據流、結構、代碼表）。
• ⚡ 能快速將XML轉換為JSON，便於數據使用。

📦 安裝指南

方法一：通過npm安裝（推薦）

通過npm安裝MCP服務器是最簡便的方式：

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配置為使用用戶目錄。

方法二：使用安裝腳本快速安裝

使用提供的安裝腳本可在本地輕鬆完成安裝。這些腳本會自動安裝依賴項、構建項目，並使命令全局可用。

1. 克隆倉庫：

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

2. 運行安裝腳本：

• Windows (PowerShell)：

.\install.ps1

• Windows (命令提示符)：

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配置為使用用戶目錄（腳本會提供相應說明）。

方法三：從GitHub安裝

1. 通過npm從GitHub全局安裝：

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 - 服務器即可使用！

方法四：本地開發安裝

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

獲取數據集的數據結構定義（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. 列出數據流 以查找感興趣的數據集

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

流程二：快速數據檢索

如果你已經知道數據流ID：

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

AI將使用適當的工具來獲取數據。

📚 詳細文檔

數據格式

所有響應均以JSON格式返回，由原始的SDMX XML響應轉換而來。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響應格式發生了變化。請將此問題作為一個issue進行報告。

開發

項目結構

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許可證。

貢獻

歡迎貢獻代碼！請隨時提交issue或pull request。

聯繫

有關烏克蘭統計API的問題，請訪問官方文檔：https://stat.gov.ua/uk/development-api/