AI 튜토리얼

M餐搭子 튜토리얼: 실시간 메뉴, 예산 및 영양 목표로 맥도날드 식사 조합 3가지 생성

이 튜토리얼에서는 M餐搭子를 설치하고 실행하는 방법, 맥도날드 MCP Token 설정 방법, 매장 메뉴·예산·열량 상한·단백질 목표에 따라 실행 가능한 식사 조합 3가지를 생성하는 방법을 소개합니다. 또한 데모 모드, Docker 배포, 테스트 점검 및 보안 실천 방법을 설명합니다.

2026년 10월 24일약 12분 소요

M餐搭子 튜토리얼: 실시간 메뉴, 예산 및 영양 목표로 맥도날드 식사 조합 3가지 생성

M餐搭子란

M餐搭子는 맥도날드 MCP 데이터를 기반으로 한 지능형 메뉴 조합 Skill입니다. 도시, 랜드마크, 예산, 최대 열량 및 단백질 목표를 입력하면 주변 포장 가능 매장을 조회하고, 현재 메뉴와 영양 데이터를 대조하여 실행 가능한 세 가지 메뉴 조합을 제공합니다.

단일 상품만 추천하는 도구와 달리 M餐搭子는 각 조합의 가격, 열량, 단백질, 예산 사용량, 남은 열량 및 추천 이유를 보여 줍니다. 또한 MCP 호출 체인을 펼쳐 각 Tool의 상태와 소요 시간을 확인할 수 있습니다.

이 프로젝트는 2026 맥도날드 프로그래머 창의 개발 대회에 참가했지만, 맥도날드 공식 제품은 아닙니다. 메뉴 제공 여부, 가격 및 프로모션은 맥도날드 공식 채널의 실제 정보를 기준으로 하며, 결과는 의료 또는 영양에 관한 전문적인 조언을 구성하지 않습니다.

프로젝트가 해결하는 문제

주문이 어려운 이유는 선택지가 부족해서가 아니라 메뉴, 영양 정보, 할인 및 개인 목표가 서로 다른 위치에 흩어져 있기 때문입니다. 사용자는 예산과 열량을 조절하면서 단백질도 늘리고 싶을 수 있으며, 마지막에는 조합이 완전한지도 판단해야 합니다.

M餐搭子는 사용자가 먼저 해당 식사의 기준을 정한 뒤 실제 메뉴에서 결과를 계산합니다. 사용자가 구체적인 상품을 미리 정하도록 하는 방식이 아닙니다. 메뉴 가격, 영양 데이터 및 할인 정보를 하나의 작업 공간에 통합하여 추천 과정을 더 쉽게 이해하고 검증할 수 있도록 합니다.

핵심 기능

실시간 매장 조회: query-nearby-stores를 통해 도시와 랜드마크를 기준으로 주변 포장 가능 매장을 찾습니다.
실시간 메뉴 조회: query-meals를 통해 현재 매장의 가격, 정가, 상품 이미지 및 태그를 가져옵니다.
영양 매칭: list-nutrition-foods를 사용하여 메뉴 상품을 열량 및 단백질 데이터와 대조합니다.
세 가지 메뉴 조합: 각각 “균형 우선”, “단백질 강화” 및 “간편 조합”을 반환하여 하나의 블랙박스 답변만 제시하지 않습니다.
설명 가능한 지표: 위안당 단백질, 예산 사용량, 남은 열량 및 할인 차액을 표시합니다.
할인 및 프로모션: available-coupons와 campaign-calendar를 호출하여 받을 수 있는 쿠폰과 예정된 프로모션을 한곳에 표시합니다.
호출 추적: 사용자가 MCP Tool의 호출 상태와 소요 시간을 확인할 수 있습니다.
안전한 대체 처리: Token이 설정되지 않았거나 Tool을 일시적으로 사용할 수 없을 때 명확히 표시된 비식별 데모 스냅샷을 사용합니다.

실행 전 준비

실시간 MCP 버전은 저장소의 Node 서비스를 로컬에서 실행해야 합니다. 시작하기 전에 다음 환경을 준비하세요.

Node.js 20 이상
npm 10 이상
맥도날드 MCP Token 1개. 데모 데이터만 체험하는 경우에는 제공하지 않아도 됩니다.

설치하지 않고 바로 사용하려면 GitHub Pages 온라인 데모에 접속할 수도 있습니다. 이 버전은 순수 프런트엔드 데모로, 조건 조정과 메뉴 조합 계산을 모두 지원하지만 실시간 MCP 데이터가 아닌 비식별 메뉴 스냅샷을 사용합니다.

설치 및 설정

1단계: 복제 및 의존성 설치

터미널에서 다음 명령을 실행하세요. 저장소 주소 자리 표시자를 실제 주소로 바꾸세요.

git clone <your-repository-url>
cd mcd-meal-mate
npm install
cp .env.example .env

2단계: 환경 변수 설정

프로젝트 루트 디렉터리의 .env 파일을 열고 MCP Token과 서비스 포트를 입력하세요.

MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787

