mcp-recipe-shopping-list

Recipe Shopping List — MCP 서버

다음을 수행할 수 있는 MCP 서버(Model Context Protocol)입니다:

1. food.ru에서 레시피 읽기 — 링크로 재료, 조리 단계, 영양성분(KBJU)을 가져옵니다

2. magnit.ru에서 상품 검색 — 특정 매장을 고려합니다

3. 쇼핑 목록 작성 — 레시피에 맞는 상품을 가격과 함께 찾아 합계를 계산합니다

4. 매장 정보 표시 — 매장 코드로 조회합니다

요약: 레시피 링크를 제공하면 Magnit의 가격과 상품으로 이동하는 직접 링크가 포함된 완성된 쇼핑 목록을 받게 됩니다.

🎓 학습용 프로젝트: 이 프로젝트는 소매 체인의 카테고리 매니저들에게 MCP 서버 구축을 교육하는 데 사용되었습니다. 아이디어와 기술 사양부터 AI 어시스턴트가 사용하는 작동하는 MCP 서버까지 전체 주기를 다루는 실용적인 사례입니다. 참가자들은 AI 에이전트의 도움을 받아 food.ru 레시피 파서, magnit.ru 상품 검색, 가격이 포함된 쇼핑 목록 등 작동하는 애플리케이션을 단 한 번의 수업 시간 안에 완성하며 긍정적인 결과를 얻습니다.

🌐 웹 버전: MCP 인터페이스 외에도 브라우저에서 실행되는 MCP 클라이언트가 필요 없는 로컬 웹 인터페이스가 있습니다. 다음 한 줄로 실행합니다:

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

웹 버전에서는 레시피 링크를 붙여넣고 쇼핑 목록이 포함된 표를 받은 다음 Excel로 저장할 수 있습니다. 자세한 내용은 «웹 인터페이스» 섹션을 참조하세요.

설치

빠른 방법: install.py 설치 프로그램

install.py 스크립트(추가 설치가 필요 없는 Python 표준 라이브러리만 사용)가 가상 환경 생성, 종속성 및 Playwright용 브라우저 설치, .env 생성, 선택한 MCP 클라이언트에 서버 등록, 모든 것이 제대로 작동하는지 확인하는 작업을 모두 자동으로 수행합니다.

Python 3.11+가 필요합니다(uv 권장 — 설치 프로그램이 uv와 일반 Python을 모두 찾습니다).

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

모든 플래그는 선택 사항입니다:

예:

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

수동 설치

Python 3.11+가 필요합니다(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

실행

.venv/bin/python src/server.py

서버는 stdio를 통한 MCP 프로토콜로 작동합니다. 즉, AI 어시스턴트(Claude Desktop, LM Studio 등)가 호출하며, 그 자체로는 터미널에서 "조용히" 대기합니다.

웹 인터페이스

MCP 클라이언트를 연결하고 싶지 않은 사용자를 위한 로컬 웹 페이지입니다. 레시피 링크를 붙여넣으면 쇼핑 목록이 포함된 표와 Excel 저장 버튼을 얻을 수 있습니다.

실행 (서버가 브라우저에서 페이지를 자동으로 엽니다):

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

서버가 실행 중일 때 ./start.sh를 다시 실행하면 페이지가 열립니다. 수동으로 (스크립트가 적합하지 않은 경우):

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

브라우저에서 엽니다: http://127.0.0.1:8000

페이지에서 할 수 있는 작업:

• food.ru 레시피 링크를 붙여넣고 버튼을 누르면 서버가 쇼핑 목록을 수집합니다 (웹사이트 요청에 30~90초 소요, 로딩 표시기 표시)

• 표 표시: 재료, 수량, Magnit 상품, 가격, 구매 수량, 합계, 상품 링크

• «Excel로 저장» 버튼으로 목록을 Excel 파일로 저장

Excel 파일은 프로젝트 루트의 exports/ 폴더에 저장됩니다 (shopping_list_<레시피>_<날짜>.xlsx 형식).

OpenCode에 연결

~/.config/opencode/opencode.jsonc (전역) 또는 프로젝트 루트의 opencode.json에 mcp 섹션을 추가하세요. 형식이 Claude Desktop과 다릅니다 (mcp 키, command는 배열, 변수는 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
    }
  }
}

OpenCode를 다시 시작하면 서버가 MCP 목록(앱의 /mcp 명령)에 나타납니다. OpenCode.app을 통한 설치에서 터미널(opencode mcp list)에서 확인하는 것은 Electron 래퍼이므로 작동하지 않습니다.

Claude Desktop에 연결

claude_desktop_config.json에 추가하세요 (경로는 절대 경여야 합니다):

{
  "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"
      }
    }
  }
}

도구

예시

«레시피입니다: https://food.ru/recipes/269806-sous-iz-iogurta-s-ukropom-i-chesnokom-1766588076»

에이전트가 get_shopping_list를 호출하고 다음을 반환합니다:

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

테스트

빠른 로직 테스트 (웹사이트에 접속하지 않음 — 파서는 목(mock)으로 대체됨):

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

라이브 통합 테스트 — 실제로 Playwright를 통해 food.ru 및 magnit.ru를 열어 프로덕션 서버처럼 작동합니다 (약 1분, 요청 사이에 일시 중지 포함):

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

라이브 테스트 규칙: 사이트에 접속할 수 없으면(네트워크) 테스트를 건너뜁니다. 사이트가 응답했지만 구조가 다르면 테스트가 실패합니다(레이아웃이 변경된 것이므로 선택기를 업데이트하고 LESSONS.md에 교훈을 기록해야 합니다).

구조

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

알아두어야 할 사항

• 두 사이트(food.ru, magnit.ru) 모두 SPA입니다. 데이터는 JavaScript로 로드됩니다. 따라서 파서는 단순 HTTP 대신 Playwright(헤드리스 브라우저)를 통해 작동합니다.

• 사이트 요청 사이에 2~5초의 일시 중지가 있으며 결과는 캐시됩니다(레시피는 24시간, 상품은 15분).