🛒 Pyaterochka MCP Tool

MCP-сервер и AI-бот для каталога «Пятёрочки» — поиск магазинов, товаров, акций и цен по всей России прямо из вашей нейросети.

✨ Что это

Проект превращает публичный каталог 5ka.ru в инструменты (tools) для LLM:

Умеет:

• 🔍 найти физический магазин по адресу или геолокации;

• 🗂️ получить категории конкретного магазина;

• 🛒 искать товары с фильтрами: цена (мин/макс), бренд, только акции;

• 📊 сортировать по цене / размеру скидки / популярности;

• 💳 показывать цену по карте, акции «при покупке N штук», старую цену;

• 📋 возвращать наличие, остаток, БЖУ, состав, PLU и ссылку на товар;

• 📸 отправлять альбом фотографий найденных товаров в Telegram.

⚠️ Проект неофициальный и не связан с X5 Group. Используется открытый веб-каталог без логина и пароля. Только в образовательных целях.

Related MCP server: E-Commerce MCP Server

🏗️ Архитектура

                    ┌──────────────────────┐
                    │   Claude / Cursor /  │
                    │  ChatGPT / Telegram  │
                    └──────────┬───────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                 │
     MCP stdio / HTTP MCP                OpenAI-compatible API
              │                                 │
    ┌─────────▼─────────┐             ┌─────────▼─────────┐
    │   mcp/mcp_server  │             │    llm_client     │
    │  + mcp_http_server│             │ (фолбэк между     │
    └─────────┬─────────┘             │  провайдерами)    │
              │                       └─────────┬─────────┘
    ┌─────────▼──────────────────────────────────▼─────────┐
    │                 pyaterochka_store_api                 │
    │   браузер Camoufox  ИЛИ  aiohttp + cookies.json       │
    └──────────────────────────┬───────────────────────────┘
                               │
                        🌐 5d.5ka.ru API

🚀 Быстрый старт

1. Установка

git clone https://github.com/<you>/pyaterochka-mcp-tool.git
cd pyaterochka-mcp-tool

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

Без него тоже работает — через cookies (см. ниже). С ним cookies не нужны вообще:

pip install "camoufox[geoip]"
python -m camoufox fetch   # один раз скачать браузер (~150 МБ)

2. Настройка .env

cp .env.example .env

Минимум для работы MCP-сервера — ничего (только cookies, если не ставили camoufox). Минимум для бота:

TELEGRAM_BOT_TOKEN=123456:AA...      # от @BotFather
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

Любой OpenAI-совместимый провайдер подойдёт: OpenAI, OpenRouter, Groq, DeepSeek, NVIDIA NIM, Together AI, локальный vLLM/Ollama (http://localhost:11434/v1).

🇷🇺 Пользователям из РФ: если официальный api.telegram.org недоступен, можно использовать публичное зеркало Telegram Bot API — просто добавьте в .env:

TELEGRAM_API_BASE_URL=https://telegram.ebalo.lol

🧩 Запуск MCP-сервера

Вариант A: stdio (для десктопных клиентов)

Ничего запускать руками не нужно — клиент сам стартует процесс. Добавьте сервер в конфиг клиента:

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "pyaterochka": {
      "command": "python",
      "args": ["C:/absolute/path/to/pyaterochka-mcp-tool/mcp/mcp_server.py"],
      "env": {
        "PYATEROCHKA_COOKIES_FILE": "C:/secrets/pyaterochka/cookies.json"
      }
    }
  }
}

Cursor / любой клиент с mcpServers — формат тот же.

Проверить вручную можно так:

python mcp/mcp_server.py          # слушает JSON-RPC в stdin/stdout
# или после pip install -e . :
pyaterochka-mcp

Вариант B: HTTP (Streamable HTTP)

python mcp_http_server.py         # → http://127.0.0.1:8765/mcp

Эндпоинты: POST /mcp (JSON-RPC), GET /health, GET / (инфо + список tools).

Пример запроса:

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_store","arguments":{"address":"Москва, Кировоградская улица, 17"}}}'

🧰 Доступные инструменты (12)

Подробнее — в mcp/README.md.

🤖 Запуск Telegram-бота

