식자재회수점검
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
2026-11-12 기준 카카오클라우드(PlayMCP in KC)에 배포되어 동작 중이며, 식품안전나라 회수·판매중지 실데이터 389건을 1시간마다 갱신합니다. PlayMCP 1차 심사 반려 사유(도구 description의 서비스명 표기)는 수정해 재배포했습니다. 이 문서는 상태를 구분해 적습니다. 구현 = 실제로 동작, 계획 = 아직 만들지 않음, 가설 = 측정 전 기대효과.
🔍 Introduction
배경
식품 회수는 대부분 제품명 전체가 아니라 특정 제조일자·유통기한 범위의 로트에만 적용됩니다. 검수 담당자는 입고 때마다 "지금 가진 물건이 회수 대상인가"를 확인해야 하지만, 공개 API는 회수 목록만 줄 뿐 해당 여부는 판정하지 않습니다.
어려움 | 데이터에서 확인한 예 (2026-11-12, 389건) |
회수는 로트 단위 | 297건(76%)이 제조일자 또는 유통기한 범위를 명시. 같은 제품명이라도 다른 로트는 대상이 아님 |
날짜 표기가 제각각 |
|
바코드로 찾기 어려움 | 바코드가 기록된 레코드는 222건(57%). 일반 웹 검색으로는 바코드 역조회가 되지 않음 |
같은 이름, 다른 업체 | 제품명만 같고 업체가 다른 경우 이름만으로 판정하면 오탐 |
대상 : 학교·기관 급식소, 어린이집, 편의점, 식자재 유통사의 입고 검수 담당자
데이터 : 식품안전나라 회수·판매중지 정보(I0490)
MCP Endpoint : https://foodrecallcheck.playmcp-endpoint.kakaocloud.io/mcp (식별자 foodRecall)
특징
로트 단위 대조 : 제품명·업체·제조일자·유통기한·바코드를 회수 레코드와 맞춰 판정하고, 근거 필드를 함께 반환
재고 30건 일괄 검수 : 납품 목록이나 식단표를 한 번에 대조
바코드 역조회 : 바코드 숫자로 회수 건 찾기
제조업체 이력 집계 : 업체별 누적 회수 건수와 등급 분포 (원천 API가 주지 않는 값)
오탐 방지 : 퍼지 매칭 없음. 같은 제품명이라도 업체가 다르면 해당으로 단정하지 않음
식품안전나라 웹사이트에서도 회수 정보를 검색할 수 있습니다. 차별점은 검색이 아니라, AI 대화 안에서 여러 품목을 로트 단위로 한 번에 대조하고 근거를 보여주는 데 있습니다. 이것이 검수 현장에 충분한 가치인지는 실사용자 검증 전입니다(가설).
Related MCP server: FDA API MCP Service
🧭 주요 기능
도구 7개 모두 구현되어 있고, 모두 읽기 전용입니다.
도구 | 하는 일 | 상태 |
| 재고·식단·발주 목록(최대 30건) 일괄 대조 | 구현 |
| 단일 제품 로트 대조 (제품명·제조일자·유통기한·바코드·업체) | 구현 |
| 바코드 역조회 | 구현 |
| 제조업체별 회수 이력 집계 | 구현 |
| 기간·분류별 최근 회수 목록 | 구현 |
| 회수 레코드 상세 (사유·등급·로트·회수방법·사진) | 구현 |
| 회수등급 1~3등급의 법적 의미와 조치 (정적 테이블, 외부 호출 없음) | 구현 |
판정 표시
판정은 AI가 아니라 정해진 대조 규칙이 합니다. 결과는 세 가지뿐입니다.
표시 | 뜻 | 하지 않는 해석 |
⚠️ 해당 | 제품명(또는 바코드)·업체가 회수 레코드와 일치하고 입력한 날짜가 회수 범위 안. 레코드에 로트 제한이 없으면 업체나 바코드 일치만으로 해당 | 실제 위해 여부, 회수 완료 여부 |
⚠️ 로트 확인 필요 | 제품명은 회수 목록에 있으나 업체·제조일자가 없어 로트를 특정할 수 없음, 또는 같은 제품명인데 업체가 다름 | 해당 또는 미해당으로 자동 변환 |
✅ 미해당 | 목록에 같은 제품명·바코드가 없거나, 입력한 날짜가 모든 회수 범위 밖 | 안전 보증. 제품명 표기가 목록과 다르면 미해당으로 나올 수 있음 |
모든 응답 끝에는 "최종 확인은 식품안전나라 또는 구입처·제조업체 안내를 따르십시오" 문구가 붙습니다.
🔄 User Flow
flowchart TB
subgraph S1["질문"]
direction LR
A["1. 검수 담당자 질문<br/>예: 명품갈비탕 기본맛<br/>제조일 2026-06-20 회수 대상이야?"] --> B["2. AI 채팅이 도구 선택<br/>PlayMCP 또는 외부 AI<br/>7개 도구 중 선택"]
end
subgraph S2["대조 (서버 메모리에서만 처리)"]
direction LR
C["3. 후보 찾기<br/>바코드 우선<br/>없으면 제품명 완전일치"] --> D["4. 업체 · 로트 대조<br/>제조일자 · 유통기한 범위<br/>업체가 다르면 단정하지 않음"] --> E["5. 판정 + 근거<br/>해당 / 로트 확인 필요 / 미해당<br/>등급 · 사유 · 레코드 ID"]
end
S1 --> S2
style E stroke-width:3px사용자 입력은 제품 정보뿐이며 서버에 저장하지 않습니다.
💡 Tech Stack
MCP Server | Runtime | Data | Infra | Collaboration |
- MCP Server : TypeScript, @modelcontextprotocol/sdk ^1.29 (공식 SDK), Zod (입력 스키마)
- Runtime : Node.js 20, Express 5, Streamable HTTP (Stateless)
- Data : 식품안전나라 Open API I0490 (회수·판매중지)
- Deployment : 카카오클라우드 PlayMCP in KC (Dockerfile 빌드), 인증키는 플랫폼 환경변수
- Tool : GitHub💻 Architecture
flowchart LR
API["식품안전나라 Open API<br/>I0490 회수 · 판매중지"]
subgraph KC["카카오클라우드 · PlayMCP in KC"]
direction TB
LOAD["적재 · 갱신<br/>기동 시 전량<br/>이후 1시간마다"]
SEED["data/seed.json<br/>최초 적재 실패 시 폴백"]
SNAP["메모리 스냅샷<br/>제품명 · 바코드 · 업체 인덱스"]
MCP["POST /mcp<br/>Streamable HTTP · Stateless<br/>도구 7개 (읽기 전용)"]
LOAD --> SNAP
SEED -.-> SNAP
MCP --> SNAP
end
API --> LOAD
USER["PlayMCP AI 채팅<br/>외부 AI 클라이언트"] --> MCP- 데이터 적재 : 식품안전나라 I0490 -> 기동 시 전량 -> 메모리 스냅샷 (제품명 · 바코드 · 업체 인덱스)
- 갱신 : 1시간마다 다시 받아 교체. 데이터가 없으면 30초마다 재시도
- 도구 호출 : PlayMCP -> POST /mcp -> 메모리 조회만. 도구 호출 경로에 외부 API 호출 없음
- 장애 대응 : 원천의 오류 코드(ERROR-xxx)는 실패로 처리, 이전 스냅샷 유지, 0건 결과로 덮어쓰지 않음
- 폴백 : 최초 적재가 실패하면 data/seed.json으로 기동, 실데이터가 들어오면 즉시 교체
- 상태 확인 : GET /health -> 서버가 살아 있으면 항상 200, 본문에 ready · records · loadedAt
- 배포 : GitHub -> PlayMCP in KC (Dockerfile 빌드)전량 메모리 적재 : PlayMCP 요구(응답 평균 100ms, p99 3,000ms)를 맞추려고 도구 호출 때 외부 API를 부르지 않습니다. 회수 목록은 수백 건 규모라 메모리에 충분히 들어갑니다.
DB를 두지 않음 : 원천이 공공 API이고 규모가 작아 별도 DB 없이 메모리 스냅샷으로 충분합니다. 재배포 직후 원천 장애에 대비해 seed 파일만 저장소에 둡니다.
Stateless : PlayMCP 권장 방식. 요청마다 서버 인스턴스를 새로 만들고 세션을 두지 않습니다.
원천 장애 대응 : 2026-07-09 식품안전나라 API가 200 응답 안에
ERROR-500을 담아 0건을 돌려준 적이 있습니다. 이를 정상 0건으로 받아 데이터가 비는 문제를 겪고, 오류 코드 감지·스냅샷 유지·seed 폴백·자가 회복을 넣었습니다.health는 항상 200 : health를 데이터 유무에 따라 503으로 돌려주자 배포가 Failed로 처리됐습니다. 그래서 서버 생존 여부로만 200을 주고, 데이터 상태는 본문(
ready,records)으로 알립니다.AI 역할 : 서버 안에 AI 모델은 없습니다. 판정은 정해진 규칙이 하고, 질문 이해와 도구 선택은 사용자 쪽 AI 채팅이 합니다.
🗂 데이터 모델
회수 레코드는 기동 시 아래 필드로 정규화해 메모리에 올립니다. DB 테이블은 없습니다.
의미 | I0490 필드 | 쓰임 |
제품명 |
| 후보 찾기 (공백·기호 제거 후 완전일치) |
업체명 |
| 업체 대조, 업체별 이력 |
바코드 |
| 바코드 역조회 (숫자만 비교) |
제조일자 |
| 로트 범위 대조 |
유통기한 |
| 로트 범위 대조 |
회수사유 · 회수등급 |
| 근거 표시 |
레코드 ID |
| 상세 조회 |
품목명 · 품목유형 |
| 최근 목록 분류 필터 |
등록일 |
| 최근 목록 기간 필터 |
회수방법 · 포장단위 · 사진 |
| 상세 조회 |
원문 예 | 처리 |
| 단일 날짜 |
| 한 자리 월·일 허용 |
| 범위 (최소~최대) |
| 구분자 없는 8자리 |
| 날짜가 아니므로 로트 제한으로 보지 않음 |
| 빈 값 |
사진 필드에 URL이 여러 개 콤마로 붙어 오는 경우 첫 번째만 씁니다.
🔐 데이터 · 보안 원칙
항목 | 처리 |
사용자 입력 | 제품명·업체·날짜·바코드 등 제품 정보만 받음. 개인정보 항목 없음, 서버에 저장하지 않음 |
인증 | 사용하지 않음 (공개 데이터 조회) |
API 인증키 | 카카오클라우드 환경변수로 주입. 저장소와 이미지에 넣지 않음 ( |
도구 성격 | 7개 모두 |
응답 크기 | 24k 제한 대비 20,000자에서 절단 |
판정 범위 | 회수 목록과의 일치 여부만 확인. 안전성 판단은 하지 않음 |
📊 Data
데이터 | 규모 | 출처 | 상태 |
식품안전나라 회수·판매중지 (I0490) | 389건 (등록일 2013-01-17 ~ 2026-11-12) | 식품안전나라 Open API, 2026-11-12 조회 | 구현 (1시간 주기 갱신) |
seed 폴백 | 5건 | 같은 API 공식 샘플, 2026-07-08 캡처 | 구현 |
공공데이터포털 15074318 · 15095378 | - | 공공데이터포털 | 계획 (엔드포인트 URL 확보 후) |
2026-11-12 조회 기준 필드 채움 정도: 바코드 222건(57%), 제조일자에 날짜 142건(37%), 유통기한에 날짜 207건(53%), 둘 중 하나라도 날짜 297건(76%), 로트 정보가 전혀 없는 레코드 92건(24%). 유통기한이 제조일로부터 N개월 같은 상대 표현인 레코드는 30건입니다.
그래서 바코드는 보조로 쓰고 제품명 + 업체 + 로트 대조를 기본으로 합니다. 로트 정보가 없는 회수는 업체나 바코드가 일치하면 제품 전체 회수로 판정합니다.
회수등급 | 1등급 | 2등급 | 3등급 | 자율회수 | 미상 |
건수 | 133 | 75 | 171 | 2 | 8 |
품목유형에는 가공식품 209건 외에 기구용기포장 25건, 주류 16건처럼 식자재가 아닌 품목도 포함됩니다. 수입신고 위반 등 수입 관련 회수 건도 20건 있지만, 수입식품 회수를 모두 포함하는지는 확인하지 못했습니다.
✅ 검증
항목 | 결과 |
판정 로직 테스트 ( | 11/11 통과 |
실스키마 · 날짜 파싱 테스트 ( | 14/14 통과 |
MCP 프로토콜 버전 | 2025-03-26 · 2025-06-18 · 2025-11-25 협상 확인 (라이브 서버) |
PlayMCP 개발가이드 툴 규칙 | 도구 7개 모두 annotations 5종 지정, description 1,024자 이내(최대 680자), 서비스명 국·영 병기, 이름에 "kakao" 없음 |
원천 장애 시 동작 | API 차단 상태에서 seed로 기동, health 200, 예시 질문 3개 정상 (로컬 재현) |
응답 시간 (간이) | 브라우저 왕복 23~32ms, 도구 3종 × 5회 (2026-11-12) |
응답 시간은 클라이언트 쪽 간이 측정입니다. 정식 부하 테스트와 p99 측정은 하지 않았습니다.
📂 Directory Structure
food-recall-mcp
├── src
│ ├── server.ts # Express + Streamable HTTP (POST /mcp, GET /health)
│ ├── tools.ts # 도구 7개 (description, inputSchema, annotations)
│ ├── env.ts # 로컬 .env 로더 (배포 환경은 플랫폼 환경변수)
│ └── mfds
│ ├── config.ts # 데이터 소스, 오류 코드 감지, 갱신 주기
│ ├── cache.ts # 전량 적재, 스냅샷 유지, seed 폴백, 재시도
│ ├── fields.ts # I0490 필드 매핑, 날짜 파싱, 정규화
│ ├── types.ts # 회수 레코드 변환
│ ├── match.ts # 로트 대조 판정
│ ├── format.ts # 마크다운 응답, 24k 가드
│ └── grades.ts # 회수등급 1~3 정적 테이블
├── data
│ └── seed.json # 원천 장애 대비 폴백 (실데이터 5건)
├── scripts
│ ├── test-match.ts # 판정 테스트 11건
│ ├── test-schema.ts # 실스키마 · 날짜 파싱 테스트 14건
│ ├── make-seed.mjs # seed 갱신
│ └── probe.mjs # 스키마 탐색
├── docs/images/icon.png
├── Dockerfile
└── .env.example⚙️ 실행 · 배포
로컬 실행
cp .env.example .env # FOODSAFETYKOREA_API_KEY 입력
npm install
npm run test:match # 판정 로직 테스트 (네트워크 불필요)
npm run test:schema # 실스키마 · 날짜 파싱 테스트
npm run build && npm start # http://localhost:8080
curl localhost:8080/health # {"ready":true,"records":...}seed 갱신 (식품안전나라 API가 정상일 때):
FOODSAFETYKOREA_API_KEY=발급키 npm run seed # macOS · Linux
$env:FOODSAFETYKOREA_API_KEY="발급키"; npm run seed # Windows PowerShell카카오클라우드 배포 (PlayMCP in KC)
항목 | 값 |
Git URL |
|
브랜치 |
|
Dockerfile 경로 |
|
환경변수 |
|
GitHub push만으로는 서버에 반영되지 않았습니다(2026-07 확인). 코드를 바꾸면 endpoint를 삭제하고 같은 이름으로 다시 등록합니다.
이전 endpoint가 남아 있는 상태에서 같은 이름으로 만들면 Failed가 났고, 모두 지운 뒤 다시 만들면 정상 배포됐습니다.
재등록할 때마다 환경변수를 다시 넣어야 합니다.
📌 진행 상황
2026-11-12 기준
식품안전나라 I0490 실스키마 확정 (필드 매핑)
로트 대조 판정과 오탐 방지 (판정 테스트 11건)
날짜 형식 처리: 한 자리 월·일, 범위, 상대 표현,
데이터없음(스키마 테스트 14건)도구 7개, annotations 5종, 서비스명 병기
카카오클라우드(PlayMCP in KC) 배포
원천 장애 대응: 오류 코드 감지, 스냅샷 유지, seed 폴백, 자가 회복
PlayMCP 등록, 1차 반려 사유(description 서비스명 표기) 수정 후 재배포
재심사 통과
MCP Inspector 표준 점검
회수등급 문구를 식품위생법 시행규칙 별표 18 원문과 대조 (
grades.ts)seed를 전량으로 갱신 (
npm run seed)공공데이터포털 15074318 · 15095378 소스 연결
실사용자(급식·유통 검수 담당) 테스트
제품명만 넣어도 "회수 목록에 있음" 경고를 먼저 보여주면 확인을 미루지 않는다.
로트 단위 대조와 근거 표시가 같은 제품명 다른 로트의 불필요한 폐기를 줄인다.
30건 일괄 검수가 품목별 검색보다 누락을 줄인다.
📅 일정
내용 | 날짜 |
카카오클라우드 첫 배포, 실데이터 355건 적재 | 2026-07-08 |
1차 심사 반려 (description 서비스명 표기) 수정 후 재배포 | 2026-07-09 |
원천 API 장애(ERROR-500) 대응: seed 폴백 · 자가 회복 | 2026-07-09 |
실데이터 389건, 1시간 주기 갱신 확인 | 2026-11-12 |
공모전 일정은 PlayMCP Agentic Player 10 공지를 따릅니다.
👥 Team
기획 · 설계 · 개발 · 배포 |
코드 작성, 데이터 분석, 문서 초안에 AI(Claude)를 활용했습니다. 도메인 선정, 판정 기준 결정, 배포와 최종 확인은 사람이 했습니다.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Check products against FDA food, drug and device recalls; drug labels, NDC, 510(k) via openFDA
Is it recalled or fake? Recall lookup vs live US gov feeds + transparent counterfeit risk signal.
U.S. federal product recalls and safety notices from FDA, FSIS, CPSC, and NHTSA, in one schema.
Is it recalled? US recalls from 9 agencies by UPC, model, NDC, VIN or lot. Its API also takes x402.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAccess US consumer-product safety recalls from the CPSC, free and without authentication.84 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables searching FDA food recalls and adverse event reports through natural language, supporting filters and pagination.-

deeprecall-mcpofficial
AlicenseNot gradedqualityDmaintenanceSearch 120,000+ recalled products from CPSC, FDA, EU Safety Gate, and other global agencies via MCP. Enables AI agents to check product safety by text or image.Apache 2.0- AlicenseNot gradedqualityCmaintenanceEnables determining whether a specific product unit is affected by FDA/CPSC recalls by evaluating the unit's lot, date, and other codes against frozen recall notices, returning affected, not affected, or needed-code questions.MIT