Skip to main content
Glama

alphamega-mcp

Неофициальный MCP-сервер для интернет-магазина гипермаркета Alphamega (Кипр). Даёт ИИ-агенту инструменты, чтобы собрать продуктовую корзину: найти товары, сравнить цены и акции, положить выбранное в корзину на сайте.

Проект не связан с Alphamega и не одобрен ею. Он пользуется недокументированными интерфейсами сайта, которые могут измениться в любой момент. Используйте на свой риск и в темпе обычного покупателя — см. «Ограничения и риски».

Состоит из двух частей:

  • Каталог — поиск, карточки, категории. Работает сам по себе, проверен на живых данных.

  • Корзина — работает через расширение для Chrome в extension/. Проверена вживую под настоящим аккаунтом: товар добавлен, количество изменено, корзина очищена.

Оформление заказа и оплату сервер не умеет и уметь не должен — это делает человек.

Установка

Нужен Node.js 20 или новее. Сервер запускается на вашем компьютере, отдельный хостинг не требуется.

Только каталог

Ставить ничего не нужно: клиент сам запускает сервер через npx.

Claude Code:

claude mcp add alphamega -- npx -y @drillcoder/alphamega-mcp

Claude Desktop, Cursor и другие клиенты с локальными MCP-серверами — в конфиге MCP:

{
  "mcpServers": {
    "alphamega": {
      "command": "npx",
      "args": ["-y", "@drillcoder/alphamega-mcp"]
    }
  }
}

Каталог и корзина

Для корзины нужно расширение Chrome, а оно загружается из папки пакета. У npx эта папка лежит в кэше и при обновлении меняет путь, поэтому здесь лучше глобальная установка — путь остаётся постоянным.

  1. Установите пакет:

    npm install -g @drillcoder/alphamega-mcp
  2. Подключите сервер. Claude Code:

    claude mcp add alphamega -- alphamega-mcp

    Другие клиенты — в конфиге MCP:

    {
      "mcpServers": {
        "alphamega": {
          "command": "alphamega-mcp"
        }
      }
    }

    Если клиент не находит команду (так бывает у приложений с окном, когда Node установлен через nvm), укажите полный путь из which alphamega-mcp.

  3. Узнайте, где лежит папка расширения:

    alphamega-mcp --extension-path
  4. Откройте в Chrome chrome://extensions и включите «Режим разработчика» (Developer mode) справа вверху.

  5. Нажмите «Загрузить распакованное расширение» (Load unpacked) и выберите эту папку.

  6. Войдите в свой аккаунт на alphamega.com.cy в этом же Chrome.

Когда сервер запущен, на значке расширения появляется зелёная метка on (в течение 30 секунд). Клик по значку заставляет переподключиться сразу.

Обновление: npm install -g @drillcoder/alphamega-mcp@latest, затем кнопка обновления на карточке расширения в chrome://extensions и перезапуск клиента.

Related MCP server: Rohlik MCP Server

Инструменты

Каталог

Инструмент

Что делает

match_shopping_list

Принимает весь список покупок (до 40 строк) и возвращает по несколько кандидатов на каждую строку. С него агенту стоит начинать.

search_products

Поиск по тексту (английский, греческий, терпит опечатки) и фильтрам: категория, бренды, диета, акция, диапазон цен, наличие на складе. Сортировка по цене, пагинация, опционально фасеты.

get_products

Полные карточки по id (SKU) или штрихкоду EAN: греческое название, описание, состав.

list_categories

Дерево категорий с числом товаров; пути из него подставляются в фильтр category.

suggest

Автодополнение запроса и подходящие подкатегории.

Товар в ответе выглядит так:

{
  "id": "370183",
  "title": "Lurpak® Unsalted Butter 250 g",
  "brand": "Lurpak®",
  "price": 3.85,
  "currency": "EUR",
  "unit_price": { "value": 15.4, "per": "1kg" },
  "promotion": "Only",
  "barcode": "5740900863309",
  "category": "Chilled > Butter & Margarine > Cooking Butter",
  "in_stock": { "any": true, "larnaca_central": true, "polemidia": true },
  "url": "https://alphamega.com.cy/default.aspx?ID=149&ProductId=370183",
  "image": "https://alphamega.com.cy/Files/Images/Products/370183.jpg"
}

unit_price есть не у всех товаров (в проверке — у 12 из 20). У товаров со скидкой добавляются original_price, discount_percent, offer_valid_from и offer_valid_to, у товаров с диетическими метками — diet.

Корзина

Инструмент

Что делает

cart_view

Читает корзину: строки, количества, цены, подытог, доставка, итог. Сообщает, выполнен ли вход.

cart_set

Задаёт точное количество для перечисленных товаров; 0 убирает товар. Остальные строки не трогает. Возвращает по каждому товару, сколько магазин реально положил.

cart_clear

Убирает из корзины всё.

cart_login

Если вход не выполнен, открывает страницу входа в Chrome. Телефон и SMS-код вводит человек.

cart_open

Выводит страницу корзины на передний план. Агенту велено вызывать его только по просьбе пользователя.

