mart-compare-mcp

An MCP server that compares/recommends product A vs B (vs N products) at the mart. It's designed as a hybrid structure where specs (origin/certification/nutrition info) come from a curated DB, and price/reviews can be attached via real-time lookup - however, real-time price/review lookup is on hold as of 2026-08-25 (see §3).

It's currently confirmed to actually build, run, test, and deploy. Sample data for 5 categories (milk/water/canned ham/tofu/canned tuna) is included, and all 3 tools (list_categories/search_products/compare_products) have been verified working via actual curl calls. It's deployed on Render at endpoint https://mart-compare-mcp.onrender.com/mcp (free plan, so it sleeps when there's no traffic). (Updated 2026-08-25)

1. Local execution

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

During development, use npm run dev (tsx watch, auto-restarts on file save).

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

Related MCP server: Trader Joe's MCP Server

2. Structure

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. Parts that are "fake"/"incomplete" in the current state (important)

• Price/reviews aren't actually connected, and there's no immediate way to connect them. I originally tried to fill KR prices with the Naver Shopping search API, but this API was fully discontinued as of 2026-07-31 with no official replacement (confirmed that the "Search" item itself has disappeared from the "APIs in use" list in the Naver Developer Center. Source: waffleboard.io). As an alternative, I reviewed the Coupang Partners search API, but three issues - the 10 calls/hour limit (risk of permanent account ban after 3 consecutive 403s) + the need to pass Partners membership review + unclear whether it's allowed for pure price comparison given the terms require affiliate link promotion - mean a human needs to make the judgment call on signing up, so it's on hold for now. I also looked into 11st OpenAPI but only found seller-only documentation. There's no code at all for Rakuten Market (JP) integration. See the comments at the top of lib/liveData.ts for details/re-evaluation approach.

• Saturated fatty acid/trans fatty acid fields were intentionally omitted from canned tuna and tofu data. The original values from the Ministry of Food and Drug Safety (MFDS) API are 3~6x larger than the same product's total fat content (e.g., 15g fat but 50g saturated fatty acids), which suggests a field mapping error or original data error. Since this appeared identically across all 4 tofu products and all 4 canned tuna products, it's not a coincidence but appears to be a structural problem with this API's fields (AMT_NUM23/24) themselves - whereas milk/water/canned ham didn't have this problem. Do not use these two fields until the AMT_NUM23/24 definitions are re-confirmed via official documentation. (Discovered during PlayMCP testing: 2026-08-25)

• The egg category doesn't exist yet. data/staging/egg.draft.json contains 20 results from searching "계란" (egg) in the MFDS API, but all of them were processed foods like egg cookies/egg snacks/roasted eggs - not a single fresh egg (a carton of eggs) sold at the mart, so all results were discarded after review. To recollect, change the search term to "달걀" or narrow down to egg processed products using the FOOD_CAT1_NM (food major category) parameter and retry.

• Items with needsVerification: true in the data files are sample data whose source verification isn't complete. The compare_products response also includes this fact as a note, so don't use these values as facts in answers.

• The certifications field only contains items actually verified through search (e.g., Jeju Samdasoo Drinking Water Research Institute ERA certification). No negative facts like "non-compliant/failed" about competing products were ever added without verification - such information carries defamation risk, so if it must be added, only use primary official sources like the Food Safety Korea (MFDS) official recall/administrative disposition information.

4. How to add categories/products

Manually:

1. Add a per-category json file to src/data/products/ (or add items to an existing file)

2. Follow the ProductSpec schema (src/data/schema.ts) - especially, always fill in sources, and don't include values without a source; instead leave them as needsVerification: true + notes

3. Run npm run build again (json must be copied to dist to take effect)

Automated collection (Layer 1 - MFDS API):

The existence/nutrition info of Korean products can be bulk-collected via the MFDS Food Nutrition Composition DB Open API. Note: This API must be requested through the Public Data Portal (data.go.kr), not the foodsafetykorea.go.kr site search itself - searching on foodsafetykorea.go.kr returns a different (link-type/L-type) service that blocks the application.

# 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

Results are saved only as a draft to src/data/staging/milk.draft.json, not to src/data/products/. Since it's not automatically applied, open this file and:

