mart-compare-mcp

MCP-сервер, который сравнивает/рекомендует товар A против B (против N товаров) в магазине. Гибридная структура, спроектированная так, чтобы характеристики (страна происхождения/сертификация/пищевая ценность) брались из курируемой БД, а цены/отзывы подтягивались в реальном времени — однако, по состоянию на 2026-08-25, запрос цен/отзывов в реальном времени приостановлен (см. §3).

Сейчас это состояние, в котором реально подтверждены сборка, запуск, тестирование и развёртывание. Включены образцы данных по 5 категориям (молоко/вода/консервированная ветчина/тофу/консервированный тунец), и все 3 инструмента (list_categories/search_products/compare_products) реально вызывались через curl, и их работа подтверждена. Развёрнуто на Render, эндпоинт — https://mart-compare-mcp.onrender.com/mcp (на бесплатном тарифе сервер засыпает при отсутствии трафика). (обновлено 2026-08-25)

1. Локальный запуск

npm install
npm run build   # tsc 컴파일 + data/products/*.json을 dist로 복사
npm start        # http://localhost:3000/mcp 에서 대기

Во время разработки — npm run dev (tsx watch, автоматический перезапуск при сохранении файла).

Проверка здоровья: curl http://localhost:3000/health → {"status":"ok"}

Related MCP server: mcp-supermercados-cl

2. Структура

