mart-compare-mcp

Servidor MCP que compara/recomienda producto A vs B (vs N) en el supermercado. Las especificaciones (origen/certificación/información nutricional) provienen de una base de datos de curación, mientras que el precio/reseñas se pueden adjuntar mediante consulta en tiempo real: una estructura híbrida diseñada para ello. No obstante, la consulta en tiempo real de precio/reseñas está en pausa a fecha de 2026-08-25 (ver §3).

Actualmente el estado es que se ha verificado la compilación, ejecución, pruebas y despliegue reales. Incluye datos de muestra de 5 categorías (leche/agua embotellada/jamón en lata/tofu/lata de atún), y las 3 herramientas (list_categories/search_products/compare_products) se han invocado todas realmente con curl y se ha confirmado su funcionamiento correcto. Está desplegado en Render y el endpoint es https://mart-compare-mcp.onrender.com/mcp (como es el plan gratuito, se duerme si no hay tráfico). (Actualizado el 2026-08-25)

1. Ejecución local

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

Durante el desarrollo, usar npm run dev (tsx watch, reinicio automático al guardar el archivo).

Healthcheck: curl http://localhost:3000/health → {"status":"ok"}

Related MCP server: Trader Joe's MCP Server

2. Estructura

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. Partes que actualmente son "falsas"/"incompletas" (importante)

• El precio/las reseñas no están conectados realmente y no hay forma de conectarlos por ahora. Originalmente se intentó completar los precios KR con la API de búsqueda de Naver Shopping, pero esta API se cerró por completo el 2026-07-31 y no existe una API oficial de reemplazo (se confirmó de forma real que el propio elemento "Búsqueda" desapareció de la lista de "APIs en uso" del Centro de desarrolladores de Naver. Fuente: waffleboard.io). Como alternativa se revisó la API de búsqueda de Coupang Partners, pero por estas tres razones — límite de 10 llamadas por hora (riesgo de suspensión permanente de la cuenta si hay 3 errores 403 consecutivos) + necesidad de pasar la revisión de registro de Partners + no está claro si por los términos de uso, cuyo propósito es la generación de enlaces de afiliados, se puede usar para comparación de precios pura — se requiere que una persona decida y se registre, así que se dejó en pausa por ahora. También se buscó la OpenAPI de 11st, pero solo se confirmó documentación para vendedores. La integración con 楽天市場 (JP) ni siquiera tiene código desde el principio. Consulta el comentario al inicio de lib/liveData.ts para más detalles/cómo reexaminarlo.

• En los datos de lata de atún y tofu, los campos de ácidos grasos saturados/ácidos grasos trans se omitieron intencionalmente. El valor original de la API del Ministerio de Alimentos y Medicamentos de Corea (MFDS) es de 3 a 6 veces mayor que el contenido total de grasa del mismo producto (ej.: 15 g de grasa pero 50 g de ácidos grasos saturados), por lo que se sospecha un error de mapeo de campos o un error en los datos originales. Como el problema apareció de forma idéntica en los 4 productos de la categoría de tofu y en los 4 de lata de atún, no parece casualidad sino un problema estructural del propio campo de esta API (AMT_NUM23/24) — en cambio, en leche/agua embotellada/jamón en lata no hubo este problema. No usar jamás estos dos campos hasta volver a confirmar la definición de AMT_NUM23/24 con la documentación oficial. (Descubierto durante pruebas con PlayMCP: 2026-08-25)

• La categoría egg (huevo) aún no existe. En data/staging/egg.draft.json, los 20 resultados obtenidos al buscar "계란" (huevo) en la API del MFDS eran todos alimentos procesados como galletas de huevo, dulces de huevo o huevos horneados, y no había ni un solo producto de huevo fresco (una bandeja de huevos) que se venda en el supermercado, así que tras la revisión se descartaron todos. Para volver a recopilar, cambiar el término de búsqueda a "달걀" o reducir con el parámetro FOOD_CAT1_NM (clasificación principal de alimentos) al grupo de productos procesados de huevo y reintentar.

