mart-compare-mcp

在超市中比较/推荐产品 A vs B（vs N 个）的 MCP 服务器。规格（原产地/认证/营养信息）采用 混合结构，设计为可从策展数据库获取，价格/评论则通过实时查询附加——但价格/评论的 实时查询截至 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. 当前状态下"虚假"/"未完成"的部分（重要）

• 价格/评论尚未实际接入，且目前没有可立即接入的方法。 原本想用 Naver Shopping 搜索 API 来填充 KR 价格，但该 API 已于 2026-07-31 完全终止，且没有官方替代 API （已实际确认 Naver 开发者中心"使用中 API"列表中"搜索"项目本身已消失。来源： waffleboard.io）。 作为替代方案审查了 Coupang Partners 搜索 API，但由于每小时调用 10 次的限制（连续 3 次 403 有账号永久封禁风险）+ 需要 Partners 注册审核 + 条款上用途是引导联盟链接，是否可用于纯价格 比较不明确，这三点需要人工判断后决定是否注册，因此暂时搁置。 也查找了 11 街 OpenAPI，但只确认到卖家专用文档。楽天市場（JP）联动从一开始就没有代码。 详细内容/重新审查方法请参考 lib/liveData.ts 顶部注释。

• 金枪鱼罐头·豆腐数据中故意省略了饱和脂肪酸/反式脂肪酸字段。 食药处 API 原始值比 同一产品的总脂肪含量大 3~6 倍（例如：脂肪 15g 但饱和脂肪酸 50g），疑似字段映射错误或 原始数据错误。豆腐类别全部 4 个产品和金枪鱼罐头全部 4 个产品都出现相同问题，因此这并非 偶然，而更像是该 API 字段（AMT_NUM23/24）本身的结构性问题——相反，牛奶/ 矿泉水/罐头火腿中未出现此问题。在通过官方文档重新确认 AMT_NUM23/24 定义之前， 绝对不要使用这两个字段。（PlayMCP 测试中发现：2026-08-25）

• egg（鸡蛋）类别尚不存在。 data/staging/egg.draft.json 中，用"계란"搜索食药处 API 得到的 20 条结果全部是鸡蛋曲奇/鸡蛋点心/烤鸡蛋等加工食品，超市中出售的生鲜蛋（一板鸡蛋） 产品一个都没有，因此验收结果全部丢弃。若要重新收集，请将搜索词改为"달걀"，或使用 FOOD_CAT1_NM（食品大类）参数缩小到蛋加工品类后重试。

• 数据文件中带有 needsVerification: true 的项目是来源验证尚未完成的示例数据。 compare_products 响应中也会以 note 形式附带此信息，因此不得将此值当作事实用于回答。

• certifications 字段只收录了通过搜索实际确认的内容（例如：济州三多水饮用水研究所 ERA 认证）。 对于竞争产品，未经验证的"不合格/未通过"等负面事实绝不收录—— 此类信息有诽谤风险，若要收录，必须仅使用食品安全国家（食药处）官方召回·行政处分 信息等一手官方来源。

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 代码分别对应哪种营养素，由于无法用浏览器打开 文档（Excel），因此通过已实现相同 API 的开源（ISC 许可证）项目 k-mfds-fooddb-mcp-server 的 映射代码进行了交叉确认。实际 API 调用本身由于此容器网络屏蔽了 apis.data.go.kr （host_not_allowed），无法在此处执行，而是用完全模拟实际响应架构的 mock 验证了 请求组装→响应解析→映射→文件保存的整个流程。使用真实密钥的首次调用需要你亲自执行。

5. 部署（Render）- 已完成

已关联 GitHub 仓库（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 分支时 Render 会自动重新部署

• 免费套餐在无流量时进入休眠状态，首次请求可能会有冷启动（数十秒）—— 如果产生实际使用流量，可考虑转换为付费套餐（Starter，$7/月）

首次部署时健康检查持续超时的 bug（已修复，提交 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. 使用 Kakao 账号登录 https://playmcp.kakao.com

3. 在"MCP 服务器注册"中输入已部署服务器的端点 URL（https://.../mcp）

4. 最初以非公开（临时注册）状态仅可在本人账号下测试

5. 要向其他用户公开，需经过 Kakao 合作伙伴验证流程（此部分的详细要求需在 PlayMCP 网站内的"使用指南"中另行确认——该区域持续更新，请在注册前再次确认）

7. 后续步骤建议

• 类别扩展（添加豆腐/金枪鱼罐头，鸡蛋因数据质量问题搁置）

• 编写 Dockerfile/render.yaml

• 创建 GitHub 仓库 + 完成 Render 部署

• 调查价格实时查询 API（确认 Naver Shopping 终止，审查 Coupang Partners/11 街后搁置）

• 修复部署后健康检查超时 bug + 完成 /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