Recipe Shopping List — servidor MCP

Servidor MCP (Model Context Protocol) que puede:

1. Leer recetas de food.ru — a partir del enlace extrae ingredientes, pasos, KBJU

2. Buscar productos en magnit.ru — teniendo en cuenta la tienda concreta

3. Elaborar la lista de la compra — para la receta encuentra productos con precios y calcula el total

4. Mostrar información sobre la tienda — por código de tienda

Resultado: das un enlace a una receta — obtienes una lista de la compra lista con precios de Magnit y enlaces directos a los productos.

🎓 Proyecto educativo: el proyecto se utilizó para formar a los category managers de una cadena minorista en la creación de servidores MCP. Es un caso práctico con el ciclo completo: desde la idea y el pliego de condiciones hasta un servidor MCP funcional que utiliza un asistente de IA. Los participantes, con la ayuda de un agente de IA, crean una aplicación funcional — un parser de recetas de food.ru, búsqueda de productos en magnit.ru y una lista de la compra con precios — y obtienen un resultado positivo en el transcurso de una sola sesión.

🌐 Versión web: además de la interfaz MCP, hay una interfaz web local — no requiere cliente MCP, funciona en el navegador. Se inicia con un solo comando:

./start.sh   # запустить и открыть страницу в браузере (http://127.0.0.1:8000)
./stop.sh    # остановить сервер

En la versión web puedes pegar un enlace a una receta, obtener una tabla con la lista de la compra y guardarla en Excel. Detalles en la sección «Interfaz web».

Instalación

Método rápido: instalador install.py

El script install.py (solo biblioteca estándar de Python — no hay que instalar nada adicional) lo hace todo por sí mismo: crea un entorno virtual, instala las dependencias y el navegador para Playwright, crea .env, registra el servidor en los clientes MCP seleccionados y comprueba que todo funciona.

Se requiere Python 3.11+ (recomendamos uv — el instalador encontrará tanto uv como Python normal).

python install.py      # или: python3 install.py

Todos los flags son opcionales:

Ejemplos:

python install.py --check              # проверка окружения без изменений
python install.py --yes                # установка «на все по умолчанию»
python install.py --shop-code 992301 --clients opencode,claude

Manualmente

Se requiere Python 3.11+ (recomendamos uv).

# 1. Виртуальное окружение и зависимости
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -r requirements.txt

# 2. Браузер для Playwright (оба сайта — SPA, без браузера никак)
.venv/bin/python -m playwright install chromium

# 3. Секреты
cp .env.example .env   # при необходимости поправь код магазина по умолчанию

Related MCP server: Recipe Commerce Intelligence MCP

Ejecución

.venv/bin/python src/server.py

El servidor funciona según el protocolo MCP a través de stdio — lo invoca el asistente de IA (Claude Desktop, LM Studio, etc.), por sí mismo «permanece en silencio» en la terminal.

Interfaz web

Página web local para quienes no quieren conectar un cliente MCP: pegas un enlace a una receta — obtienes una tabla con la lista de la compra y un botón para guardar en Excel.

Ejecución (el servidor abrirá la página en el navegador por sí mismo):

./start.sh     # запустить и открыть браузер
./stop.sh      # остановить сервер

Un ./start.sh repetido con el servidor en funcionamiento simplemente abre la página. Manual (si los scripts no son adecuados):

.venv/bin/python src/web/server.py

Abre en el navegador: http://127.0.0.1:8000

Qué puede hacer la página:

• pegar un enlace a una receta de food.ru y pulsar el botón — el servidor elaborará la lista de la compra (la consulta a los sitios tarda 30–90 segundos, se muestra un indicador de carga);

• mostrar una tabla: ingrediente, cantidad, producto en Magnit, precio, cantidad a comprar, importe, enlace al producto;

• guardar la lista en un archivo Excel con el botón «Guardar en Excel».

Los archivos Excel se guardan en la carpeta exports/ en la raíz del proyecto (nombre del tipo shopping_list_<receta>_<fecha>.xlsx).

Conexión a OpenCode

En ~/.config/opencode/opencode.jsonc (global) o opencode.json en la raíz del proyecto, añade la sección mcp — el formato difiere de Claude Desktop (clave mcp, command — array, variables — environment):

{
  "mcp": {
    "recipe-shopping-list": {
      "type": "local",
      "command": [
        "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/.venv/bin/python",
        "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/src/server.py"
      ],
      "environment": {
        "MAGNIT_SHOP_CODE": "543440",
        "MAGNIT_SHOP_TYPE": "dostavka",
        "LOG_LEVEL": "INFO"
      },
      "enabled": true
    }
  }
}

Tras reiniciar OpenCode, el servidor aparecerá en la lista de MCP (comando /mcp en la aplicación). La comprobación desde la terminal (opencode mcp list) en la instalación a través de OpenCode.app no funciona — la CLI es un envoltorio de Electron.

Conexión a Claude Desktop

En claude_desktop_config.json añade (las rutas deben ser absolutas):

{
  "mcpServers": {
    "recipe-shopping-list": {
      "command": "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/.venv/bin/python",
      "args": ["/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/src/server.py"],
      "env": {
        "MAGNIT_SHOP_CODE": "543440",
        "MAGNIT_SHOP_TYPE": "dostavka",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Herramientas

Ejemplo

«Aquí está la receta: https://food.ru/recipes/269806-sous-iz-iogurta-s-ukropom-i-chesnokom-1766588076»

El agente llamará a get_shopping_list y devolverá:

Греческий йогурт — 100г → Йогурт греческий Teos 2% 140г — 89,90 ₽ [ссылка]
Чеснок — 2 зубчик =10г → Чеснок свежий 100г — 45,00 ₽ [ссылка]
...
Итого: 356,70 ₽ · 6 товаров

Pruebas

Pruebas rápidas de lógica (no acceden a los sitios — los parsers se sustituyen por mocks):

.venv/bin/python -m pytest tests/ -v

Pruebas de integración en vivo — abren realmente food.ru y magnit.ru a través de Playwright, como el servidor de producción (~1 minuto, con pausas entre solicitudes):

.venv/bin/python -m pytest -m integration -v

Reglas de las pruebas en vivo: si el sitio no está disponible (red) — la prueba se omite; si el sitio respondió, pero la estructura no es la esperada — la prueba falla (el maquetado ha cambiado, es hora de actualizar los selectores y registrar la lección en LESSONS.md).

Estructura

src/
├── server.py                  # Точка входа MCP-сервера
├── tools/                     # MCP-инструменты (бизнес-логика)
├── integrations/              # Парсеры сайтов (Playwright)
├── models/                    # Pydantic-модели
├── utils/                     # Кэш, ограничитель запросов, валидаторы
└── config/                    # Настройки (.env) и селекторы

Importante saber

• Ambos sitios (food.ru, magnit.ru) son SPA: los datos se cargan mediante JavaScript. Por eso los parsers funcionan a través de Playwright (navegador headless), no mediante HTTP simple.

• Entre solicitudes a los sitios — pausa de 2–5 segundos, los resultados se cachean (recetas durante 24 horas, productos durante 15 minutos).