<div align="center">

🛒 Pyaterochka MCP Tool

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

</div>

---

✨ Что это

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

Компонент	Что делает
🧩 MCP stdio-сервер	Подключается к Claude Desktop, Cursor, opencode и любому MCP-клиенту
🌐 HTTP MCP-сервер	Тот же набор инструментов по http://127.0.0.1:8765/mcp (Streamable HTTP) — удобно для remote MCP через туннель
🤖 Telegram-бот с ИИ	Полноценный агент: сам находит магазин, ищет товары, показывает фото и цены, помнит ваши предпочтения

Умеет:

• 🔍 найти физический магазин по адресу или геолокации;
• 🗂️ получить категории конкретного магазина;
• 🛒 искать товары с фильтрами: цена (мин/макс), бренд, только акции;
• 📊 сортировать по цене / размеру скидки / популярности;
• 💳 показывать цену по карте, акции «при покупке N штук», старую цену;
• 📋 возвращать наличие, остаток, БЖУ, состав, PLU и ссылку на товар;
• 📸 отправлять альбом фотографий найденных товаров в Telegram.

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

---

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

                    ┌──────────────────────┐
                    │   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

<details> <summary><b>Браузерный режим (опционально, рекомендую)</b></summary>

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

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

</details>

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).

<details> <summary><b>Все переменные окружения</b></summary>

Переменная	По умолчанию	Описание
TELEGRAM_BOT_TOKEN	—	Токен бота от @BotFather (обязателен для бота)
TELEGRAM_API_BASE_URL	https://api.telegram.org	Можно указать локальный Telegram Bot API Server — тогда включится стриминг ответа
LLM_API_URL	https://api.openai.com/v1	Основной LLM (OpenAI-совместимый /v1)
LLM_API_KEY	—	Ключ основного LLM
LLM_MODEL	gpt-4o-mini	Модель основного провайдера
LLM_RESERVE_URL/_KEY/_MODEL	—	Резерв №1 (автофолбэк при сбоях/429/5xx)
LLM_FALLBACK_URL/_KEY/_MODEL	—	Резерв №2 (последний рубеж)
OPENAI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, …	—	Ключи для инлайн-меню /model в боте
PYATEROCHKA_COOKIES_FILE	—	Путь к cookies.json (если нет браузерного режима)
PYATEROCHKA_PROXY	—	SOCKS5-прокси для запросов к 5ka.ru
MCP_HOST / MCP_PORT	127.0.0.1 / 8765	Адрес HTTP MCP-сервера

</details>

🇷🇺 Пользователям из РФ: если официальный 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)

Tool	Описание
find_store	Найти магазин по адресу → store_id
find_nearest_stores	Ближайшие магазины по координатам
get_store_info / get_store_hours	Карточка и часы работы магазина
list_stores_in_area	Магазины в прямоугольной области карты
list_store_categories	Дерево категорий магазина
search_products	Поиск товаров: цена, бренд, акции, сортировка
list_category_products	Товары категории с фильтрами
find_products	Универсальный поиск по адресу или store_id
get_product_promotion	Условия акции на товар
get_product_info	Карточка товара: состав, калории, БЖУ
refresh_session	Обновить web-сессию 5ka.ru

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

---

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

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

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

1. /start → отправьте боту геолокацию (скрепка → 📍 Location) или напишите адрес;
2. выберите избранный магазин кнопками;
3. спрашивайте: «найди молоко до 100 ₽», «что со скидкой на кофе?», «часы работы?»;
4. команды: /reset — сбросить память, /stop — прервать выполнение, /model — сменить модель на лету.

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

---

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

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

	🦊 Браузерный (camoufox)	📄 aiohttp + cookies.json
Ручные cookies	❌ не нужны	✅ нужны
Надёжность при 403/антиботе	выше	ниже
Зависимости	тяжёлые (~150 МБ браузер)	лёгкие

Как получить 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 в клиент:

Клиент	Где указать
Claude Desktop / Claude Web	Settings → Connectors → Add custom connector → https://ваш-адрес/mcp
ChatGPT	Settings → Apps & Connectors → Create (Developer Mode) → URL https://ваш-адрес/mcp
Cursor	MCP settings → Add server → тип URL/SSE
MCP Inspector	npx @modelcontextprotocol/inspector, transport: 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 («Пятёрочка»); все товарные знаки принадлежат их владельцам.