mart-compare-mcp

マートで製品A vs B（vs N個）を比較・推薦してくれるMCPサーバー。スペック（原産地/認証/栄養情報）は キュレーションDB、価格/レビューはリアルタイム照会で付与できるように設計したハイブリッド構造 - ただし、価格/レビューの リアルタイム照会は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. 現状で「偽物」/「未完成」の部分（重要）

• 価格/レビューは実際には接続されておらず、今すぐ接続する方法がない。 もともとネイバーショッピング検索APIで KR価格を埋めようとしたが、このAPIは2026-07-31をもって完全終了しており、公式の代替APIがない （ネイバー開発者センターの「使用API」リストから「検索」項目自体が消えたことを実際に確認した。出典: waffleboard.io）。 代替としてクーパン パートナーズ検索APIを検討したが、時間あたり呼び出し10回制限（3回連続403ならアカウント 永久停止のリスク）+ パートナーズ登録審査が必要 + 規約上、用途がアフィリエイトリンク誘導のため純粋な価格比較に 使ってもよいか不明確、この3つの理由で人が直接判断して登録する必要があるため、ひとまず保留した。 11番街OpenAPIも探したが、セラー専用ドキュメントのみ確認された。楽天市場（JP）連携はそもそもコードもない。 詳細/再検討方法は lib/liveData.ts 冒頭のコメント参照。

• ツナ缶・豆腐データで飽和脂肪酸/トランス脂肪酸フィールドは意図的に省いた。 食品医薬品安全処APIの元の値が 同じ製品の総脂肪含有量より3〜6倍大きく（例: 脂肪15gなのに飽和脂肪酸50g）、フィールドマッピングエラーまたは 元データのエラーが疑われる。豆腐カテゴリ4製品すべてとツナ缶4製品すべてで同様に 現れた問題なので、偶然ではなくこのAPIフィールド（AMT_NUM23/24）自体の構造的問題と見られる - 一方、牛乳/ ミネラルウォーター/缶詰ハムではこの問題はなかった。公式ドキュメントでAMT_NUM23/24の定義を再確認するまで、この 2つのフィールドは絶対に使わないこと。（PlayMCPテスト中に発見: 2026-08-25）

• egg（卵）カテゴリはまだない。 data/staging/egg.draft.jsonは食品医薬品安全処APIで「계란」と 検索して出た20件すべてが卵クッキー/卵菓子/焼き卵などの加工食品で、マートで売っている生卵（卵 1パック）製品が1つもなかったため、検収結果すべて破棄した。再収集するには検索語を「달걀」に変えるか FOOD_CAT1_NM（食品大分類）パラメータで卵加工品類に絞って再試行すること。

• データファイルに needsVerification: true が付いた項目は出典検証が終わっていないサンプルデータ。 compare_products レスポンスにもこの事実をnoteとして一緒に返すので、この値を事実のように回答に使ってはいけない。

• certifications フィールドは検索で実際に確認したものだけ入れた（例: 済州三多水 飲用水研究所 ERA認証）。 競合製品に対して「不適合/不合格」のような否定的な事実は検証されていないままでは絶対に入れていない — こういう情報は名誉毀損の恐れがあるため、入れる場合は必ず食品安全国家（食品医薬品安全処）公式回収・行政処分 情報のような1次公式ソースのみで埋めること。

4. カテゴリ/製品の追加方法

手動で追加:

1. src/data/products/ にカテゴリ別jsonファイルを追加（または既存ファイルに項目を追加）

2. ProductSpec スキーマ（src/data/schema.ts）に従うこと — 特に sources を必ず埋め、 出典が見つからない値は入れずに needsVerification: true + notesで残すこと

3. npm run build を再実行（jsonがdistにコピーされて初めて反映される）

自動収集（1層 - 食品医薬品安全処API）:

韓国製品の存在/栄養情報は食品医薬品安全処 食品栄養成分DB 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コードがそれぞれどの栄養素かを示すドキュメント（エクセル）は ブラウザで開けなかったため、同じAPIをすでに実装しているオープンソース（ISCライセンス）プロジェクト k-mfds-fooddb-mcp-serverの マッピングコードでクロス確認した。実際のAPI呼び出し自体はこのコンテナネットワークが apis.data.go.kr を ブロックしているため（host_not_allowed）ここではできず、代わりに実際のレスポンススキーマをそのまま模したmockで リクエスト組み立て→レスポンス解析→マッピング→ファイル保存の全体フローを検証した。本物のキーでの最初の呼び出しは自分で直接行う必要がある。

5. デプロイ（Render） - 完了

GitHub repo（ksbsjh74-code/mart-compare-mcp） 連携してRender Freeプランでデプロイ完了。

• ヘルスチェック: https://mart-compare-mcp.onrender.com/health

• PlayMCP登録用エンドポイント: https://mart-compare-mcp.onrender.com/mcp

• 環境変数はRenderダッシュボードのEnvironmentタブで直接管理（FOODSAFETY_API_KEYのみ登録済み - ingestスクリプトはローカルで回すものなので実はサーバーランタイムには不要、後で整理してもよい）

• main ブランチにpushするとRenderが自動で再デプロイする

• 無料プランはトラフィックがないとスリープ状態になり、最初のリクエストでコールドスタート（数十秒）が発生することがある — 実使用トラフィックが出たら有料プラン（Starter、$7/月）への切り替えを検討

初回デプロイ時にヘルスチェックがタイムアウトし続けたバグ（修正済み、コミット d03db8c）: src/index.ts で @modelcontextprotocol/sdk の createMcpExpressApp() をオプションなしで呼び出すとデフォルト値が host: '127.0.0.1' になり、この場合SDKがDNSリバインディング防止ミドルウェアを自動で挟むため、Host ヘッダーが localhost/127.0.0.1/[::1] でないすべてのリクエストを403で拒否する。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 にカカオアカウントでログイン

3. 「MCPサーバー登録」でデプロイしたサーバーのエンドポイントURL（https://.../mcp）を入力

4. 最初は非公開（仮登録）状態で自分のアカウントでのみテスト可能

5. 他のユーザーに公開するにはカカオパートナー検証手続きを経る必要がある（この部分の詳細要件は PlayMCPサイト内の「利用ガイド」で別途確認が必要 — 継続的に更新される領域なので 登録直前に再確認すること）

7. 次のステップ提案

• カテゴリ拡張（豆腐/ツナ缶追加、卵はデータ品質問題で保留）

• Dockerfile/render.yaml作成

• GitHub repo作成 + Renderデプロイ完了

• 価格リアルタイム照会API調査（ネイバーショッピング終了確認、クーパンパートナーズ/11番街検討後保留）

• デプロイ後のヘルスチェックタイムアウトバグ修正 + /mcp 実際の呼び出し検証完了（2026-08-25、コミット d03db8c）

• PlayMCP登録 + 実際のチャットで3つのツール（list_categories/search_products/compare_products） すべて呼び出しテスト完了（2026-08-25、審査リクエスト提出済み - 審査結果待ち）。テスト中、 飽和脂肪酸/トランス脂肪酸データ品質問題がツナ缶だけでなく豆腐にもあることを追加で確認した （上記§3に反映）

• eggカテゴリ再収集（検索語「달걀」またはFOOD_CAT1_NMフィルタで再試行）

• （任意）価格リアルタイム照会に再挑戦 - クーパンパートナーズ登録審査を受け、時間あたり10回制限を考慮した キャッシュ構造で接続するか、11番街の公式ドキュメントを直接開いて一般商品検索APIの存在有無を確認