MCP сервер Сільпо

MCP (Model Context Protocol) сервер для взаємодії з інтернет-супермаркетом Сільпо через ШІ-асистентів.

Можливості

🔍 Пошук товарів — за назвою або ключовими словами
📁 Категорії — перегляд усіх категорій товарів
🏷️ Акції — товари зі знижками
🛒 Кошик — додавання, видалення, перегляд товарів (локальний та серверний)
📦 Товари за категорією — фільтрація та сортування
🚚 Доставка — перевірка зони доставки та вибір часу
💬 Коментарі — примітки до товарів («нарізати», «стиглі» тощо)
🔐 Авторизація — токен для особистих функцій

Встановлення

Жодної установки не потрібно! Використовуйте через npx:

npx silpo-mcp

Для розробників: Якщо хочете працювати з вихідним кодом:
git clone https://github.com/MIt9/silpo-mcp.git
cd silpo-mcp
npm install
npm run build

Налаштування

Claude Desktop

Додати в claude_desktop_config.json:

{
  "mcpServers": {
    "silpo": {
      "command": "npx",
      "args": ["-y", "silpo-mcp"]
    }
  }
}

Альтернатива: Якщо ви клонували репозиторій, можете використати "command": "node" та "args": ["/absolute/path/to/silpo-mcp/dist/index.js"]

Примітка: ID магазину (branch) визначається автоматично після вибору адреси доставки.

Claude Code

Додати в .mcp.json у корені проєкту або в ~/.claude/settings.json:

{
  "mcpServers": {
    "silpo": {
      "command": "npx",
      "args": ["-y", "silpo-mcp"]
    }
  }
}

Альтернатива: Якщо ви клонували репозиторій, можете використати "command": "node" та "args": ["/absolute/path/to/silpo-mcp/dist/index.js"]

Використання

Початок роботи

Перед пошуком товарів потрібно встановити адресу доставки:

«Встанови адресу доставки: Вінниця, вулиця Лисенка, 12»

Або перевірити, чи потрапляє адреса в зону доставки:

«Доставляєте за координатами 49.2328, 28.4816?»

Повний флоу: усі можливості MCP

Щоб отримати повний доступ (серверний кошик + історія замовлень + пропозиції «як зазвичай» + перегляд кошика через кабінет), передайте асистенту в такому порядку:

