MCP Сервер Статистики України

🇬🇧 English version

Model Context Protocol (MCP) сервер, який надає моделям штучного інтелекту безперешкодний доступ до української статистичної інформації від Державної служби статистики України через їх SDMX API v3.

Можливості

• 🇺🇦 Доступ до офіційної державної статистики України
• 📊 Підтримка багатьох статистичних галузей (енергетика, демографія, торгівля тощо)
• 🌐 Двомовна підтримка (українська та англійська)
• 🔍 Гнучка фільтрація та запити даних
• 📈 Комплексний огляд метаданих (потоки даних, структури, довідники)
• ⚡ Швидке перетворення 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 (Командний рядок):

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. Встановіть глобально через 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 - Сервер готовий до використання!

Метод 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": ["/абсолютний/шлях/до/ukrainian-stats-mcp-server/build/index.js"]
    }
  }
}

Доступні Інструменти

1. list_dataflows

Отримати список усіх доступних потоків даних (наборів даних) від Держстату України.

Призначення: Дізнатися, які статистичні галузі доступні (енергетика, торгівля, демографія).

Параметри:

• detail (опціонально): Рівень деталізації - full, allstubs, або referencestubs (за замовчуванням: full)

Приклад:

Будь ласка, покажи всі доступні потоки даних української статистики

2. get_dataflow

Отримати детальну інформацію про конкретний потік даних.

Призначення: Зрозуміти структуру та метадані конкретного набору даних.

Параметри:

• dataflow_id (обов'язковий): Ідентифікатор потоку даних (наприклад, DF_SUPPLY_USE_ENERGY)
• agency_id (опціонально): ID агенції (за замовчуванням: SSSU)
• version (опціонально): Версія (за замовчуванням: latest)

Приклад:

Отримай інформацію про потік даних постачання енергії DF_SUPPLY_USE_ENERGY

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)

Приклад:

Отримай структуру даних для 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)

Приклад:

Покажи всі довідники

6. get_codelist

Отримати конкретний довідник зі всіма значеннями та перекладами.

Призначення: Зрозуміти дозволені значення для вимірів (необхідно для фільтрації даних).

Параметри:

• codelist_id (обов'язковий): ID довідника (наприклад, CL_SUPPLY_USE_ENERGY_INDICATOR)
• agency_id (опціонально): ID агенції (за замовчуванням: SSSU)
• version (опціонально): Версія (за замовчуванням: latest)

Приклад:

Отримай довідник CL_SUPPLY_USE_ENERGY_INDICATOR зі всіма значеннями

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"})

Приклад:

Отримай річні дані про енергію з DF_SUPPLY_USE_ENERGY за 2020-2023 роки

8. check_data_availability

Перевірити, які дані доступні, без їх завантаження.

Призначення: Дослідити доступні виміри та значення перед запитом великих наборів даних.

Параметри:

• resource_id (обов'язковий): ID ресурсу/потоку даних
• context (опціонально): Тип контексту (за замовчуванням: dataflow)
• agency_id (опціонально): ID агенції (за замовчуванням: SSSU)
• version (опціонально): Версія (за замовчуванням: latest)
• key (опціонально): Ключ даних з підстановочними знаками (за замовчуванням: *)

Приклад:

Перевір доступність даних для DF_SUPPLY_USE_ENERGY

Типові Робочі Процеси

Процес 1: Дослідження Нового Набору Даних

1. Отримати список потоків даних для пошуку цікавих наборів даних

   Покажи всі потоки даних

2. Отримати деталі потоку даних для розуміння вмісту набору даних

   Отримай потік даних DF_SUPPLY_USE_ENERGY

3. Отримати структуру даних для перегляду вимірів та атрибутів

   Отримай структуру даних DSD_SUPPLY_USE_ENERGY

4. Отримати довідники для перегляду дозволених значень вимірів

   Отримай довідник CL_SUPPLY_USE_ENERGY_INDICATOR

5. Отримати дані з відповідними фільтрами

   Отримай дані з DF_SUPPLY_USE_ENERGY за 2020-2023 роки

Процес 2: Швидке Отримання Даних

Якщо ви вже знаєте ID потоку даних:

Отримай дані про постачання та використання енергії з DF_SUPPLY_USE_ENERGY за останні 3 роки

ШІ використає відповідні інструменти для отримання даних.

Формат Даних

Усі відповіді повертаються у форматі JSON, перетворені з оригінальних XML відповідей SDMX. Структура 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

Внесок

Внески вітаються! Будь ласка, не соромтеся подавати проблеми або pull-запити.

Контакти

З питань про API української статистики відвідайте офіційну документацію на https://stat.gov.ua/uk/development-api/