← На головну

Офіційний MCP «Сільпо»

Один URL — і будь-який MCP-сумісний AI-клієнт (Claude, Cursor, Kiro) отримує доступ до каталогу, кошика, замовлень, лояльності та доставки «Сільпо» від імені авторизованого гостя. 39 tools, OAuth 2.1, без кастомних інтеграцій.

Транспорт
Streamable HTTP
Авторизація
OAuth 2.1 + PKCE
Tools
39 доступних

Що це і навіщо

MCP (Model Context Protocol) — відкритий стандарт від Anthropic для підключення AI-моделей до зовнішніх систем. Один сервер описує свої можливості (tools), і будь-який MCP-сумісний клієнт одразу може ними користуватись — без окремих інтеграцій під кожну модель.

Офіційний MCP «Сільпо» дає AI-агенту повний доступ до e-commerce платформи «Сільпо» від імені гостя: пошук товарів, наповнення кошика, доставка, історія замовлень, бонуси та сертифікати. Це технологічна основа хакатону — усі рішення учасників мають взаємодіяти саме через нього.

Приклади запитів, які «просто працюють»:
  • «Додай у кошик 2 літри молока, буханець хліба і десяток яєць»
  • «Покажи мої останні 5 замовлень»
  • «Які акції доступні на мою адресу доставки?»
  • «Застосуй мої балабонуси до поточного кошика»
  • «Знайди заміну товару, якого немає в наявності»

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

Додай MCP-сервер у конфіг свого клієнта. На першому підключенні відкриється браузер — увійди в акаунт «Сільпо», і все.

{
  "mcpServers": {
    "silpo": {
      "url": "https://mcp.silpo.ua/mcp"
    }
  }
}

Підключення клієнтів

КлієнтЯк підключити
Claude DesktopДодай URL https://mcp.silpo.ua/mcp у секцію mcpServers конфіга.
Claude Codeclaude mcp add --transport http silpo https://mcp.silpo.ua/mcp
CursorДодай https://mcp.silpo.ua/mcp у налаштування MCP-серверів.
Kiro CLIДодай URL у конфігурацію mcpServers.

TypeScript SDK

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport }
  from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.silpo.ua/mcp"),
  { authProvider: mySilpoAuthProvider },
);

const client = new Client(
  { name: "hackathon-agent", version: "0.1.0" },
  { capabilities: {} },
);

await client.connect(transport);
const { tools } = await client.listTools();

Vercel AI SDK

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://mcp.silpo.ua/mcp",
    authProvider: mySilpoAuthProvider,
  },
});

const tools = await mcp.tools();

const result = await streamText({
  model: openai("gpt-4o"),
  tools,
  prompt: "Знайди варіанти вечері з молочних продуктів до 300 грн",
});

Python SDK

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://mcp.silpo.ua/mcp",
    auth=my_oauth_provider,
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

Як працює авторизація

Сервер використовує OAuth 2.1 (Authorization Code + PKCE). Для AI-клієнта процес майже повністю автоматичний: гість авторизується в акаунті «Сільпо» один раз, а далі клієнт сам поновлює доступ.

Перше підключення

  1. Клієнт отримує 401 і читає метадані OAuth-сервера з /.well-known/oauth-authorization-server.
  2. Реєструється через Dynamic Client Registration ( POST /register).
  3. Генерує PKCE-пару та відкриває /authorize у браузері.
  4. Гість логіниться на auth.silpo.ua (телефон + OTP або пароль).
  5. Після успішної авторизації клієнт отримує MCP-токен і використовує його в усіх запитах: Authorization: Bearer <mcp_token>.

Безпека: AI-клієнт ніколи не бачить Silpo JWT гостя — він залишається всередині інфраструктури «Сільпо».

Доступні tools (39)

Усі tools потребують авторизації. Позначка 🔒 cart означає, що потрібен контекст кошика (branchId, deliveryType, timeslot) — отримай його через silpo_get_my_shopping_cart silpo_get_shopping_cart_by_id. Позначка ✎ write — tool змінює стан.