ID кошика → асистент викличе set_basket_id({ basketId: "ваш-uuid" }).
- Кошик підхоплюється з API; якщо в ньому вже збережена адреса доставки та магазин — вони відновлюються в сесії. Далі можна одразу шукати товари та додавати в кошик.
Токен кабінету → асистент викличе set_auth_token({ token: "Bearer…" }).
- Токен має бути з id.silpo.ua (кабінет), а не з головного сайту (у DevTools → Application/Storage або мережевий запит з origin: https://id.silpo.ua). У payload JWT має бути client_id: "profile--profile--cabinet".

Після цього доступні:

Що	Як працює
Серверний кошик	`get_server_cart` використовує `/v1/my/shopping-cart/{basketId}` з вашим токеном (ваш кошик у кабінеті).
Додавання/зміна/видалення	`add_to_server_cart`, `update_cart_item`, `remove_from_server_cart`, `add_item_comment` — як і раніше.
Історія замовлень	`get_orders_history` — список минулих замовлень.
Пропозиції «як зазвичай»	`silpo_suggest_from_history` — товари на основі історії (потрібна хоча б одна минула покупка).
Баланс бонусів	`get_loyalty_balance` (якщо API повертає дані).

Якщо в кошику не було адреси, асистент окремо запитає адресу доставки та викличе set_delivery_address перед пошуком товарів.

Приклад фразу користувача:

Мій кошик: fadff098-d1ed-47dd-a312-5cdd11a54a67. Ось токен з кабінету Сільпо: eyJhbGciOiJSUzI1NiIs…

Або по кроках: спочатку «працюй з моїм кошиком fadff098-…», потім «токен для кабінету: …».

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

Налаштування сесії

Інструмент	Опис
`set_delivery_address`	Встановити адресу доставки (текстом або координатами)
`search_address`	Пошук адреси / автодоповнення через API Сільпо
`get_current_address`	Переглянути поточну адресу
`set_auth_token`	Встановити токен авторизації
`set_basket_id`	Вказати існуючий ID кошика
`get_session_info`	Інформація про поточну сесію

Товари та пошук

Інструмент	Опис
`search_products`	Пошук товарів за запитом
`get_categories`	Список категорій
`get_promotions`	Товари зі знижками
`get_product`	Деталі товару за ID
`get_category_products`	Товари в обраній категорії

Рецепти

Інструмент	Опис
`search_recipes`	Пошук рецептів на silpo.ua (за назвою) з інгредієнтами та кількостями
`get_recipe_filters`	Отримати фільтри рецептів з API Сільпо (час, категорії тощо)

Локальний кошик (у пам’яті)

Інструмент	Опис
`add_to_cart`	Додати товар у локальний кошик
`remove_from_cart`	Видалити з локального кошика
`get_cart`	Переглянути локальний кошик
`clear_cart`	Очистити локальний кошик

Список покупок (окремо від кошика)

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

Інструмент	Опис
`add_to_shopping_list`	Додати товар у список покупок (кількість і примітка)
`get_shopping_list`	Переглянути список покупок
`remove_from_shopping_list`	Видалити товар зі списку
`clear_shopping_list`	Очистити список покупок
`set_shopping_list_item_checked`	Позначити товар як куплений / не куплений
`shopping_list_to_cart`	Додати всі пункти списку в локальний кошик

Серверний кошик (синхронізація з Сільпо)

Інструмент	Опис
`create_server_cart`	Створити новий кошик на сервері
`get_server_cart`	Переглянути серверний кошик
`add_to_server_cart`	Додати товар у серверний кошик
`update_cart_item`	Змінити кількість товару
`remove_from_server_cart`	Видалити з серверного кошика
`add_item_comment`	Додати коментар до товару в кошику

Доставка

Інструмент	Опис
`get_time_slots`	Доступні слоти доставки (опційно за типом доставки)
`set_delivery_slot`	Встановити час доставки для кошика
`get_delivery_slot`	Переглянути обраний час доставки
`check_delivery_zone`	Перевірити, чи адреса в зоні доставки
`get_delivery_modes`	Усі типи доставки (додому, широка номенклатура, самовивіз, Б2Б тощо) за координатами
`search_nova_poshta_city`	Пошук населених пунктів Нової пошти (інтеграція Сільпо)
`search_nova_poshta_office`	Пошук відділень Нової пошти в населеному пункті

Приклади запитів для асистента

«Встанови адресу: Вінниця, вулиця Лисенка, 12»
«Знайди адресу: Вінниця, вулиця Лисенка, 12»
«Знайди молоко в Сільпо»
«Покажи акції на сир»
«Додай хліб у кошик»
«Що в моєму кошику?»
«Покажи категорії товарів»
«Коли можна замовити доставку?»
«Постав доставку на завтра з 10:00 до 12:00»
«Який зараз обраний час доставки?»
«Створи кошик на сервері»
«Додай коментар до ковбаси — нарізати»
«Покажи інформацію про сесію»

Авторизація (опційно)

Щоб отримати баланс бонусів та історію замовлень, потрібен токен доступу:

Відкрити silpo.ua та увійти в обліковий запис
Відкрити DevTools (F12) → Application → Local Storage
Скопіювати значення access_token
Викликати set_auth_token з цим токеном

Як дізнатися координати

Відкрити Google Maps
Клікнути правою кнопкою по місцю доставки
Скопіювати координати (широта, довгота)

Обмеження

Локальний кошик зберігається лише в пам’яті (між сесіями не зберігається)
Серверний кошик синхронізується з Сільпо, але оформлення замовлення потребує авторизації на сайті
API може змінюватися без попередження (зворотна розробка)
Окремі операції можуть блокуватися Cloudflare

Розробка

# Development mode
npm run dev

# Build
npm run build

# Run built server
npm start

Публікація нової версії

Використовуйте автоматизований скрипт:

./scripts/publish.sh

Скрипт виконує:

Перевірку версій (package.json ↔ server.json)
Валідацію CHANGELOG.md
Git tag і push
Build і публікацію в NPM
Опціонально: публікацію в MCP Registry

Детальніше: scripts/README.md

Документація для ШІ-асистента

ai-assistant-guidelines.md — основний документ з правилами та флоу для асистента покупок (узгоджено з MCP prompt shopping_assistant у src/index.ts та правилом адреси .cursor/rules/silpo-address.mdc).
docs/ — дослідницькі/допоміжні матеріали (HAR/Swagger мапінги тощо). За замовчуванням ігнорується через .gitignore, тому може бути відсутнім у репозиторії.

Структура проєкту

silpo-mcp/
├── src/
│   ├── index.ts      # MCP сервер та інструменти
│   └── silpo-api.ts  # Клієнт API Сільпо
├── scripts/
│   ├── publish.sh    # Автоматизована публікація
│   └── README.md     # Документація скриптів
├── dist/             # Зібраний код (генерується)
├── ai-assistant-guidelines.md  # Рекомендації для ШІ
├── server.json       # MCP Registry metadata
├── CHANGELOG.md      # Історія змін
├── LICENSE           # MIT License
├── package.json      # NPM package config
├── tsconfig.json     # TypeScript config
└── README.md         # Документація

MCP Registry

Цей сервер може бути опублікований в офіційному MCP Registry. Файл server.json містить метадані для реєстру.

Після публікації в NPM, сервер можна додати до Registry згідно з MCP Registry quickstart.

Changelog

Детальна історія змін доступна в CHANGELOG.md.

Ліцензія

MIT

Silpo MCP Server

Quick Install