MCP сервер Сільпо (silpo-mcp)

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

Побудований на реальних запитах storefront-API Сільпо (sf-ecom-api.silpo.ua), відновлених із мережевого трафіку. Офіційного SDK немає — API може змінюватися без попередження.

Можливості

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

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

# Глобальна установка
npm install -g silpo-mcp

# або без установки
npx silpo-mcp

З вихідного коду:

git clone https://github.com/MIt9/silpo-mcp.git
cd silpo-mcp
npm install
npm run build
npm start

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

Claude Desktop / Claude Code

claude_desktop_config.json або .mcp.json:

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

Або з вихідного коду:

{
  "mcpServers": {
    "silpo": {
      "command": "node",
      "args": ["/absolute/path/to/silpo-mcp/dist/index.js"]
    }
  }
}

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

Віддалений хостинг (Claude web / custom connector)

Крім локального stdio-режиму, сервер має віддалений HTTP-режим (dist/http.js), захищений OAuth 2.1 — саме його підключає Claude через «custom connector».

Поля OAuth Client ID / OAuth Client Secret у Claude — це не захист від підбору IP, а стандартний OAuth: Claude виступає OAuth-клієнтом, а сервер — сервером авторизації. Доступ обмежується паролем на сторінці входу (SILPO_MCP_PASSWORD), тому сторонні, навіть знаючи URL, не зможуть користуватися.

Запуск

npm run build
SILPO_MCP_BASE_URL="https://silpo.example.com" \
SILPO_MCP_PASSWORD="ваш-надійний-пароль" \
SILPO_MCP_PORT=3000 \
npm run start:http

Змінні середовища:

| Змінна | Обовʼязково | Опис | | --- | --- | --- | | SILPO_MCP_BASE_URL | так | Публічний https URL сервера (issuer для OAuth) | | SILPO_MCP_PASSWORD | так | Пароль для входу (гейт доступу) | | SILPO_MCP_PORT | ні | Порт (типово 3000) | | SILPO_MCP_TOKEN_TTL | ні | Час життя access-токена, сек (типово 2592000 = 30 днів) | | SILPO_MCP_STATE_FILE | ні | Файл персистентності OAuth (клієнти + токени). Типово .oauth-state.json у робочій теці | | SILPO_MCP_SESSION_FILE | ні | Файл персистентності сесії (адреса, basketId, токен і cookie кабінету). Типово session.json поряд зі SILPO_MCP_STATE_FILE | | SILPO_OAUTH_CLIENT_ID / SILPO_OAUTH_CLIENT_SECRET | ні | Наперед зареєстрований клієнт (для полів у Claude) | | SILPO_OAUTH_REDIRECT_URIS | ні | Дозволені redirect_uri статичного клієнта (через кому) |

Персистентність. У віддаленому режимі і OAuth-токени, і стан сесії зберігаються на диск (файли з правами 0600), тож перезапуск/деплой/перезавантаження не вимагають повторної авторизації в Claude і не втрачають адресу/кошик. Токен і cookie кабінету Сільпо теж потрапляють у SILPO_MCP_SESSION_FILE — тримайте файл приватним (cookie дозволяє оновлювати токен від імені акаунта).

HTTPS обовʼязковий