Локація та доставка (6)

  • silpo_find_address

    Знайти координати (lat/lng) за текстом адреси. Перший крок при зміні адреси доставки.

  • silpo_get_available_delivery_types

    Доступні типи доставки для координат: DeliveryHome, WideAssortDelivery, SelfPickup, NovaPoshta, B2B.

  • silpo_list_branches

    Список магазинів «Сільпо». Фільтри: hasPickup, hasNovaPoshta.

  • silpo_get_time_slots

    Доступні слоти доставки для магазину. ОБОВ'ЯЗКОВО викликати після отримання кошика — валідувати слот.

  • silpo_find_nova_poshta_settlements

    Пошук населеного пункту Нової Пошти за назвою.

  • silpo_find_nova_poshta_offices

    Відділення / поштомати НП у населеному пункті.

Пошук товарів (7)

  • silpo_find_products_batch🔒 cart

    Пошук до 30 товарів паралельно. Основний tool для заповнення кошика зі списку покупок.

  • silpo_get_products🔒 cart

    Товари з фільтрами: категорія, акція, пошуковий запит, пагінація.

  • silpo_get_product_details🔒 cart

    Повна картка товару: склад, харчова цінність, атрибути, зображення.

  • silpo_get_similar_products🔒 cart

    Схожі / альтернативні товари за slug.

  • silpo_get_replacements🔒 cart

    Заміни для товарів, яких немає в наявності.

  • silpo_get_my_favorites

    Список збережених «улюблених» товарів гостя.

  • silpo_add_or_update_favorite_products✎ write

    Додати / прибрати товари з улюблених.

Каталог (6)

  • silpo_get_promotions🔒 cart

    Активні акції та знижки в конкретному магазині.

  • silpo_get_popular_categories🔒 cart

    Популярні категорії в магазині.

  • silpo_get_category🔒 cart

    Деталі окремої категорії: підкатегорії, кількість товарів.

  • silpo_get_categories

    Плоский список усіх категорій магазину.

  • silpo_get_categories_tree🔒 cart

    Повне дерево категорій та підкатегорій.

  • silpo_get_product_sets

    Кураторські добірки товарів (тематичні, сезонні).

Кошик (7)

Кошик — центральний об'єкт. Рекомендований старт сесії: silpo_get_my_shopping_cart → silpo_get_shopping_cart_by_id → silpo_get_time_slots.

  • silpo_get_my_shopping_cart

    Отримати ID активного кошика. Завжди перший крок.

  • silpo_get_shopping_cart_by_id

    Повний кошик: товари, доставка, тайм-слот, суми, валідації, бонуси, посилання на checkout.

  • silpo_add_or_update_cart_products✎ write

    Додати товари або оновити кількість. Потрібні productId + companyId + branchId з пошуку.

  • silpo_remove_cart_products✎ write

    Видалити конкретні товари з кошика.

  • silpo_clear_shopping_cart✎ write

    Очистити весь кошик.

  • silpo_update_shopping_cart✎ write

    Оновити доставку, слот, адресу, промокод, спосіб оплати, застосувати бонуси.

  • silpo_add_or_update_certificates✎ write

    Додати або зняти подарункові сертифікати з кошика.

Замовлення (2)

  • silpo_get_my_online_orders

    Історія онлайн-замовлень (silpo.ua / застосунок). Дає змогу повторити замовлення одним викликом cart.add.

  • silpo_get_my_offline_orders

    Історія покупок у фізичних магазинах: чеки, товари, знижки, зароблені бонуси.

Профіль (4)

  • silpo_get_my_profile

    Дані профілю: ім'я, телефон, email, дата народження.

  • silpo_get_my_delivery_addresses

    Збережені адреси доставки гостя.

  • silpo_get_my_family

    Члени родини у профілі: діти (з віком) і тварини.

  • silpo_get_my_food_restrictions

    Дієтичні обмеження та харчові уподобання.