MCD_MCP_TOKEN은 필수 변수가 아닙니다. 설정하면 실시간 MCP가 활성화되고, 설정하지 않으면 데모 데이터를 사용합니다.
PORT는 필수 변수가 아니며 기본값은 8787입니다.

MCP Token은 서버 환경 변수에만 저장해야 합니다. 프런트엔드 코드에 작성하거나 공개 저장소에 커밋하지 마세요.

3단계: 개발 환경 시작

npm run dev

시작한 후 브라우저에서 http://localhost:5173에 접속하세요. 개발 명령은 Express API를 실행하고 Vite 핫 리로드를 활성화하므로 인터페이스와 서버 로직을 디버깅하는 데 적합합니다.

Token을 설정하지 않는 데모 모드

맥도날드 MCP Token이 없다면 프로덕션 버전을 빌드하고 시작할 수 있습니다.

npm install
npm run build
npm start

그런 다음 http://localhost:8787에 접속하세요. 이때 페이지에는 “데모 데이터”가 명확히 표시되며, 메뉴, 가격 및 프로모션은 비식별 스냅샷에서 가져옵니다.

데모 모드는 상호작용 흐름, 입력 제약 및 세 가지 메뉴 조합 결과를 확인하는 데 적합하지만, 현재 매장의 실시간 제공 여부, 가격 또는 프로모션을 나타내지는 않습니다. 실제 사용 시에는 대상 매장에서 반환한 데이터를 기준으로 해야 합니다.

기본 사용법: 세 가지 메뉴 조합 생성

1단계: 선호도 선택

작업 공간에 들어간 후 먼저 “균형”과 같은 선호도를 선택할 수 있습니다. 선호도는 조합 점수에 반영되지만 결과는 여전히 예산, 열량 및 단백질 목표의 제약을 받습니다.

2단계: 식사 조건 입력

다음 예시 조건으로 시작할 수 있습니다.

도시: 상하이시
상권 / 랜드마크: 인민광장
예산: 35위안
최대 열량: 700 kcal
단백질 목표: 35 g

3단계: 계산 결과 확인

서버는 주변 매장을 찾고 메뉴와 영양 데이터를 조회한 뒤 세 가지 유형의 조합을 반환합니다.

조합 A: 균형 우선. 예산과 열량 제한 내에서 주식과 간식 또는 음료를 제공하며 단백질, 위안당 단백질 및 추천 이유를 표시합니다.
조합 B: 단백질 강화. 단백질을 우선적으로 높이면서 예산과 열량 제한을 최대한 지킵니다.
조합 C: 간편 조합. 가격은 더 낮지만 여전히 완전한 조합을 제공하여 비용과 선택 효율을 더 중시하는 상황에 적합합니다.

조합을 비교할 때 총 단백질만 보지 마세요. 위안당 단백질, 남은 예산, 남은 열량 및 할인 차액을 함께 고려하여 현재 요구에 가장 적합한 결과를 판단할 수 있습니다.

4단계: MCP 호출 체인 확인

“MCP 호출 체인”을 펼치면 매장, 메뉴, 영양, 할인 및 프로모션 관련 Tool의 상태와 소요 시간을 확인할 수 있습니다. 이를 통해 추천이 실시간 반환 데이터를 기반으로 하는지, 아니면 Token이 없거나 Tool을 사용할 수 없어 데모 스냅샷으로 전환되었는지 판단할 수 있습니다.

자주 사용하는 개발 명령

npm run dev: Express API와 Vite 핫 리로드를 시작합니다.
npm run build: 프런트엔드를 빌드하고 서버를 컴파일합니다.
npm start: 프로덕션 서비스를 시작합니다.
npm test: 조합 로직 및 영양 분석 테스트를 실행합니다.
npm run check: 타입 검사, 서버 컴파일 검사 및 테스트를 순서대로 실행합니다.

영양 분석, 메뉴 매핑 또는 메뉴 조합 규칙을 수정한 후에는 최소한 다음을 실행하는 것이 좋습니다.

npm test
npm run check

이를 통해 타입 오류, 컴파일 문제 및 조합 제약이나 영양 분석과 관련된 회귀를 조기에 발견할 수 있습니다.

Docker를 사용한 배포

프로젝트는 Docker 빌드 방식을 제공합니다. 먼저 이미지를 생성하세요.

docker build -t mcd-meal-mate .

그런 다음 호스트의 8787 포트를 컨테이너에 매핑하고 환경 변수로 Token을 전달하세요.

docker run --rm -p 8787:8787 \
  -e MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN" \
  mcd-meal-mate

컨테이너가 시작되면 http://localhost:8787에 접속할 수 있습니다. MCD_MCP_TOKEN을 생략하면 애플리케이션은 데모 데이터를 사용합니다.

프로젝트 구조 이해

프로젝트는 React 프런트엔드, Express 서비스, MCP 호출, 영양 분석 및 조합 계획을 서로 다른 모듈로 분리합니다.

src/
  App.tsx          React 작업 공간 및 반응형 상호작용
  styles.css       편집부 메뉴 × 영수증 시각 시스템