• Los elementos con needsVerification: true en los archivos de datos son datos de ejemplo cuya verificación de fuente no ha terminado. La respuesta de compare_products también incluye este hecho como nota, así que no se debe usar este valor como si fuera un hecho real en las respuestas.

• El campo certifications solo incluye lo que se confirmó realmente mediante búsqueda (ej.: certificación ERA del Instituto de Investigación del Agua Potable de Jeju Samdasu). No se ha incluido ningún hecho negativo como "no apto/no aprobado" sobre productos competidores sin verificar — como este tipo de información puede constituir difamación, si se quiere incluir, debe llenarse únicamente con fuentes oficiales primarias como la información oficial de retirada/sanción administrativa de Food Safety Korea (MFDS).

4. Cómo añadir categorías/productos

Añadir manualmente:

1. Añadir un archivo json por categoría en src/data/products/ (o añadir elementos a un archivo existente)

2. Seguir el esquema ProductSpec (src/data/schema.ts) — en particular, llenar obligatoriamente sources, y los valores cuya fuente no se encuentre no incluirlos, sino dejarlos con needsVerification: true + notas

3. Ejecutar npm run build de nuevo (el json debe copiarse a dist para que se refleje)

Recopilación automática (capa 1 - API del MFDS):

La existencia/información nutricional de productos coreanos se puede recopilar en masa con la API abierta de la Base de Datos de Componentes Nutricionales de Alimentos del MFDS. Atención: esta API no es la búsqueda del propio sitio foodsafetykorea.go.kr, sino que debe solicitarse a través del Portal de Datos Públicos (data.go.kr) — si se busca en foodsafetykorea.go.kr, aparece otro servicio (tipo enlace/tipo L) y la solicitud se bloquea.

# 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

El resultado se guarda solo como borrador en src/data/staging/milk.draft.json, no en src/data/products/. Como no se refleja automáticamente, abre este archivo y:

• selecciona solo productos de marcas que se vendan realmente en el supermercado (hay mucho ruido como muestras de investigación/alimentos preparados)

• completa o descarta los elementos con nombre de marca vacío

• la información de certificación/diferenciación (capa 2) no la puede completar este script, así que búscala por separado y refuérzala

Solo los elementos depurados se trasladan a src/data/products/milk.json. Este script sirve para crear rápidamente un borrador de información nutricional; no sustituye la revisión.

Transparencia sobre la verificación: esta especificación de API (URL base apis.data.go.kr/1471000/FoodNtrCpntDbInfo02, parámetros de solicitud, nombres de campos AMT_NUM1~157) se confirmó accediendo realmente con un navegador a la página de data.go.kr y leyendo directamente la pantalla de especificación de la API (Swagger). Como no se pudo abrir el documento (Excel) con el navegador para ver qué nutriente corresponde a cada código AMT_NUM, se verificó de forma cruzada con el código de mapeo del proyecto de código abierto (licencia ISC) k-mfds-fooddb-mcp-server, que ya implementa la misma API. La llamada real a la API no se pudo hacer aquí porque la red de este contenedor bloquea apis.data.go.kr (host_not_allowed); en su lugar, se verificó todo el flujo — ensamblaje de la solicitud → análisis de la respuesta → mapeo → guardado del archivo — con un mock que imita fielmente el esquema de respuesta real. La primera llamada con una clave real debes hacerla tú mismo.

5. Despliegue (Render) - completado

Despliegue completado en el plan gratuito de Render conectando el repositorio de GitHub (ksbsjh74-code/mart-compare-mcp).

• Healthcheck: https://mart-compare-mcp.onrender.com/health

• Endpoint para registro en PlayMCP: https://mart-compare-mcp.onrender.com/mcp

