# MCP Сервер Статистики України
> [🇬🇧 English version](./README.md)
Model Context Protocol (MCP) сервер, який надає моделям штучного інтелекту безперешкодний доступ до української статистичної інформації від Державної служби статистики України через їх SDMX API v3.
## Можливості
- 🇺🇦 Доступ до офіційної державної статистики України
- 📊 Підтримка багатьох статистичних галузей (енергетика, демографія, торгівля тощо)
- 🌐 Двомовна підтримка (українська та англійська)
- 🔍 Гнучка фільтрація та запити даних
- 📈 Комплексний огляд метаданих (потоки даних, структури, довідники)
- ⚡ Швидке перетворення XML в JSON для зручного використання даних
## Встановлення
### Метод 1: Встановлення з npm (Рекомендовано)
Найпростіший спосіб встановлення MCP сервера - через npm:
```bash
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`
```json
{
"mcpServers": {
"ukrainian-stats": {
"command": "ukrainian-stats-mcp"
}
}
}
```
Перезапустіть Claude Desktop і сервер готовий до використання!
> **Примітка**: На Linux/macOS, якщо виникнуть проблеми з дозволами, можливо, знадобиться використати `sudo npm install -g ukrainian-stats-mcp-server` або налаштувати npm для використання користувацької директорії.
### Метод 2: Швидке Встановлення за Допомогою Скриптів Встановлення
Найпростіший спосіб локального встановлення - використання наданих скриптів встановлення. Ці скрипти автоматично встановлюють залежності, збирають проект та роблять команду глобально доступною.
1. **Клонуйте репозиторій**:
```bash
git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server
```
2. **Запустіть скрипт встановлення**:
**Windows (PowerShell)**:
```powershell
.\install.ps1
```
**Windows (Командний рядок)**:
```cmd
install.bat
```
**Linux/macOS**:
```bash
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`
```json
{
"mcpServers": {
"ukrainian-stats": {
"command": "ukrainian-stats-mcp"
}
}
}
```
Потім перезапустіть Claude Desktop і сервер готовий до використання!
> **Примітка**: На Linux/macOS, якщо виникнуть проблеми з дозволами, можливо, знадобиться запустити `sudo ./install.sh` або налаштувати npm для використання користувацької директорії (скрипт надасть інструкції).
### Метод 3: Встановлення з GitHub
1. **Встановіть глобально через npm з GitHub**:
```bash
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`
```json
{
"mcpServers": {
"ukrainian-stats": {
"command": "ukrainian-stats-mcp"
}
}
}
```
3. **Перезапустіть Claude Desktop** - Сервер готовий до використання!
### Метод 4: Локальне Встановлення для Розробки
1. **Клонуйте репозиторій**:
```bash
git clone https://github.com/VladyslavMykhailyshyn/ukrainian-stats-mcp-server.git
cd ukrainian-stats-mcp-server
```
2. **Встановіть залежності**:
```bash
npm install
```
3. **Зберіть проект**:
```bash
npm run build
```
4. **Додайте до конфігурації Claude Desktop** (використовуйте абсолютний шлях):
```json
{
"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
```
### Запуск у Режимі Розробки
```bash
# Режим спостереження - автоматична перебудова при змінах
npm run watch
# В іншому терміналі
node build/index.js
```
## Ліцензія
MIT
## Внесок
Внески вітаються! Будь ласка, не соромтеся подавати проблеми або pull-запити.
## Контакти
З питань про API української статистики відвідайте офіційну документацію на https://stat.gov.ua/uk/development-api/