server/
  index.ts         Express API, 입력 검증 및 정적 리소스
  mcp.ts           MCP JSON-RPC 클라이언트, Tool 오케스트레이션 및 대체 처리
  nutrition.ts     영양 텍스트 분석, 메뉴 매핑 및 상품 역할 식별
  planner.ts       조합 제약, 선호도 점수 및 세 가지 조합 선택
  demo-data.ts     비식별 데모 스냅샷
  planner.test.ts  영양 및 조합 테스트
shared/
  types.ts         프런트엔드와 백엔드의 공유 타입

server/mcp.ts는 MCP JSON-RPC 통신, Tool 오케스트레이션 및 오류 발생 시 대체 처리를 담당합니다. server/nutrition.ts는 영양 텍스트와 메뉴 상품의 매핑을 처리하며, server/planner.ts는 조합 제약, 선호도 점수 및 세 가지 조합 선택을 실행합니다. 프런트엔드와 백엔드의 공통 데이터 구조는 shared/types.ts에 있습니다.

백엔드는 네이티브 fetch를 사용하여 맥도날드 MCP Streamable HTTP Server와 통신합니다. 프로덕션 빌드에서는 하나의 Express 프로세스가 API와 정적 페이지를 동시에 제공하며, 메뉴와 영양 결과를 메모리에 캐시합니다.

고급 사용 및 개발 권장 사항

먼저 제약 조건을 기준으로 결과 점검

예상한 조합을 얻지 못했다면 먼저 예산, 최대 열량 및 단백질 목표가 지나치게 엄격하지 않은지 확인하세요. 메뉴 조합 도구는 여러 경계를 동시에 만족해야 하므로 목표 간에 충돌이 발생할 수 있습니다. 예산을 적절히 늘리거나 최대 열량을 높이거나 단백질 목표를 낮추면 실행 가능한 조합을 더 많이 얻을 수 있습니다.

실시간 데이터와 데모 스냅샷 구분

디버깅할 때 페이지에 “데모 데이터”가 표시되는지 확인하고 MCP 호출 체인을 살펴보세요. Token이 없거나 Tool을 일시적으로 사용할 수 없거나 순수 프런트엔드 GitHub Pages 버전을 실행할 때는 결과가 비식별 스냅샷에서 제공될 수 있습니다.

서버 자격 증명 보호

Token을 브라우저 측에 주입하지 마세요. 프로젝트는 이미 Express 서비스에서 환경 변수를 읽고 서버에서 MCP를 호출하므로, 구조적으로 Token이 프런트엔드에 노출되는 것을 방지합니다. 서버나 컨테이너에 배포할 때도 안전한 환경 변수 관리 방식을 사용하여 자격 증명을 주입해야 합니다.

계획 로직 수정 후 전체 검사 실행

planner.ts, nutrition.ts 또는 공유 타입을 수정했다면 npm run check를 사용하여 타입, 컴파일 및 테스트를 검사하세요. 프로젝트에는 기존 조합 및 영양 분석 테스트가 있어 수정 사항이 기존 동작에 영향을 주는지 확인하는 데 도움이 됩니다.

통합 자료 확인

저장소의 MCP_INTEGRATION.md에는 전체 Tool, 호출 흐름, 비즈니스 가치 및 보안 경계가 기록되어 있습니다. mcp-config.example.json은 비식별 설정 예시를 제공하며, workbuddy.md에는 WorkBuddy 연동 컨텍스트와 재현 가능한 명령이 포함되어 있습니다. 다른 Agent 또는 Skill을 연동할 때는 먼저 이 파일들을 참고하세요.

보안 경계

저장소에는 실제 Token, 비밀번호 또는 계정 자격 증명이 포함되지 않습니다.
MCP Token은 서버 환경 변수에서만 읽습니다.
프로젝트는 주문, 결제, 추첨 또는 포인트 교환 Tool을 호출하지 않습니다.
서버는 사용자 입력을 저장하지 않으며 사용자 프로필을 생성하지 않습니다.
메뉴 제공 여부, 가격 및 프로모션은 맥도날드 공식 채널을 기준으로 합니다.
추천 결과는 의료, 영양 또는 기타 전문적인 조언을 구성하지 않습니다.

요약

M餐搭子는 매장 조회, 실시간 메뉴, 영양 매칭, 할인 정보와 조합 계획을 하나의 설명 가능한 식사 구성 흐름으로 통합합니다. MCP Token을 구성하면 현재 매장 데이터를 사용할 수 있으며, Token이 없어도 비식별화된 스냅샷을 통해 전체 상호작용을 체험할 수 있습니다.

설치가 완료되면 먼저 예시 조건으로 세 가지 구성을 검증한 다음, MCP 호출 체인을 통해 데이터 출처를 확인할 수 있습니다. 개발자는 mcp.ts, nutrition.ts 및 planner.ts부터 살펴보며 실시간 데이터 오케스트레이션, 영양 매핑 및 제약 조건 계산의 구현 방식을 이해할 수 있습니다.