Skip to main content
Glama
식자재회수점검

식자재회수점검

by NFULL07

2026-11-12 기준 카카오클라우드(PlayMCP in KC)에 배포되어 동작 중이며, 식품안전나라 회수·판매중지 실데이터 389건을 1시간마다 갱신합니다. PlayMCP 1차 심사 반려 사유(도구 description의 서비스명 표기)는 수정해 재배포했습니다. 이 문서는 상태를 구분해 적습니다. 구현 = 실제로 동작, 계획 = 아직 만들지 않음, 가설 = 측정 전 기대효과.

  1. 🔍 Introduction

  2. 🧭 주요 기능

  3. 🔄 User Flow

  4. 💡 Tech Stack

  5. 💻 Architecture

  6. 🗂 데이터 모델

  7. 🔐 데이터 · 보안 원칙

  8. 📊 Data

  9. ✅ 검증

  10. 📂 Directory Structure

  11. ⚙️ 실행 · 배포

  12. 📌 진행 상황

  13. 📅 일정

  14. 👥 Team

🔍 Introduction

배경

식품 회수는 대부분 제품명 전체가 아니라 특정 제조일자·유통기한 범위의 로트에만 적용됩니다. 검수 담당자는 입고 때마다 "지금 가진 물건이 회수 대상인가"를 확인해야 하지만, 공개 API는 회수 목록만 줄 뿐 해당 여부는 판정하지 않습니다.

어려움

데이터에서 확인한 예 (2026-11-12, 389건)

회수는 로트 단위

297건(76%)이 제조일자 또는 유통기한 범위를 명시. 같은 제품명이라도 다른 로트는 대상이 아님

날짜 표기가 제각각

2026-06-26, 2028.5.26, 2025-11-04 ~ 2026-5-19, 제조일로부터 9개월, 데이터없음 이 같은 필드에 섞여 있음

바코드로 찾기 어려움

바코드가 기록된 레코드는 222건(57%). 일반 웹 검색으로는 바코드 역조회가 되지 않음

같은 이름, 다른 업체

제품명만 같고 업체가 다른 경우 이름만으로 판정하면 오탐

대상 : 학교·기관 급식소, 어린이집, 편의점, 식자재 유통사의 입고 검수 담당자 데이터 : 식품안전나라 회수·판매중지 정보(I0490) MCP Endpoint : https://foodrecallcheck.playmcp-endpoint.kakaocloud.io/mcp (식별자 foodRecall)

특징

  • 로트 단위 대조 :  제품명·업체·제조일자·유통기한·바코드를 회수 레코드와 맞춰 판정하고, 근거 필드를 함께 반환

  • 재고 30건 일괄 검수 :  납품 목록이나 식단표를 한 번에 대조

  • 바코드 역조회 :  바코드 숫자로 회수 건 찾기

  • 제조업체 이력 집계 :  업체별 누적 회수 건수와 등급 분포 (원천 API가 주지 않는 값)

  • 오탐 방지 :  퍼지 매칭 없음. 같은 제품명이라도 업체가 다르면 해당으로 단정하지 않음

식품안전나라 웹사이트에서도 회수 정보를 검색할 수 있습니다. 차별점은 검색이 아니라, AI 대화 안에서 여러 품목을 로트 단위로 한 번에 대조하고 근거를 보여주는 데 있습니다. 이것이 검수 현장에 충분한 가치인지는 실사용자 검증 전입니다(가설).

Related MCP server: FDA API MCP Service

🧭 주요 기능

도구 7개 모두 구현되어 있고, 모두 읽기 전용입니다.

도구

하는 일

상태

check_inventory_recall_batch

재고·식단·발주 목록(최대 30건) 일괄 대조

구현

check_product_recall_match

단일 제품 로트 대조 (제품명·제조일자·유통기한·바코드·업체)

구현

check_recall_by_barcode

바코드 역조회

구현

check_manufacturer_recall_history

제조업체별 회수 이력 집계

구현

list_recent_food_recalls

기간·분류별 최근 회수 목록

구현

get_recall_detail

회수 레코드 상세 (사유·등급·로트·회수방법·사진)

구현

get_recall_grade_rule

회수등급 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 필드

쓰임

제품명

PRDTNM

후보 찾기 (공백·기호 제거 후 완전일치)

업체명

BSSHNM

업체 대조, 업체별 이력

바코드

BRCDNO

바코드 역조회 (숫자만 비교)

제조일자

MNFDT

로트 범위 대조

유통기한

DISTBTMLMT

로트 범위 대조

회수사유 · 회수등급

RTRVLPRVNS, RTRVL_GRDCD_NM

근거 표시

레코드 ID

RTRVLDSUSE_SEQ

상세 조회

품목명 · 품목유형

PRDLST_CD_NM, PRDLST_TYPE

최근 목록 분류 필터

등록일

CRET_DTM

최근 목록 기간 필터

회수방법 · 포장단위 · 사진

RTRVLPLANDOC_RTRVLMTHD, FRMLCUNIT, IMG_FILE_PATH

상세 조회

원문 예

처리

2026-06-26

단일 날짜

2028.5.26

한 자리 월·일 허용

2025-11-04 ~ 2026-5-19

범위 (최소~최대)

20260610

구분자 없는 8자리

제조일로부터 9개월

날짜가 아니므로 로트 제한으로 보지 않음

데이터없음

빈 값

사진 필드에 URL이 여러 개 콤마로 붙어 오는 경우 첫 번째만 씁니다.

🔐 데이터 · 보안 원칙

항목

처리

사용자 입력

제품명·업체·날짜·바코드 등 제품 정보만 받음. 개인정보 항목 없음, 서버에 저장하지 않음

인증

사용하지 않음 (공개 데이터 조회)

API 인증키

카카오클라우드 환경변수로 주입. 저장소와 이미지에 넣지 않음 (.gitignore, .dockerignore)

도구 성격

7개 모두 readOnlyHint: true, destructiveHint: false

응답 크기

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건 있지만, 수입식품 회수를 모두 포함하는지는 확인하지 못했습니다.

✅ 검증

항목

결과

판정 로직 테스트 (npm run test:match)

11/11 통과

실스키마 · 날짜 파싱 테스트 (npm run test:schema)

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

https://github.com/NFULL07/food-recall-mcp

브랜치

main

Dockerfile 경로

Dockerfile

환경변수

FOODSAFETYKOREA_API_KEY

  • 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Access US consumer-product safety recalls from the CPSC, free and without authentication.
      84 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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