• Las variables de entorno se gestionan directamente en la pestaña Environment del panel de Render (solo se ha registrado FOODSAFETY_API_KEY — como el script de ingest se ejecuta localmente, en realidad no se necesita en el runtime del servidor; se puede limpiar más adelante)

• Al hacer push a la rama main, Render se redespliega automáticamente

• En el plan gratuito, si no hay tráfico entra en estado de suspensión y la primera solicitud puede tener un arranque en frío (decenas de segundos) — si hay tráfico real de uso, considerar la conversión al plan de pago (Starter, $7/mes)

Bug por el que el healthcheck seguía dando timeout en el primer despliegue (corregido, commit d03db8c): en src/index.ts, al llamar a createMcpExpressApp() de @modelcontextprotocol/sdk sin opciones, el valor predeterminado es host: '127.0.0.1'; en ese caso, el SDK añade automáticamente un middleware de prevención de DNS rebinding que rechaza con 403 todas las solicitudes cuyo encabezado Host no sea localhost/127.0.0.1/[::1]. Como el healthcheck de Render y las solicitudes reales de los clientes llegan con Host: mart-compare-mcp.onrender.com, incluso /health quedaba bloqueado, y aunque la aplicación se vinculaba correctamente al puerto según los logs, el despliegue fallaba continuamente por timeout del healthcheck. Se resolvió especificando explícitamente createMcpExpressApp({ host: "0.0.0.0" }) — es una opción que hay que incluir obligatoriamente al usar este SDK en entornos de despliegue público, así que si más adelante se usa el mismo helper en otros proyectos, tener cuidado.

6. Procedimiento de registro en PlayMCP (contenido confirmado a fecha de 2026-08)

1. El endpoint del servidor desplegado en §5 debe ser accesible desde internet (la ruta /mcp debe aceptar POST). Como PlayMCP usa el método de registro de servidores MCP remotos, un servidor stdio local no se puede usar tal cual.

2. Iniciar sesión con cuenta de Kakao en https://playmcp.kakao.com

3. En "Registro de servidor MCP", introducir la URL del endpoint del servidor desplegado (https://.../mcp)

4. Al principio queda en estado privado (registro temporal) y solo se puede probar desde tu propia cuenta

5. Para hacerlo público para otros usuarios, hay que pasar el proceso de verificación de socio de Kakao (los requisitos detallados de esta parte deben consultarse por separado en la "Guía de uso" dentro del sitio de PlayMCP — es un área que se actualiza continuamente, así que volver a verificar justo antes del registro)

7. Propuesta de siguientes pasos

• Ampliación de categorías (añadidos tofu/lata de atún; huevo en pausa por problemas de calidad de datos)

• Redacción de Dockerfile/render.yaml

• Creación del repositorio de GitHub + despliegue en Render completado

• Investigación de API de consulta de precios en tiempo real (confirmado el cierre de Naver Shopping, revisados Coupang Partners/11st y en pausa)

• Corrección del bug de timeout del healthcheck tras el despliegue + verificación de la llamada real a /mcp completada (2026-08-25, commit d03db8c)

• Registro en PlayMCP + prueba de llamada de las 3 herramientas (list_categories/search_products/compare_products) todas mediante chat real completada (2026-08-25, se envió la solicitud de revisión - en espera del resultado de la revisión). Durante las pruebas se confirmó además que el problema de calidad de datos de ácidos grasos saturados/ácidos grasos trans existe no solo en la lata de atún sino también en el tofu (reflejado en §3 arriba)

• Recopilación de nuevo de la categoría egg (reintentar con el término de búsqueda "달걀" o con el filtro FOOD_CAT1_NM)

• (Opcional) Reintentar la consulta de precios en tiempo real - pasar la revisión de registro de Coupang Partners y conectarla con una estructura de caché que tenga en cuenta el límite de 10 llamadas por hora, o abrir directamente los documentos oficiales de 11st para confirmar si existe una API de búsqueda general de productos