Лояльність та акції (7)

  • silpo_get_loyalty_info

    Картка «Власний Рахунок»: номер, статус, поточний та нарахований баланс балабонусів.

  • silpo_get_my_coupons

    Доступні купони знижок гостя.

  • silpo_get_coupon_details

    Повна інформація про купон: умови, товари, штрих-код.

  • silpo_get_my_promos

    Персональні промо-пропозиції.

  • silpo_get_promo_codes

    Активні промокоди гостя.

  • silpo_get_my_certificates

    Активні подарункові сертифікати: код, штрих-код, номінал.

  • silpo_get_my_premium_subscription

    Статус Silpo Premium: активність, дата завершення, переваги.

Актуальний список — з tools/list

Точні назви, аргументи та JSON Schema завжди повертає сам сервер після авторизації. Читай tools/list на старті агента — це стандартна MCP-практика.

Типові сценарії

Наповнити кошик зі списку покупок

1. silpo_get_my_shopping_cart          → cartId
2. silpo_get_shopping_cart_by_id       → branchId, deliveryType, timeslot
3. silpo_get_time_slots                ← обов'язково: валідація слота
4. silpo_find_products_batch(items[])  → productId + companyId + branchId
5. silpo_add_or_update_cart_products   → додати все
6. silpo_get_shopping_cart_by_id       ← перевірити результат
   • перевірити validations[]
   • якщо loyalty.bonusAvailable > 0 — запропонувати балабонуси
   • якщо express доступний — підсвітити варіант і ціну
   • показати checkoutWebLink + checkoutMobileLink

Змінити адресу доставки

1. silpo_find_address(text)                     → lat, lng
2. silpo_get_available_delivery_types(lat, lng) → варіанти доставки

   ├─ DeliveryHome / WideAssortDelivery: branchId в відповіді → крок 3
   ├─ SelfPickup:     silpo_list_branches(hasPickup=true) → гість обирає
   └─ NovaPoshta:     silpo_find_nova_poshta_settlements(city)
                      silpo_find_nova_poshta_offices(settlementId)
                      silpo_list_branches(hasNovaPoshta=true)

3. silpo_get_time_slots(branchId, deliveryType) → гість обирає слот
4. silpo_update_shopping_cart(...)              → застосувати
5. silpo_get_shopping_cart_by_id                ← перевірити

Застосувати балабонуси

Після silpo_get_shopping_cart_by_id:
  якщо loyalty.bonusAvailable > 0
     і loyalty.bonusRequested == null
     і loyalty.isEnabled:
       → запитати: «У вас є {bonusAvailable} балабонусів. Застосувати?»
       → якщо так: silpo_update_shopping_cart(bonusRequested = bonusAvailable)

Помилки та обмеження

  • 401 invalid_token — токен відсутній або протух. Клієнт має використати refresh_token або пройти OAuth-потік заново.
  • 403 — токен валідний, але немає доступу до конкретного tool.
  • 429 — rate-limit. Використай експоненційний backoff. Ліміти застосовуються per-user через Cookie: mcp-user={userId}.
  • -32601 Method not found — метод JSON-RPC не підтримується поточною версією.
Безпека. AI-клієнт ніколи не бачить Silpo JWT. MCP-токен зберігай на бекенді або у secure storage — не у публічному фронтенді.

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

Щоб проєкт відповідав умовам «Сільпо» AI Factory, він має:

  • підключатись саме до https://mcp.silpo.ua/mcp, а не до сторонніх або неофіційних API;
  • викликати хоча б один tool із tools/list у робочому сценарії агента;
  • мати робочий prototype або demo, у якому цей виклик видно (запис екрана, лог JSON-RPC або трейси);
  • зберігати токени серверно, а не в клієнтському коді.

Готовий підключатись?

Зареєструйся на хакатон — і ми надішлемо starter kit, приклади готових агентів та актуальний перелік tools.