• Keep only branded products actually sold at the mart (lots of noise like research samples/processed foods)

• Fill in or discard items with empty brand names

• Certification/differentiation info (Layer 2) can't be filled by this script, so search separately and supplement

Move only the cleaned items into src/data/products/milk.json. This script is for quickly producing nutrition info drafts - it doesn't replace human review.

Transparency on verification: This API spec (Base URL apis.data.go.kr/1471000/FoodNtrCpntDbInfo02, request parameters, AMT_NUM1~157 field names) was confirmed by actually visiting the data.go.kr page in a browser and reading the API spec (Swagger) screen directly. Since I couldn't open the documentation (Excel) in a browser to see what each AMT_NUM code corresponds to, I cross-checked with the mapping code from an open-source (ISC licensed) project that already implements the same API, k-mfds-fooddb-mcp-server. I couldn't make actual API calls from here because this container network blocks apis.data.go.kr (host_not_allowed), so instead I verified the entire flow - request assembly → response parsing → mapping → file saving - using a mock that mimics the actual response schema. You'll need to make the first call with a real key yourself.

5. Deployment (Render) - Complete

Deployed on the Render Free plan connected to the GitHub repo (ksbsjh74-code/mart-compare-mcp).

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

• Endpoint for PlayMCP registration: https://mart-compare-mcp.onrender.com/mcp

• Environment variables are managed directly in the Render dashboard Environment tab (only FOODSAFETY_API_KEY is registered - since the ingest script runs locally, it's not actually needed at server runtime; can be cleaned up later)

• Pushing to the main branch triggers automatic redeployment by Render

• The free plan goes to sleep when there's no traffic, and the first request may have a cold start (tens of seconds) - if real traffic materializes, consider switching to a paid plan (Starter, $7/month)

Bug where the health check kept timing out on first deployment (fixed, commit d03db8c): When calling createMcpExpressApp() from @modelcontextprotocol/sdk without options in src/index.ts, the default is host: '127.0.0.1', in which case the SDK automatically adds DNS rebinding protection middleware that rejects all requests with a 403 unless the Host header is localhost/127.0.0.1/[::1]. Since Render's health check and real client requests come in with Host: mart-compare-mcp.onrender.com, /health was blocked too, so the deployment kept failing with health check timeouts even though the app was binding to the port normally per the logs. Fixed by explicitly passing createMcpExpressApp({ host: "0.0.0.0" }) - this option is mandatory when using this SDK in a public deployment environment, so be careful if you use the same helper in other projects later.

6. PlayMCP registration procedure (confirmed as of 2026-08)

1. The endpoint of the server deployed in §5 must be accessible from the internet (the /mcp path must accept POST). PlayMCP uses remote MCP server registration, so a local stdio server can't be used as-is.

2. Log in with a Kakao account at https://playmcp.kakao.com

3. In "MCP server registration", enter the deployed server's endpoint URL (https://.../mcp)

4. Initially it's in private (temporary registration) status, testable only from your own account

5. To make it public to other users, you must go through Kakao partner verification (detailed requirements for this need to be checked separately in the "Usage Guide" on the PlayMCP site - this area is continuously updated, so re-check right before registering)

7. Next step suggestions

• Category expansion (added tofu/canned tuna; eggs on hold due to data quality issues)

• Dockerfile/render.yaml written

• GitHub repo created + Render deployment complete

• Real-time price lookup API research (confirmed Naver Shopping discontinued; reviewed Coupang Partners/11st and put on hold)

• Post-deployment health check timeout bug fixed + /mcp actual call verified (2026-08-25, commit d03db8c)

• PlayMCP registration + actual chat testing of all 3 tools (list_categories/search_products/compare_products) complete (2026-08-25, review request submitted - awaiting review results). During testing, additionally confirmed that the saturated/trans fatty acid data quality issue exists in tofu as well as canned tuna (reflected in §3 above)

• Re-collect egg category (retry with search term "달걀" or FOOD_CAT1_NM filter)

• (Optional) Retry real-time price lookup - either apply for Coupang Partners review and integrate with a caching structure that accounts for the 10 calls/hour limit, or open 11st's official docs directly to check whether a general product search API exists