Claude вимагає https з валідним сертифікатом і доменним іменем — «голий» IP не підійде. Запускайте сервер за реверс-проксі, напр. Caddy (автоматичний Let's Encrypt):

silpo.example.com {
    reverse_proxy localhost:3000
}

Підключення в Claude

1. Розгорніть сервер за HTTPS-доменом.
2. У Claude → «Add custom connector» вкажіть Server URL: https://silpo.example.com/mcp.
3. Client ID/Secret залиште порожніми — сервер підтримує Dynamic Client Registration, тож Claude зареєструється сам. (Або задайте SILPO_OAUTH_CLIENT_* і впишіть їх у ці поля.)
4. Під час підключення Claude відкриє сторінку входу — введіть SILPO_MCP_PASSWORD.
5. Готово: доступні всі інструменти. Стан сесії (адреса, кошик) спільний для сервера.

Ендпоінти

• POST/GET/DELETE /mcp — MCP Streamable-HTTP транспорт (захищений Bearer-токеном)
• /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server — метадані
• /authorize, /token, /register, /revoke — стандартні OAuth-ендпоінти
• /login — сторінка входу за паролем

Швидкий старт

Перед пошуком товарів встановіть адресу доставки — вона визначає найближчий магазин:

«Встанови адресу доставки: Львів, вулиця Стрийська, 45А»
«Доставляєте за координатами 49.8030, 24.0196?»
«Знайди молоко»
«Покажи акції»
«Коли можна замовити доставку?»

Для особистих функцій (історія замовлень, бонуси) потрібна авторизація. Є два способи:

• Cookie (рекомендовано) — set_auth_cookie зберігає cookie сесії .AspNetCore.Identity.Application (auth.silpo.ua), і сервер сам оновлює токен кабінету, коли той спливає (кожні ~24 год), без ручного втручання.
• Токен — set_auth_token приймає разовий Bearer-токен (живе ~24 год, далі треба вставити новий вручну).

«Мій кошик: fadff098-d1ed-47dd-a312-5cdd11a54a67»
«Cookie авторизації Сільпо: CfDJ8PokYHNhxS1Nmvi…»
«Токен з кабінету Сільпо: eyJhbGciOiJSUzI1NiIs…»

Де взяти cookie: DevTools → Application → Cookies → https://auth.silpo.ua → значення .AspNetCore.Identity.Application. Токен: мережевий запит на sf-ecom-api.silpo.ua із заголовком authorization: Bearer ….

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

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

| Інструмент | Опис | | --- | --- | | set_delivery_address | Встановити адресу доставки (текст або координати) | | get_current_address | Поточна адреса та магазин | | set_auth_cookie | Cookie сесії для автооновлення токена кабінету (рекомендовано) | | set_auth_token | Разовий токен авторизації кабінету (без автооновлення) | | set_basket_id | Підключити існуючий кошик Сільпо | | get_session_info | Стан поточної сесії |

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

| Інструмент | Опис | | --- | --- | | search_products | Пошук товарів за запитом | | get_categories | Список категорій | | get_category_products | Товари в категорії (сортування, пагінація) | | get_promotions | Товари зі знижками | | get_product | Деталі товару за slug | | get_product_images | Фото товару за slug — повертає самі зображення (не посилання) |

Доставка

| Інструмент | Опис | | --- | --- | | check_delivery_zone | Чи в зоні доставки координати | | get_delivery_modes | Усі типи доставки за координатами | | get_time_slots | Доступні слоти доставки | | set_delivery_slot / get_delivery_slot | Обраний час доставки |

Кошик (реальний кошик Сільпо)

add_to_cart, get_cart, update_cart_item, remove_from_cart, clear_cart, create_cart, add_item_comment

Кошик живе на сервері Сільпо — це той самий кошик, що видно на сайті/у застосунку. Створюється автоматично при першому add_to_cart (потрібна встановлена адреса доставки); create_cart існує для явного створення нового кошика. Товари ідентифікуються за productId (uuid товару — беріть його з search_products/get_product). update_cart_item з quantity: 0 (або remove_from_cart) видаляє товар. Авторизація не потрібна — кошик визначається лише за basketId; токен можна передати опційно.

Список покупок

add_to_shopping_list, get_shopping_list, remove_from_shopping_list, clear_shopping_list, set_shopping_list_item_checked, shopping_list_to_cart

Список покупок — легкий чернетковий список (назва + кількість), який живе в сесії сервера і не чіпає API Сільпо. shopping_list_to_cart знаходить кожен пункт у каталозі (за slug або назвою) і додає його в кошик Сільпо.

Кабінет (потрібна авторизація)

get_orders_history, get_order_products, get_loyalty_balance, silpo_suggest_from_history

get_orders_history повертає перелік замовлень (номер, статус, сума, дата, адреса). get_order_products повертає позиції конкретного замовлення (за номером або з останнього): назва, кількість, сума, productId (щоб додати назад у кошик), позначки заміни/видалення.

Потрібен токен (set_auth_token) або, краще, cookie (set_auth_cookie) — з cookie токен оновлюється автоматично при спливанні. При 401 сервер робить одну спробу оновити токен і повторити запит.

Обмеження

• У stdio-режимі сесія (адреса, basketId, список покупок) живе лише в пам'яті (між запусками не зберігається). У віддаленому режимі стан персистується у SILPO_MCP_SESSION_FILE і переживає перезапуск.
• Кошик синхронізується з Сільпо, але оформлення замовлення потребує авторизації на сайті.
• Кошики ефемерні — Сільпо видаляє їх через деякий час бездіяльності; тоді get_cart поверне 404, і наступний add_to_cart створить новий.
• Створення кошика потребує обраного слоту доставки (обирається автоматично, якщо не задано) і обмежується частотою (HTTP 429). Якщо у вас уже є basketId — використовуйте set_basket_id.
• Зміни кошика застосовуються асинхронно (сервер відповідає 202), тому сервер робить повторний GET, щоб показати актуальний стан.
• set_delivery_address приймає координати (рекомендовано) або текст. Текст геокодується через OpenStreetMap Nominatim, бо власне автодоповнення Сільпо ще не відновлено.
• Токен кабінету живе ~24 год. З set_auth_cookie він оновлюється автоматично (тихий OIDC-флоу через cookie сесії); без cookie після спливання треба вставити новий токен вручну. Якщо cookie перестане діяти — вставте новий.
• Тимчасово вимкнено (закоментовано в src/index.ts до відновлення реальних ендпоінтів): search_address (окремий пошук адрес) та рецепти search_recipes / get_recipe_filters.
• API відновлено методом зворотної розробки і може змінюватися; окремі операції можуть блокуватися Cloudflare.

Розробка

npm run dev     # watch-збірка
npm run build   # збірка
npm start       # запуск зібраного сервера

Структура

silpo-mcp/
├── src/
│   ├── index.ts       # buildServer() + усі MCP-інструменти, stdio-режим
│   ├── http.ts         # Віддалений HTTP-режим (Streamable HTTP + OAuth)
│   ├── oauth.ts        # OAuth 2.1 сервер авторизації (пароль-гейт, DCR)
│   ├── silpo-api.ts    # HTTP-клієнт API Сільпо
│   ├── silpo-auth.ts   # Автооновлення токена кабінету (PKCE prompt=none через cookie)
│   └── session.ts      # Стан сесії, список покупок
├── .env.example        # Змінні для віддаленого режиму
├── dist/
├── package.json
└── tsconfig.json

Ліцензія

MIT