Количество в cart_set абсолютное, поэтому повторный вызов с теми же данными ничего не задваивает.

Разработка

git clone https://github.com/drillcoder/alphamega-mcp.git
cd alphamega-mcp
npm install        # заодно собирает проект

Чтобы клиент запускал вашу копию, укажите в его конфиге node и путь к dist/index.js вместо npx. Расширение загружайте из папки extension репозитория.

Проверки:

npm run smoke         # каталог: все инструменты на живых данных
npm run bridge-test   # корзина офлайн: настоящий сервер + имитация расширения и магазина
npm run cart-check    # корзина вживую, только чтение: подключено ли расширение, выполнен ли вход

npm run cart-check -- --write добавляет один товар, меняет количество и убирает его. Запускается только при выполненном входе и пустой корзине, чтобы не задеть настоящие покупки.

Как это устроено

Каталог

Сам сайт (Dynamicweb Swift) закрыт Cloudflare и без браузера не отвечает. Но поиск на нём работает через внешний сервис Unbxd, и его JSON API открыт: сервер ходит в https://search.unbxd.io/<apiKey>/<siteKey>/search с клиентскими ключами, которые лежат в JavaScript самого сайта.

  • API недокументированный. Ключи или набор полей могут поменяться без предупреждения — npm run smoke покажет, что именно сломалось.

  • Сервер бережёт чужой сервис: ответы кэшируются на 5 минут, запросы идут по одному с паузой не меньше 200 мс.

  • Наличие — только флаг «есть / нет» по складам Larnaca Central и Polemidia. Точных остатков в API нет.

  • Булевы поля индекса (lactoseFree, vegan, availability) заполнены ненадёжно, поэтому диета фильтруется по specialNutrition, а наличие — по stock_*.

  • Условия акции «Mix & Match» (сколько штук и какая выгода) в API не передаются.

Корзина

Магазин разрешает корзину только вошедшему пользователю (вход по телефону и SMS) и закрыт Cloudflare. Браузер, запущенный автоматикой (Playwright), Cloudflare не пускает — это проверено, и обходить эту проверку сервер не пытается. Поэтому команды корзины выполняются в обычном Chrome пользователя, где он сам прошёл проверки и вошёл.

MCP-клиент ⇄ сервер (stdio) ⇄ WebSocket 127.0.0.1:8765–8769 ⇄ расширение ⇄ вкладка магазина
  • Сервер слушает первый свободный порт из диапазона, поэтому несколько копий (по одной на сессию клиента) друг другу не мешают; расширение подключается ко всем.

  • Расширение умеет ровно три команды: прочитать корзину, задать количество товара, показать страницу корзины или входа. Произвольных запросов и оформления заказа в нём нет.

  • Запросы выполняются внутри вкладки магазина, не меняя её адрес. Если такой вкладки нет, расширение открывает её в фоне и само закрывает примерно через 3 минуты простоя.

  • На передний план вкладка выходит только по cart_open или cart_login. Вкладку, где пользователь смотрит другую страницу магазина, расширение не перенаправляет — открывает новую.

  • К порту может подключиться только это расширение: его идентификатор закреплён ключом в манифесте, а сервер сверяет заголовок Origin, который ни веб-страница, ни другое расширение подделать не могут.

Запросы, которыми пользуется расширение (проверены вручную под вошедшим аккаунтом):

  • Изменить количество:

    POST /Default.aspx?ID=216&LayoutTemplate=Swift_MiniCart.cshtml
    redirect=false, cartcmd=setmulti, CartType=minicart,
    ProductLoopCounter1=1, ProductID1=<id>, VariantID1=, Quantity1=<n>

    В ответ приходит одно число — сколько всего единиц теперь в корзине.

  • Прочитать корзину: GET /en/cart. Каждая строка — article[data-product-id] с атрибутами data-orderline-unit-price и data-orderline-total-price, количество — в input.swift_quantity-field. Пустая корзина перенаправляет на /en/cart/empty-cart.

Ограничения и риски

  • Это автоматизация, которую магазин явно не разрешал; условия использования сайта не изучались. Риск для аккаунта — на его владельце.

  • Каталог берётся из поискового сервиса магазина по клиентскому ключу, который лежит в коде его сайта. Не используйте сервер для массовой выгрузки каталога.

  • Любая программа на этом компьютере, занявшая порт из диапазона раньше сервера, сможет отдавать расширению те же три команды. Ущерб ограничен содержимым корзины.

  • Не проверено: поведение при превышении остатка и лимита тяжёлых товаров, флаг «Allow replacements», слоты доставки.

  • Пищевая ценность есть на карточке товара на сайте (вкладка Nutrition), но не в API — сервер её не отдаёт.

Настройки

Переменные окружения, все необязательные:

Переменная

По умолчанию

Назначение

ALPHAMEGA_UNBXD_API_KEY

ключ с сайта

Если магазин сменит ключ

ALPHAMEGA_UNBXD_SITE_KEY

ключ с сайта

То же для идентификатора витрины

ALPHAMEGA_CACHE_TTL_SEC

300

Время жизни кэша каталога; 0 выключает

ALPHAMEGA_MIN_REQUEST_GAP_MS

