mart-compare-mcp

MCP-Server, der im Supermarkt Produkt A vs. B (vs. N Produkte) vergleicht/empfiehlt. Eine Hybrid-Struktur, die so konzipiert ist, dass Spezifikationen (Herkunft/Zertifizierungen/Nährwertangaben) aus einer kuratierten DB stammen, während Preise/Bewertungen per Echtzeitabfrage angebunden werden können – allerdings ist die Echtzeitabfrage von Preisen/Bewertungen mit Stand 2026-08-25 auf Eis gelegt (§3 beachten).

Der aktuelle Stand ist, dass Build, Ausführung, Tests und Deployment tatsächlich verifiziert wurden. Es sind Beispieldaten für 5 Kategorien (Milch/Wasser/Dosenfleisch/Tofu/Thunfischdosen) enthalten, und alle 3 Tools (list_categories/search_products/compare_products) wurden tatsächlich per curl aufgerufen und auf korrekte Funktion geprüft. Der Server ist auf Render deployed, der Endpunkt ist https://mart-compare-mcp.onrender.com/mcp (da es sich um den kostenlosen Plan handelt, schläft er bei fehlendem Traffic ein). (Aktualisiert am 2026-08-25)

1. Lokale Ausführung

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

Während der Entwicklung npm run dev (tsx watch, automatischer Neustart bei Dateispeicherung).

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

Related MCP server: mcp-supermercados-cl

2. Struktur

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. Teile, die im aktuellen Zustand "gefälscht"/"unvollständig" sind (wichtig)

• Preise/Bewertungen sind nicht wirklich angebunden, und es gibt derzeit keine Möglichkeit, sie anzubinden. Ursprünglich sollte die Naver-Shopping-Such-API verwendet werden, um KR-Preise zu füllen, aber diese API wurde mit Wirkung zum 2026-07-31 vollständig eingestellt und es gibt keine offizielle Ersatz-API (im Naver-Entwicklercenter wurde tatsächlich bestätigt, dass der Punkt "Suche" aus der Liste "Verwendete APIs" verschwunden ist. Quelle: waffleboard.io). Als Alternative wurde die Coupang-Partners-Such-API geprüft, aber wegen der Begrenzung auf 10 Aufrufe pro Stunde (Risiko der dauerhaften Kontosperrung bei 3 aufeinanderfolgenden 403-Fehlern) + der Notwendigkeit einer Partners-Anmelde-Prüfung + der Unklarheit, ob die Nutzung für reinen Preisvergleich laut AGB zulässig ist (da der Zweck die Generierung von Affiliate-Links ist), wurde dies vorerst auf Eis gelegt, da eine manuelle Entscheidung und Anmeldung erforderlich wäre. Auch die 11st-OpenAPI wurde gesucht, aber es wurden nur Dokumente für Verkäufer gefunden. Eine 楽天市場(JP)-Anbindung existiert von vornherein nicht im Code. Details/Überprüfungsmethoden siehe Kommentar am Anfang von lib/liveData.ts.

• Bei den Thunfischdosen- und Tofu-Daten wurden die Felder für gesättigte Fettsäuren/Transfettsäuren bewusst weggelassen. Die Originalwerte der Food-Safety-API sind 3~6-mal größer als der Gesamtfettgehalt desselben Produkts (z. B. 15 g Fett, aber 50 g gesättigte Fettsäuren), was auf einen Feldzuordnungsfehler oder einen Fehler in den Originaldaten hindeutet. Da das Problem bei allen 4 Produkten der Tofu-Kategorie und allen 4 Produkten der Thunfischdosen-Kategorie gleichermaßen auftrat, scheint es sich nicht um Zufall, sondern um ein strukturelles Problem dieser API-Felder (AMT_NUM23/24) selbst zu handeln – während dieses Problem bei Milch/Wasser/Dosenfleisch nicht auftrat. Diese beiden Felder dürfen auf keinen Fall verwendet werden, bis die Definition von AMT_NUM23/24 anhand der offiziellen Dokumentation erneut bestätigt wurde. (Entdeckt während PlayMCP-Tests: 2026-08-25)

• Die Kategorie egg (Eier) existiert noch nicht. Bei data/staging/egg.draft.json handelte es sich bei allen 20 Treffern, die die Food-Safety-API bei der Suche nach "계란" lieferte, um verarbeitete Lebensmittel wie Eierkekse/Eiergebäck/gebackene Eier; es gab kein einziges im Supermarkt verkauftes Frischei-Produkt (ein Tablett Eier), daher wurden alle Ergebnisse bei der Prüfung verworfen. Für eine erneute Erfassung sollte der Suchbegriff auf "달걀" geändert oder mit dem Parameter FOOD_CAT1_NM (Lebensmittel-Hauptkategorie) auf Eiprodukte eingegrenzt und erneut versucht werden.