src/
  index.ts              # Express + Streamable HTTP transport 진입점
  server.ts              # McpServer 인스턴스 생성 + 툴 등록
  tools/compareProducts.ts   # list_categories / search_products / compare_products 3개 툴
  lib/loadProducts.ts    # data/products/*.json 로더 (자체 DB)
  lib/liveData.ts        # 가격/리뷰 실시간 조회 - 현재 항상 null 반환하는 스텁 (§3 참고)
  data/schema.ts          # 제품 스펙 타입 정의
  data/products/*.json    # 카테고리별 큐레이션 데이터 (milk, water, canned-ham, tofu, tuna-can)

3. Что в текущем состоянии является «фейковым»/«незавершённым» (важно)

• Цены/отзывы на самом деле не подключены, и прямо сейчас нет способа их подключить. Изначально планировалось заполнять цены в KR через API поиска Naver Shopping, но этот API полностью прекратил работу с 2026-07-31, и официального заменяющего API нет (фактически подтверждено, что сам пункт «Поиск» исчез из списка «Используемые API» в Naver Developers. Источник: waffleboard.io). В качестве альтернативы рассматривался API поиска Coupang Partners, но из-за трёх причин — ограничение 10 вызовов в час (при 3 подряд ошибках 403 есть риск вечной блокировки аккаунта) + необходимость прохождения проверки при регистрации в Partners + неясность, можно ли использовать его для чистого сравнения цен, поскольку по условиям он предназначен для привлечения партнёрских ссылок — было решено, что регистрироваться должен человек, приняв самостоятельное решение, поэтому пока отложено. OpenAPI 11번가 (11st) тоже искали, но нашлась только документация для продавцов. Интеграция с 楽天市場 (JP) изначально даже не имеет кода. Подробности/метод повторного рассмотрения — см. комментарий в начале lib/liveData.ts.

• В данных по консервированному тунцу и тофу поля насыщенных/трансжирных кислот намеренно убраны. Значения из исходного API Министерства безопасности пищевых продуктов и медикаментов (식약처) в 3–6 раз превышают общее содержание жира в том же продукте (например, жир 15 г, а насыщенных жирных кислот 50 г), что позволяет предположить ошибку сопоставления полей или ошибку исходных данных. Поскольку проблема одинаково проявилась во всех 4 продуктах категории тофу и во всех 4 продуктах консервированного тунца, это выглядит не случайностью, а структурной проблемой самих полей этого API (AMT_NUM23/24) — тогда как в молоке/воде/консервированной ветчине этой проблемы не было. Пока официальная документация не подтвердит заново определение AMT_NUM23/24, эти два поля использовать категорически нельзя. (Обнаружено при тестировании в PlayMCP: 2026-08-25)

• Категории egg (яйца) пока нет. В data/staging/egg.draft.json все 20 результатов поиска по запросу «계란» в API 식약처 оказались переработанными продуктами — печенье из яиц, яичные конфеты, запечённые яйца и т.п., — а сырых яиц (лоток яиц), которые продаются в магазине, не было ни одного, поэтому по итогам проверки всё было отброшено. Для повторного сбора нужно изменить поисковый запрос на «달걀» или сузить до категории яичных продуктов с помощью параметра FOOD_CAT1_NM (крупная категория продуктов питания) и повторить попытку.

• Элементы с пометкой needsVerification: true в файлах данных — это примерные данные, проверка источника которых не завершена. В ответе compare_products этот факт также передаётся в виде note, поэтому использовать эти значения в ответе как факт нельзя.

• В поле certifications внесены только те данные, которые были фактически подтверждены поиском (например, сертификация ERA Института питьевой воды для Jeju Samdasoo). Негативные факты о конкурирующих продуктах, такие как «несоответствие/непрохождение проверки», без проверки не добавлялись ни в коем случае — такая информация может быть сочтена клеветой, поэтому при необходимости её можно заполнять только из официальных первоисточников, таких как официальная информация об отзыве продукции и административных мерах на Food Safety Korea (식약처).

4. Как добавить категорию/продукт

Вручную:

1. Добавьте JSON-файл по категории в src/data/products/ (или добавьте позиции в существующий файл)

2. Следуйте схеме ProductSpec (src/data/schema.ts) — обязательно заполняйте sources, а значения, для которых не удалось найти источник, не вносите, а оставляйте с needsVerification: true + notes

3. Заново выполните npm run build (изменения отразятся только после копирования json в dist)

Автоматический сбор (1-й уровень — API 식약처):

Существование и пищевую ценность корейских продуктов можно массово собирать через Open API базы данных пищевой ценности 식약처. Внимание: заявку на этот API нужно подавать не через поиск на самом сайте foodsafetykorea.go.kr, а через Портал открытых данных (data.go.kr) — если искать на foodsafetykorea.go.kr, выводится другой сервис (ссылочного/L-типа), и подача заявки блокируется.

# 1. https://www.data.go.kr/data/15127578/openapi.do 접속
#    → "활용신청" 버튼 클릭 → 자동승인(개발계정, 트래픽 10,000/일)
# 2. 승인 후 마이페이지에서 서비스키(인증키) 확인
# 3. .env.example을 .env로 복사하고 FOODSAFETY_API_KEY 채우기
cp .env.example .env

# 4. 카테고리별로 수집 (검색어, 우리 카테고리id) - .env가 자동으로 읽혀서 이렇게만 하면 됨
npm run ingest -- 우유 milk

Результат сохраняется не в src/data/products/, а только как черновик в src/data/staging/milk.draft.json. Автоматически он не подхватывается, поэтому откройте этот файл и:

• отберите только фирменные продукты, которые реально продаются в магазине (много шума: исследовательские образцы, готовые блюда и т.п.)

• заполните или удалите позиции с пустым названием бренда

• информацию о сертификатах/отличиях (2-й уровень) этот скрипт заполнить не может, поэтому дополните её отдельным поиском

и перенесите в src/data/products/milk.json только отобранные позиции. Этот скрипт предназначен для быстрого создания черновика пищевой ценности, а не для замены проверки.

Прозрачно сообщаю о проверке: спецификация этого API (Base URL apis.data.go.kr/1471000/FoodNtrCpntDbInfo02, параметры запроса, имена полей AMT_NUM1~157) была фактически подтверждена тем, что я зашёл браузером на страницу data.go.kr и лично прочитал экран спецификации API (Swagger). Что означает каждый код AMT_NUM — документ (Excel) в браузере открыть не удалось, поэтому я перекрёстно проверил по коду сопоставления из проекта с открытым исходным кодом (лицензия ISC) k-mfds-fooddb-mcp-server, который уже реализует этот же API. Сам фактический вызов API здесь выполнить не удалось, поскольку сеть этого контейнера блокирует apis.data.go.kr (host_not_allowed); вместо этого весь поток — сборка запроса → разбор ответа → сопоставление → сохранение файла — был проверен на mock, точно имитирующем реальную схему ответа. Первый вызов с настоящим ключом тебе нужно сделать самому.

5. Развёртывание (Render) — завершено

Развёртывание завершено на бесплатном тарифе Render с привязкой к GitHub-репозиторию (ksbsjh74-code/mart-compare-mcp).

• Проверка здоровья: https://mart-compare-mcp.onrender.com/health

• Эндпоинт для регистрации в PlayMCP: https://mart-compare-mcp.onrender.com/mcp

• Переменные окружения управляются напрямую на вкладке Environment в панели Render (зарегистрирован только FOODSAFETY_API_KEY — ingest-скрипт запускается локально, так что на самом деле он не нужен в рантайме сервера, можно убрать позже)

• При push в ветку main Render автоматически переразвёртывает

• На бесплатном тарифе при отсутствии трафика сервер переходит в спящий режим, и на первый запрос может быть холодный старт (десятки секунд) — при появлении реального трафика стоит рассмотреть переход на платный тариф (Starter, $7/мес)

Баг с постоянным таймаутом проверки здоровья при первом развёртывании (исправлено, коммит d03db8c): при вызове createMcpExpressApp() из @modelcontextprotocol/sdk в src/index.ts без опций значение по умолчанию — host: '127.0.0.1', и в этом случае SDK автоматически подключает middleware защиты от DNS-ребдинга, который отклоняет с кодом 403 все запросы, у которых заголовок Host не равен localhost/127.0.0.1/[::1]. Поскольку проверка здоровья Render и реальные клиентские запросы приходят с Host: mart-compare-mcp.onrender.com, блокировался и /health, из-за чего развёртывание постоянно падало с таймаутом проверки здоровья, хотя приложение по логам нормально привязывалось к порту. Решено явным указанием createMcpExpressApp({ host: "0.0.0.0" }) — это опция, которую обязательно нужно указывать при использовании этого SDK в публичной среде развёртывания; если позже будешь использовать тот же хелпер в других проектах, обрати на это внимание.

6. Процедура регистрации в PlayMCP (проверено по состоянию на 2026-08)

1. Эндпоинт сервера, развёрнутого в §5, должен быть доступен из интернета (путь /mcp должен принимать POST). PlayMCP использует способ регистрации удалённых (remote) MCP-серверов, поэтому локальный stdio-сервер как есть использовать нельзя.

2. Войдите на https://playmcp.kakao.com через аккаунт Kakao

3. В «Регистрация MCP-сервера» введите URL эндпоинта развёрнутого сервера (https://.../mcp)

4. Сначала сервер находится в приватном (временная регистрация) статусе и доступен для тестирования только с вашего аккаунта

5. Чтобы открыть доступ другим пользователям, нужно пройти процедуру проверки партнёра Kakao (детальные требования этой части нужно отдельно уточнить в «Руководстве по использованию» на сайте PlayMCP — это постоянно обновляемая область, поэтому перепроверьте непосредственно перед регистрацией)

7. Предложения по следующим шагам

• Расширение категорий (добавлены тофу/консервированный тунец; яйца отложены из-за проблем с качеством данных)

• Создание Dockerfile/render.yaml

• Создание GitHub-репозитория + завершение развёртывания на Render

• Исследование API для запроса цен в реальном времени (подтверждено прекращение Naver Shopping, рассмотрены Coupang Partners/11번가 и отложено)

• Исправление бага с таймаутом проверки здоровья после развёртывания + подтверждение фактического вызова /mcp (2026-08-25, коммит d03db8c)

• Регистрация в PlayMCP + завершение тестового вызова всех 3 инструментов (list_categories/search_products/compare_products) через реальный чат (2026-08-25, заявка на проверку подана — ожидается результат проверки). В ходе тестирования дополнительно подтверждено, что проблема качества данных по насыщенным/трансжирным кислотам есть не только в консервированном тунце, но и в тофу (отражено в §3 выше)

• Повторный сбор категории egg (повторить с поисковым запросом «달걀» или фильтром FOOD_CAT1_NM)

• (опционально) Повторная попытка запроса цен в реальном времени — пройти проверку регистрации в Coupang Partners и подключить со структурой кэширования с учётом ограничения 10 вызовов в час, либо открыть официальную документацию 11번가 и проверить наличие API общего поиска товаров