# Pyro Storefront MCP Server 🎆

[![npm version](https://img.shields.io/badge/mcp-v1.0.0-blue.svg)](https://github.com/pyroua/pyro-storefront-mcp)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-purple.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Офіційний клієнтський MCP-сервер (Model Context Protocol)** для інтернет-магазину піротехніки та салютів **[pyro.ua](https://pyro.ua)**.

Дозволяє автономним ІІ-агентам (**Claude Desktop, Cursor, Cline, Windsurf, ChatGPT Desktop**) підбирати феєрверки за технічними характеристиками (калібр, кількість пострілів, тривалість, бюджет), перевіряти складські залишки, знаходити найближчі відділення і поштомати **Нової Пошти** та безпечно оформляти замовлення з миттєвим онлайн-чекаутом через **Monobank**.

---

## ⚡ Швидке підключення (1-Click Run)

Сервер повністю автономний, зібраний у єдиний виконуваний бандл і не потребує ручного встановлення залежностей.

### 🟣 1. Claude Desktop
Додайте в конфігураційний файл `claude_desktop_config.json`:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pyro-storefront": {
      "command": "npx",
      "args": ["-y", "github:pyroua/pyro-storefront-mcp"]
    }
  }
}
```

### 🔵 2. Cursor / Windsurf
Додайте в `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "pyro-storefront": {
      "command": "npx",
      "args": ["-y", "github:pyroua/pyro-storefront-mcp"]
    }
  }
}
```

---

## 🛠️ Доступні інструменти (Tools)

| Інструмент | Опис |
|:---|:---|
| `search_fireworks` | Пошук піротехніки за бюджетом, калібром (мм), кількістю пострілів та ключовими словами |
| `get_firework_details` | Детальні ТТХ товару: опис, фото, відео роботи, безпечна дистанція, інструкція |
| `check_stock_availability` | Пакетна перевірка залишків на складі та розрахунок підсумкової вартості |
| `search_delivery_branches` | Пошук відділень і поштоматів **Нової Пошти** в обраному місті України |
| `create_order` | Оформлення роздрібного замовлення з генерацією захищеного посилання на оплату Monobank |
| `track_order` | Перевірка статусу замовлення та ТТН за номером замовлення та 4 останніми цифрами телефону |

---

## 💬 Приклади запитів для вашого AI-асистента

* *«Підбери салют на день народження до 3500 грн, від 30 мм калібру, не менше ніж на 30 пострілів. Покажи відео та ціну.»*
* *«Знайди поштомати Нової Пошти у Києві біля станції метро Мінська.»*
* *«Оформи замовлення на салют №508 на ім'я Ігор Шульга (+380501234567) з доставкою до поштомату №1263 у Києві. Мені є 18 років.»*
* *«Який статус мого замовлення №72901? Мій номер закінчується на 4567.»*

---

## 🛡️ Безпека та захист даних (Enterprise Gold Standard)

1. **DLP & Нульовий витік комерційної таємниці:** Сервер має сувору ізоляцію від внутрішніх систем. Собівартість, маржа та дані постачальників недоступні клієнтському MCP.
2. **Захист від перебору (Anti-Enumeration):** Метод `track_order` вимагає обов'язкового збігу останніх 4 цифр телефону. Номери телефонів у відповідях маскуються (`+380 50 *** ** 67`).
3. **Age Gate (18+):** Замовлення створюються виключно за умови явної підтвердженої згоди клієнта про досягнення повноліття (`confirmed_legal_age: true`).
4. **Ідемпотентність:** Запобігання повторним списанням та дублюванню замовлень завдяки `Idempotency-Key`.

---

## 💻 Локальна розробка

```bash
# Клонування репозиторію
git clone https://github.com/pyroua/pyro-storefront-mcp.git
cd pyro-storefront-mcp

# Встановлення залежностей
npm install

# Збірка самодостатнього бандла
npm run bundle

# Локальний запуск
node dist/index.js
```

---

## 📄 Ліцензія

MIT License © 2026 [IT1.TEAM](https://it1.team) / [pyro.ua](https://pyro.ua). Всі права захищені.