python bot.py      # только бот
python run.py      # бот + HTTP MCP-сервер вместе (живой вывод в консоль)

Как пользоваться:

1. /start → отправьте боту геолокацию (скрепка → 📍 Location) или напишите адрес;

2. выберите избранный магазин кнопками;

3. спрашивайте: «найди молоко до 100 ₽», «что со скидкой на кофе?», «часы работы?»;

4. команды: /reset — сбросить память, /stop — прервать выполнение, /model — сменить модель на лету.

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

🍪 Cookies: нужны ли и зачем

Есть два транспорта для доступа к каталогу — выберите один:

Как получить cookies.json (для второго варианта):

1. Откройте 5ka.ru в Chrome/Firefox — логиниться не нужно, достаточно просто открыть сайт;

2. Экспортируйте cookies расширением типа Get cookies.txt LOCALLY (формат JSON или Netscape);

3. Сохраните файл вне репозитория, например C:\secrets\pyaterochka\cookies.json;

4. Укажите путь: PYATEROCHKA_COOKIES_FILE=C:\secrets\pyaterochka\cookies.json.

При запуске клиент сначала открывает 5ka.ru, чтобы принять свежие защитные cookies (spjs/spsc и др.), а затем обновляет их автоматически.

🔐 Никогда не публикуйте cookies.json — это ваша живая веб-сессия. Файл уже добавлен в .gitignore. Если утёк — очистите cookies на сайте.

🌍 Публичный доступ: подключение ChatGPT / Claude через туннель

HTTP MCP-сервер слушает 127.0.0.1:8765 — чтобы внешние нейросети (ChatGPT, Claude и любые клиенты с поддержкой remote MCP) достучались до него, заверните порт в туннель:

ngrok:

ngrok http 8765
# получите адрес вида https://a1b2-...ngrok-free.app

cloudflared (без регистрации):

cloudflared tunnel --url http://localhost:8765
# получите адрес вида https://....trycloudflare.com

Затем добавьте URL в клиент:

⚠️ Безопасность: endpoint публичный и без авторизации — любой, кто узнает адрес, сможет пользоваться вашими инструментами. Для постоянного использования прикройте туннель базовой авторизацией на реверс-прокси или используйте ngrok с IP-ограничением. SSH-туннели/ключи в код проекта сознательно не включены.

💡 Примеры запросов

Найди в Пятёрочке по адресу Москва, Кировоградская улица, 17
молоко дешевле 200 рублей и отсортируй по цене.

Что из кофе сейчас по акции рядом со мной? Пришли фото топ-5.

Через CLI (без нейросети):

python pyaterochka_store_api.py resolve --address "Москва, Кировоградская улица, 17"
python pyaterochka_store_api.py products --address "Москва, Кировоградская улица, 17" \
    --store-id S105 --query "молоко" --price-max 200 --sort price_asc --limit 20

📁 Структура проекта

pyaterochka-mcp-tool/
├── mcp/
│   ├── mcp_server.py        # MCP stdio-сервер (12 инструментов)
│   └── README.md            # детали подключения MCP-клиентов
├── mcp_http_server.py       # HTTP (Streamable HTTP) транспорт MCP
├── pyaterochka_store_api.py # API-слой каталога 5ka.ru (+CLI)
├── bot.py                   # Telegram-бот (aiogram)
├── run.py                   # бот + HTTP MCP одним процессом
├── agent.py                 # агентский цикл: LLM ↔ инструменты
├── llm_client.py            # OpenAI-совместимый клиент с фолбэком
├── providers.py             # каталог LLM-провайдеров для /model
├── config.py                # конфиг из переменных окружения
├── stats.py / live_timer.py # статистика и консольные украшения
├── requirements.txt
├── pyproject.toml
└── .env.example

🛡️ Безопасность

• Все ключи и токены — только через .env (в git не попадает).

• cookies.json, sessions.json, логи — в .gitignore.

• Ответы моделей никогда не содержат внутренних id (sap_code, PLU).

• Не публикуйте cookies, прокси и токены — см. раздел Cookies.

⚖️ Лицензия

MIT. Проект не аффилирован с X5 Group («Пятёрочка»); все товарные знаки принадлежат их владельцам.