alphamega-mcp
# 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
Scored across 10 tools
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.
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.
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).
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.