• Datenpunkte mit needsVerification: true in den Datendateien sind Beispieldaten, deren Quellenprüfung noch nicht abgeschlossen ist. Die compare_products-Antwort liefert diese Tatsache ebenfalls als Note mit, daher sollten diese Werte nicht als Fakten in Antworten verwendet werden.

• Das Feld certifications enthält nur tatsächlich durch Suche verifizierte Angaben (z. B. die ERA-Zertifizierung des Trinkwasserinstituts von Jeju Samdasoo). Für Konkurrenzprodukte wurden keine negativen Tatsachen wie "nicht konform/nicht bestanden" ohne Verifizierung aufgenommen – da solche Informationen potenziell rufschädigend sind, sollten sie nur aus primären offiziellen Quellen wie den offiziellen Rückruf-/Verwaltungsmaßnahmen-Informationen von Food Safety Korea (MFDS) stammen.

4. So fügt man Kategorien/Produkte hinzu

Manuell hinzufügen:

1. JSON-Datei pro Kategorie in src/data/products/ hinzufügen (oder Einträge in bestehende Dateien einfügen)

2. Dem ProductSpec-Schema (src/data/schema.ts) folgen – insbesondere sources unbedingt ausfüllen; Werte ohne gefundene Quelle nicht aufnehmen, sondern mit needsVerification: true + notes kennzeichnen

3. npm run build erneut ausführen (die JSON-Dateien müssen nach dist kopiert werden, damit sie übernommen werden)

Automatische Erfassung (Ebene 1 – MFDS-API):

Existenz/Nährwertangaben koreanischer Produkte können massenhaft über die Open API der Lebensmittel-Nährstoffdatenbank des MFDS erfasst werden. Achtung: Diese API muss nicht über die Suche auf der Website foodsafetykorea.go.kr selbst, sondern über das Portal für öffentliche Daten (data.go.kr) beantragt werden – eine Suche auf foodsafetykorea.go.kr liefert einen anderen (Link-/L-Typ-)Dienst, wodurch der Antrag blockiert wird.

# 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

Die Ergebnisse werden nicht in src/data/products/, sondern nur als Entwurf in src/data/staging/milk.draft.json gespeichert. Da sie nicht automatisch übernommen werden, sollte die Datei geöffnet werden, um:

• nur echte Markenprodukte aus dem Supermarkt herauszufiltern (es gibt viel Rauschen wie Forschungsproben/Zubereitungslebensmittel)

• Einträge mit leerem Markennamen zu ergänzen oder zu verwerfen

• Zertifizierungs-/Alleinstellungsinformationen (Ebene 2) kann dieses Skript nicht ausfüllen, daher separat recherchieren und ergänzen

Nur die bereinigten Einträge nach src/data/products/milk.json verschieben. Dieses Skript dient nur dazu, schnell einen Nährwert-Entwurf zu erstellen; es ersetzt keine Qualitätsprüfung.

Transparenz zur Verifizierung: Die Spezifikation dieser API (Base-URL apis.data.go.kr/1471000/FoodNtrCpntDbInfo02, Anfrageparameter, Feldnamen AMT_NUM1~157) wurde tatsächlich durch direkten Browserzugriff auf die data.go.kr-Seite und Lesen des API-Spezifikationsbildschirms (Swagger) verifiziert. Welcher Nährstoff hinter welchem AMT_NUM-Code steckt, konnte nicht über das Dokument (Excel) im Browser geprüft werden; stattdessen wurde eine Querverifizierung mit dem Mapping-Code des Open-Source-Projekts (ISC-Lizenz) k-mfds-fooddb-mcp-server durchgeführt, das dieselbe API bereits implementiert hat. Der tatsächliche API-Aufruf selbst konnte hier nicht durchgeführt werden, da das Container-Netzwerk apis.data.go.kr blockiert (host_not_allowed); stattdessen wurde der gesamte Ablauf (Anfrage zusammenstellen → Antwort parsen → Mapping → Dateispeicherung) mit einem Mock verifiziert, der das reale Antwortschema nachbildet. Den ersten Aufruf mit einem echten Schlüssel musst du selbst durchführen.

5. Deployment (Render) – abgeschlossen

Deployment über das GitHub-Repo (ksbsjh74-code/mart-compare-mcp) mit dem Render-Free-Plan abgeschlossen.

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

• Endpunkt für PlayMCP-Registrierung: https://mart-compare-mcp.onrender.com/mcp

