Skip to main content
Glama
README.md
# alphamega-mcp

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

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

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

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

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

## Установка

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

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

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

Claude Code:

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

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

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

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

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

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

   ```bash
   npm install -g @drillcoder/alphamega-mcp
   ```

2. Подключите сервер. Claude Code:

   ```bash
   claude mcp add alphamega -- alphamega-mcp
   ```

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

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

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

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

   ```bash
   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` и перезапуск клиента.

## Инструменты

### Каталог

| Инструмент | Что делает |
| --- | --- |
| `match_shopping_list` | Принимает весь список покупок (до 40 строк) и возвращает по несколько кандидатов на каждую строку. С него агенту стоит начинать. |
| `search_products` | Поиск по тексту (английский, греческий, терпит опечатки) и фильтрам: категория, бренды, диета, акция, диапазон цен, наличие на складе. Сортировка по цене, пагинация, опционально фасеты. |
| `get_products` | Полные карточки по id (SKU) или штрихкоду EAN: греческое название, описание, состав. |
| `list_categories` | Дерево категорий с числом товаров; пути из него подставляются в фильтр `category`. |
| `suggest` | Автодополнение запроса и подходящие подкатегории. |

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

```json
{
  "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` абсолютное, поэтому повторный вызов с теми же данными ничего не
задваивает.

## Разработка

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

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

Проверки:

```bash
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](LICENSE).

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