200

Минимальная пауза между запросами каталога

ALPHAMEGA_BRIDGE_PORT

8765

Первый порт диапазона моста. Расширение знает только 8765–8769, менять стоит лишь для тестов

ALPHAMEGA_EXTENSION_ID

ID из манифеста

Какому расширению разрешено подключаться; несколько — через запятую. Нужно, только если расширение собрано с другим ключом

Файлы

  • src/unbxd.ts — HTTP-клиент каталога: кэш, очередь запросов, таймаут.

  • src/product.ts — приведение «сырого» товара из индекса к компактному виду.

  • src/catalog.ts — фильтры и логика инструментов каталога.

  • src/bridge.ts — локальный WebSocket-мост к расширению.

  • src/cart.ts — логика корзины поверх моста.

  • src/index.ts — регистрация инструментов MCP (stdio).

  • extension/ — расширение Chrome (Manifest V3, без сборки).

  • scripts/ — проверки, перечисленные выше.

Лицензия

MIT, см. LICENSE.

Available Tools

10 tools
cart_clearEmpty Alphamega cartA
DestructiveIdempotent

Remove every product from the user's cart on alphamega.com.cy. Only use when the user asked to start the basket from scratch.

Inputs: no named parameters.

cart_loginOpen Alphamega loginA

Check whether the user's Chrome is signed in to Alphamega and, if not, open the login page there. The user must sign in themselves (phone number + SMS code); never ask them for the code. Call this when another cart tool reports that login is required.

Inputs: no named parameters.

cart_openShow Alphamega cart to the userA
Read-only

Bring the cart page to the front in the user's Chrome. This takes over their screen, so call it only when the user asks to see the cart or is ready to check out — not as a routine last step. Checkout, delivery slot and payment are always done by the user; this server cannot place orders.

Inputs: no named parameters.

cart_setSet Alphamega cart quantitiesA
DestructiveIdempotent

Set the quantity of one or more products in the user's real cart on alphamega.com.cy. Quantities are absolute, not increments: 2 means the cart will hold exactly 2, and 0 removes the product. Products not listed are left untouched. Returns per-product results (the shop may cap or reject a quantity) and the resulting cart. Requires the user to be logged in (see cart_login).

Inputs: items (required).

cart_viewView Alphamega cartA
Read-only

Read the current cart on alphamega.com.cy: lines (id, title, quantity, unit price, line total) and the order summary (subtotal, delivery, order total). Also reports whether the browser is logged in.

Inputs: no named parameters.

get_productsGet Alphamega products by id or barcodeA
Read-only

Look up specific products by store id (SKU) and/or EAN barcode. Returns full details including Greek title, description and ingredients, plus the ids/barcodes that were not found.

Inputs: ids, barcodes.

list_categoriesList Alphamega categoriesA
Read-only

List catalogue categories with product counts. Without parent returns the top level; pass a path to see its children. Use the returned paths as the category filter.

Inputs: depth, parent.

match_shopping_listMatch a shopping list to productsA
Read-only

Search for every line of a shopping list in one call and return the top candidates per line. Use this first when building a basket, then pick one candidate per line (compare unit_price, promotions and stock).

Inputs: items (required), sort, in_stock_at, candidates_per_item.

search_productsSearch Alphamega productsA
Read-only

Search the Alphamega catalogue by free text and/or filters. Returns compact product records (id, title, brand, price, unit price, promotion, barcode, category, stock). Omit query to browse a category or list promotions.

Inputs: diet, sort, limit, query, +8 more.

suggestSuggest search termsA
Read-only

Autocomplete for a partial or uncertain search term: returns suggested queries and matching subcategory names. Use when a search returns nothing useful.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools map to a distinct resource+action: catalogue search/lookup/categories vs. a clearly bounded cart_* family. The main soft overlaps are search_products vs. match_shopping_list (bulk variant of search) and cart_login vs. cart_view, which both report login state, though descriptions steer usage well. suggest is clearly a fallback autocomplete rather than a search itself.

    Naming Consistency4/5

    All names are snake_case and readable, with a clean verb_noun pattern for catalogue tools (search_products, get_products, list_categories, match_shopping_list). The cart tools form a predictable cart_<action> namespace, which is a deliberate grouping rather than an inconsistency. Minor deviation: bare `suggest` breaks the verb_noun pattern.

    Tool Count5/5

    Ten tools is well-scoped for a grocery catalogue + cart server, with no redundant entries. Each tool covers a distinct capability (discovery, lookup, basket building, cart mutation, browser login/surface).

    Completeness4/5

    Catalogue side is complete (free-text search, SKU/EAN lookup, category tree, autocomplete fallback) and cart side covers view, absolute-quantity set, clear, login and open. Gaps are mostly intentional (no checkout/payment, explicitly user-driven) but there is no order history or delivery-slot query, and quantity changes are absolute-only, forcing read-modify-write for increments.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, access account and order information, and find deals and delivery details across several European online grocery platforms.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, view discounts, and access account, delivery, and order information across multiple European online grocery platforms.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, and access account, order, delivery, and discount information across multiple European online grocery platforms.
      MIT