• Umgebungsvariablen werden direkt im Environment-Tab des Render-Dashboards verwaltet (nur FOODSAFETY_API_KEY registriert – da das Ingest-Skript lokal läuft, wird es zur Serverlaufzeit eigentlich nicht benötigt; kann später aufgeräumt werden)

• Bei Push auf den main-Branch deployt Render automatisch neu

• Beim kostenlosen Plan schläft der Dienst bei fehlendem Traffic ein; beim ersten Request kann es zu einem Cold Start (mehrere zehn Sekunden) kommen – bei realem Traffic sollte ein Upgrade auf einen kostenpflichtigen Plan (Starter, $7/Monat) in Betracht gezogen werden

Bug, bei dem der Healthcheck beim ersten Deployment ständig timeoutete (behoben, Commit d03db8c): Wenn createMcpExpressApp() aus @modelcontextprotocol/sdk in src/index.ts ohne Optionen aufgerufen wird, ist der Standardwert host: '127.0.0.1'; in diesem Fall fügt das SDK automatisch eine Middleware zum Schutz vor DNS-Rebinding ein, die alle Anfragen mit einem Host-Header, der nicht localhost/127.0.0.1/[::1] ist, mit 403 ablehnt. Da Render-Healthchecks und echte Client-Anfragen mit Host: mart-compare-mcp.onrender.com eingehen, wurde auch /health blockiert – das Deployment schlug trotz normaler Port-Bindung (laut Logs) wiederholt mit Healthcheck-Timeout fehl. Gelöst durch explizites createMcpExpressApp({ host: "0.0.0.0" }) – diese Option muss bei Verwendung dieses SDKs in öffentlichen Deployment-Umgebungen zwingend gesetzt werden; Vorsicht, wenn derselbe Helper später in anderen Projekten verwendet wird.

6. PlayMCP-Registrierungsverfahren (Stand 2026-08 bestätigt)

1. Der in §5 deployed Server-Endpunkt muss aus dem Internet erreichbar sein (der /mcp-Pfad muss POST entgegennehmen). PlayMCP verwendet die Remote-MCP-Server-Registrierung, daher kann ein lokaler stdio-Server nicht direkt verwendet werden.

2. Auf https://playmcp.kakao.com mit einem Kakao-Konto anmelden

3. Bei "MCP-Server registrieren" die Endpunkt-URL des deployed Servers (https://.../mcp) eingeben

4. Zunächst ist der Server privat (vorläufige Registrierung) und nur im eigenen Konto testbar

5. Für die Veröffentlichung für andere Nutzer ist ein Kakao-Partner-Verifizierungsverfahren erforderlich (die detaillierten Anforderungen hierfür müssen separat im "Nutzungsleitfaden" auf der PlayMCP-Website geprüft werden – da dieser Bereich ständig aktualisiert wird, sollte er unmittelbar vor der Registrierung erneut geprüft werden)

7. Vorschläge für nächste Schritte

• Kategorien erweitert (Tofu/Thunfischdosen hinzugefügt; Eier wegen Datenqualitätsproblemen auf Eis gelegt)

• Dockerfile/render.yaml erstellt

• GitHub-Repo erstellt + Render-Deployment abgeschlossen

• Recherche zu Preis-Echtzeitabfrage-APIs (Naver-Shopping-Einstellung bestätigt; Coupang-Partners/11st geprüft und auf Eis gelegt)

• Healthcheck-Timeout-Bug nach Deployment behoben + tatsächlicher /mcp-Aufruf verifiziert (2026-08-25, Commit d03db8c)

• PlayMCP-Registrierung + Test aller 3 Tools (list_categories/search_products/compare_products) per echtem Chat abgeschlossen (2026-08-25, Prüfungsantrag eingereicht – Ergebnis ausstehend). Bei den Tests wurde zusätzlich bestätigt, dass das Datenqualitätsproblem bei gesättigten Fettsäuren/Transfettsäuren nicht nur bei Thunfischdosen, sondern auch bei Tofu auftritt (in §3 oben berücksichtigt)

• egg-Kategorie neu erfassen (erneuter Versuch mit Suchbegriff "달걀" oder FOOD_CAT1_NM-Filter)

• (Optional) Erneuter Versuch der Preis-Echtzeitabfrage – entweder über die Coupang-Partners-Anmeldeprüfung mit einer Caching-Struktur, die die Begrenzung auf 10 Aufrufe pro Stunde berücksichtigt, oder durch direktes Öffnen der offiziellen 11st-Dokumentation, um zu prüfen, ob eine allgemeine Produktsuch-API existiert