npm package: @iflow-mcp/vladyslavmykhailyshyn-ukrainian-stats-mcp-server
Description: MCP server providing access to Ukrainian statistical data via SDMX API
Author: Vladyslav Mykhailyshyn
Latest version: 1.0.0

# 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/