AI 튜토리얼

맥카드 컬렉터 튜토리얼: WorkBuddy로 맥도날드 카드를 뽑고 영양 정보를 확인한 뒤 안전하게 주문하기

이 튜토리얼에서는 맥카드 컬렉터를 설치하고 사용하는 방법을 알아봅니다. 맥도날드 중국 MCP를 통해 실시간 메뉴, 가격 및 영양 정보를 가져와 메뉴를 SSR, UR, R 카드로 변환하고, 컬렉션북, 포인트, 여러 장 뽑기, 오프라인 명령줄 테스트와 2차 확인 주문 과정을 체험할 수 있습니다.

2026년 10월 21일약 17분 소요

맥카드 컬렉터 튜토리얼: WorkBuddy로 맥도날드 카드 뽑기, 영양 확인 및 안전 주문

프로젝트 개요

맥카 컬렉터(mcd-gacha-collector)는 맥도날드 중국 MCP를 기반으로 개발된 WorkBuddy Skill입니다. 맥도날드 메뉴를 뽑기와 수집이 가능한 카드로 변환하고, 카드에 가격, 열량, 단백질, 나트륨 함량 및 건강도를 표시합니다.

프로젝트는 MCP를 통해 실시간 메뉴, 영양 데이터, 매장 및 가격을 가져온 뒤 로컬 Python 엔진으로 건강도 평가, 희귀도 분류, 예산 필터링 및 가중치 기반 뽑기를 수행합니다. 구매 가능한 메뉴가 뽑히면 가격 확인과 2차 확인을 거쳐 실제 주문을 생성할 수도 있습니다.

저장소의 영양 데이터는 약 160개 메뉴를 포함하며, 현재 웹 카드 풀에는 실제 메뉴 정보로 생성된 카드 53장이 포함되어 있습니다. 이 프로젝트는 대회 참가 작품이며, 맥도날드 공식 제품이 아닙니다.

맥카 컬렉터 데스크톱 첫 화면

핵심 기능

예산 뽑기: “50위안 이내로 한 장 뽑아줘”와 같은 자연어 요청을 입력하면 가격을 먼저 필터링한 뒤 가중치 기반으로 뽑습니다.
영양 및 건강도: MCP가 반환한 데이터를 바탕으로 0~100의 건강도를 계산하고 열량, 단백질, 지방 또는 나트륨 등의 정보를 표시합니다.
SSR, UR, R 등급: 희귀도는 건강도 분포에 따라 결정되며 수동으로 지정하지 않습니다. 상대 등급을 사용하므로 매장별 메뉴 구성에 대응할 수 있습니다.
로컬 컬렉션: 뽑기 기록은 ledger.json에 저장됩니다. 중복 카드는 획득 횟수가 누적되며 평균 열량과 평균 건강도를 집계할 수 있습니다.
포인트 시스템: Skill은 4시간마다 뽑기 기회 1회를 자동으로 회복합니다. 웹 버전은 60초 쿨다운이 적용된 수동 새로고침 방식을 사용합니다.
실제 주문: 먼저 MCP를 호출해 가격을 확인한 뒤 사용자에게 명시적인 확인을 요청하고, 마지막으로 create-order를 호출합니다.
오프라인 사용: 저장소에 샘플 데이터가 포함되어 있어 MCP Token을 설정하지 않아도 뽑기, 컬렉션 및 HTML 카드 렌더링을 테스트할 수 있습니다.
서드파티 의존성 없음: 핵심 스크립트는 Python 표준 라이브러리를 사용하며 Python 3.8 이상이 필요합니다.

뽑기 평가 및 주문 원리도

실행 흐름

프로젝트는 “데이터 조회는 MCP에, 계산은 코드에, 표현은 Agent에 맡긴다”는 설계 원칙을 따릅니다. WorkBuddy Agent는 사용자 의도를 이해하고, 맥도날드 MCP는 실제 업무 데이터를 제공하며, gacha.py는 결정론적 계산을 수행합니다.

사용자가 뽑기, 영양 조회 또는 주문 요청
→ WorkBuddy Agent가 맥도날드 MCP 호출
→ 시간, 매장, 메뉴, 가격 및 영양 데이터 조회
→ gacha.py가 건강도와 희귀도를 계산하고 뽑기 실행
→ render.py가 카드 또는 컬렉션 페이지 생성
→ 사용자가 구매 선택
→ calculate-price로 가격 확인
→ 사용자 2차 확인
→ create-order로 주문 생성

금액, 건강도 및 희귀도는 대규모 언어 모델이 암산으로 처리하지 않습니다. 가격은 MCP가 반환하고 평가와 뽑기는 Python 코드가 수행하므로 계산 편차와 오류 위험을 줄일 수 있습니다.

시작 전 준비

Python 3.8 이상을 설치합니다.
WorkBuddy를 설치하고 사용할 수 있도록 합니다.
접근 가능한 맥도날드 중국 MCP Token을 준비합니다. 오프라인 예제만 실행할 때는 Token이 필요하지 않습니다.
WorkBuddy가 사용자 Skill 디렉터리를 읽을 수 있는지 확인합니다.

방법 1: 온라인에서 바로 사용

인터페이스와 뽑기 데모만 확인하려면 맥카 컬렉터 온라인 페이지를 열면 됩니다. 페이지는 IP를 통해 도시를 확인한 뒤 매장 조회 기능을 호출하여 가까운 매장을 선택하므로 주소를 직접 입력할 필요가 없습니다.

맥카 컬렉터 모바일 첫 화면

배포 환경의 제약으로 인해 공개 웹페이지에는 개인 MCP Token을 주입할 수 없습니다. 온라인 버전은 위치 확인, 매장 및 카드 인터페이스를 체험하는 데 적합하며, 실제 주문은 로컬 백엔드 또는 커넥터가 구성된 WorkBuddy Skill에서 수행해야 합니다.

방법 2: WorkBuddy에 설치

1단계: 저장소 복제

git clone https://github.com/YOUR_GITHUB_USER/mcd-gacha-collector.git
cd mcd-gacha-collector

README의 저장소 주소에는 플레이스홀더가 사용되었습니다. 실제로 실행할 때는 YOUR_GITHUB_USER를 저장소 소유자 이름으로 바꾸거나 GitHub 페이지에서 제공하는 복제 주소를 직접 복사하세요.

2단계: 맥도날드 MCP Token 신청

맥도날드 MCP 오픈 플랫폼에 접속해 휴대전화 번호로 로그인한 다음 콘솔에서 서비스를 활성화하고 Token을 복사합니다. Token은 민감한 자격 증명이므로 공개 저장소에 기록하거나 Git 기록에 커밋하지 마세요.

3단계: MCP 커넥터 구성

WorkBuddy 왼쪽의 “전문가·Skill·커넥터”를 엽니다.
“커넥터”로 이동한 뒤 오른쪽 위의 “사용자 지정 커넥터”를 선택합니다.
“MCP 구성”을 선택합니다.
저장소의 mcp-config.example.json 내용을 복사합니다.
그 안의 ${MCD_MCP_TOKEN}을 실제 Token으로 바꾸거나 환경 변수를 통해 주입합니다.
구성을 저장하고 커넥터를 활성화합니다.

Token은 환경 변수로 관리하는 것을 권장합니다. 어떤 방식을 사용하든 실제 자격 증명이 포함된 구성 파일을 버전 관리 시스템에 커밋해서는 안 됩니다.

4단계: Skill 복사

macOS 또는 Linux에서 실행합니다.

cp -r skills/mcd-gacha-collector ~/.workbuddy/skills/

Windows WorkBuddy 사용자의 Skill 디렉터리는 다음과 같습니다.

%USERPROFILE%\.workbuddy\skills\

복사할 때는 SKILL.md, 핵심 스크립트, 참고 문서 및 리소스 파일이 포함된 전체 mcd-gacha-collector 디렉터리를 유지해야 합니다.

5단계: 설치 확인

WorkBuddy 대화 상자로 돌아가 다음을 입력합니다.

맥도날드 카드 한 장 뽑아줘

Skill이 메뉴 및 영양 도구를 호출하고 희귀도, 가격 및 열량이 포함된 카드 결과를 반환하면 설치와 MCP 연결이 정상적으로 적용된 것입니다.

기본 사용법

예산에 맞춰 카드 한 장 뽑기

50위안 이내로 한 장 뽑아줘

Skill은 현재 매장에서 이용 가능한 메뉴와 영양 데이터를 가져오고, 가격이 50위안을 넘지 않는 메뉴를 필터링한 뒤 가중치 기반 뽑기를 실행합니다. README의 실제 테스트 예시에서는 UR 선샤인 레몬 홍차 미디엄이 뽑혔으며 가격은 10위안, 열량은 117 kcal, 건강도는 63.4였습니다.

실제 결과는 매장 메뉴, 실시간 가격, 카드 풀 구성 및 무작위 추첨 결과에 따라 달라지므로 예시에 나온 메뉴나 가격을 고정된 출력으로 간주해서는 안 됩니다.

10연속 뽑기

10연속 뽑기

포인트가 충분하면 Skill이 카드 10장을 연속으로 뽑아 더 자세한 형식으로 결과를 표시합니다. 포인트가 부족하면 부족한 횟수와 다음 회복 시간을 안내합니다.

컬렉션 보기

내 컬렉션은?

컬렉션 데이터는 로컬 ledger.json에 집계됩니다. 결과에는 수집한 카드 수, SSR·UR·R 수량, 중복 횟수, 평균 열량 및 평균 건강도가 포함될 수 있습니다.

영양 정보 조회

빅맥 열량이 얼마야?

Skill은 list-nutrition-foods를 통해 메뉴를 검색합니다. README의 예시 결과는 빅맥 513 kcal, 단백질 27g, 지방 26g, 나트륨 961mg, 건강도 32.2이며 R 등급으로 분류되었습니다. 영양 정보는 해당 시점에 MCP가 반환하는 공식 데이터를 기준으로 해야 합니다.

주변 매장 조회

근처 맥도날드?

시스템은 기본적으로 먼저 IP 위치 확인을 수행해 도시를 얻은 뒤 query-nearby-stores를 호출하고, MCP가 반환한 거리 필드로 정렬합니다. 실제 테스트에서 매장 API의 위도와 경도가 0.0으로 반환될 수 있으므로 프로젝트는 해당 좌표를 사용해 자체적으로 거리를 계산하지 않습니다.

남은 포인트 확인

모바일 전체 페이지

뽑기 기회가 몇 번 남았어?

Skill은 로컬 장부의 포인트를 읽고 현재 사용 가능한 횟수와 다음 자동 회복 시간을 반환합니다. 여기서 포인트는 이 프로젝트의 로컬 게임화 장치일 뿐 맥도날드 공식 포인트 계정과는 관련이 없습니다.

안전하게 실제 주문 생성

마음에 드는 카드를 뽑았거나 직접 구매를 요청하더라도 프로젝트는 즉시 주문을 생성하지 않고 강제 2차 확인 절차를 사용합니다.

매장과 구매 가능한 메뉴 또는 세트를 선택합니다.
calculate-price를 호출해 실시간 가격과 이용 가능한 수령 방식을 가져옵니다.
유효 기간이 15분인 일회성 quoteToken을 생성합니다.
가격 확인 결과를 사용자에게 보여주고 명시적인 확인을 기다립니다.
백엔드가 Token을 검증한 후 create-order를 호출합니다.
주문 번호와 결제 링크를 반환합니다.

create-order에는 반드시 takeWayCode가 포함되어야 하며, 이 값은 calculate-price가 반환한 takeWayList에서 가져와야 합니다. 임의로 추측하거나 생략하면 요청이 400을 반환할 수 있습니다.

실제 테스트 메뉴에서는 단품을 독립적으로 주문할 수 없을 수 있습니다. README에 기록된 단품 96장의 canWithOrder 값은 모두 false이므로 실제 주문이 가능한 주요 카드는 18장의 세트 카드입니다. 단품 카드는 컬렉션 및 영양 정보 표시에 사용할 수 있습니다.

Token 없이 사용하는 명령줄 환경

저장소에는 sample_data가 포함되어 있어 전체 뽑기 로직을 먼저 오프라인으로 검증할 수 있습니다. 스크립트 디렉터리로 이동합니다.

cd skills/mcd-gacha-collector/scripts

카드 풀 분포 확인

python gacha.py sample_data --inspect --budget 50

이 명령은 50위안 예산 조건에서 샘플 카드 풀을 확인하며, 뽑기에 참여할 수 있는 카드와 희귀도 분포를 확인하는 데 적합합니다.

단일 뽑기 및 10연속 뽑기

python gacha.py sample_data --draw 1 --budget 50 --ledger /tmp/ledger.json
python gacha.py sample_data --draw 10 --budget 50 --ledger /tmp/ledger.json

--ledger는 장부 경로를 지정합니다. 같은 파일을 계속 사용하면 포인트와 컬렉션 기록을 유지할 수 있습니다.

컬렉션 통계 보기

python gacha.py sample_data --collection --ledger /tmp/ledger.json

확률 분포 시뮬레이션

python gacha.py sample_data --simulate 100 --seed 42

샘플 목표 분포는 SSR 5%, UR 20%, R 75%입니다. --seed 42를 사용하면 무작위 결과를 재현할 수 있어 디버깅과 알고리즘 수정 전후의 출력 비교에 적합합니다.

카드 HTML 렌더링

python render.py /tmp/ledger.json --out /tmp/cards.html --last-draw 1

렌더러는 장부 데이터를 단일 HTML 파일로 출력하여 브라우저에서 마지막 추첨 카드를 확인할 수 있도록 합니다.

자체 테스트 실행

python selftest.py

핵심 로직에는 105개의 자체 테스트가 포함되어 있습니다. 점수, 포인트, 희귀도 또는 카드 추첨 코드를 수정한 후에는 이 명령을 다시 실행해야 합니다.

건강도와 희귀도 이해하기

개별 메뉴의 건강도는 다음 세 가지 지표에 가중치를 적용해 계산합니다.

단백질 밀도 35%.
저열량 지표 40%.
저나트륨 지표 25%.

희귀도는 상대 등급 방식을 사용하며, 현재 데이터 분포에 따라 백분위 임계값을 설정합니다. 이를 통해 특정 매장에 커피와 같은 고득점 메뉴가 부족하더라도 SSR이 전혀 나오지 않는 상황을 피할 수 있습니다. README의 한 실제 카드 풀에서는 백분위수를 적용한 결과 SSR 3장, UR 7장, R 13장을 얻었습니다.

세트 메뉴에는 개별 메뉴의 가중치를 그대로 적용하지 않습니다. 세트 메뉴는 총열량이 본질적으로 더 높기 때문입니다. 프로젝트는 세트 메뉴에 독립 알고리즘을 적용합니다. 단백질 밀도 40%, 나트륨 밀도 35%, 열량 부하 25%로 계산하며 백분위 임계값도 별도로 산출합니다.

건강도와 희귀도는 재미를 위한 비교 용도로만 사용되며, 의료·영양 또는 기타 전문적인 조언을 대신하지 않습니다.

고급 개발 및 문제 해결 팁

MCP 영양 데이터 올바르게 파싱하기

list-nutrition-foods가 반환하는 data는 JSON 배열이 아니라 CSV 문자열일 수 있습니다. 프로젝트는 전용 parse_nutrition_csv 파싱 로직을 제공합니다. 클라이언트를 확장할 때 데이터가 항상 목록이라고 가정해서는 안 됩니다.

structuredContent 봉투 풀기

MCP 비즈니스 데이터는 structuredContent.data에 포함될 수 있으며, 그 안의 값도 딕셔너리, 목록 또는 문자열일 수 있습니다. 응답을 처리할 때는 먼저 외부 봉투를 푼 다음 실제 유형에 따라 파서를 선택해야 합니다.

프런트엔드와 백엔드 알고리즘 일치시키기

웹 버전은 빌드 시 계산 방식을 사용합니다. tools/gen_web_data.py가 데이터를 생성하고, web/build.py가 데이터를 단일 파일 페이지에 인라인합니다. 프런트엔드에서 점수 계산 알고리즘을 다시 구현하지 않으므로 양쪽 결과가 불일치할 가능성을 줄일 수 있습니다.

데이터 생성, 필드 매핑 또는 웹 템플릿을 수정한 후에는 tools/parity_check.py를 실행할 수 있습니다. 저장소에는 HTML, JavaScript, 카드 풀 분포 및 필드 정렬을 포함한 99개의 일관성 검사가 기록되어 있습니다.

백엔드 매장 파싱 검증하기

백엔드는 server 디렉터리에 있으며 Python 표준 라이브러리로 IP 위치 확인, MCP 클라이언트 및 주문 인터페이스를 구현합니다. 매장 파싱 로직에는 별도로 15개의 어설션이 있습니다. 105개의 Skill 자체 테스트와 99개의 웹 검사를 합치면 프로젝트에는 총 219개의 어설션이 기록되어 있습니다.

매장 위도·경도에 의존하지 않기

README의 실제 테스트 결과에 따르면 query-nearby-stores가 반환하는 위도·경도 필드는 모두 0.0일 수 있습니다. 더 안정적인 방법은 먼저 IP로 도시를 확인한 다음 도시와 장소 키워드로 검색하고, 인터페이스가 반환하는 distance를 사용해 정렬하는 것입니다.

전시용 카드와 주문 가능한 카드 구분하기

메뉴에 표시되는 음식이 모두 개별 구매 가능한 것은 아닙니다. 구매 기능을 구축할 때는 MCP가 반환하는 주문 가능 상태를 확인하고, 사용자가 유효한 세트 메뉴를 우선 선택하도록 안내해야 합니다. 카드로 표시할 수 있다는 이유만으로 주문을 생성할 수 있다고 가정해서는 안 됩니다.

토큰과 주문 작업 보호하기

토큰은 우선 환경 변수를 통해 주입합니다.
실제 토큰을 mcp-config.example.json에 작성하지 않습니다.
주문 전에 항상 가격을 다시 확인합니다.
일회성 quoteToken과 그 유효 기간을 확인합니다.
사용자가 명확히 확인한 후에만 create-order를 호출합니다.
테스트 주문은 신중하게 처리하고, 적시에 취소해야 하는지 확인합니다.

어떤 사용자에게 적합한가

맥도날드 MCP 호출 과정을 배우고 싶은 개발자.
WorkBuddy Agent Skill을 개발하려는 실무자.
카드 수집, 카드 뽑기 및 도감 콘텐츠를 좋아하는 사용자.
가벼운 방식으로 메뉴의 열량과 영양 구성을 비교하려는 직장인 또는 학생.
MCP 데이터 파싱, 가격 확인 및 안전한 주문 절차를 연구해야 하는 엔지니어.

요약

맥카 컬렉터는 메뉴 조회, 영양 비교, 카드 뽑기와 수집, 실제 주문을 하나의 완전한 흐름으로 연결합니다. 처음 사용할 때는 먼저 온라인 페이지에서 인터페이스를 확인한 다음 샘플 데이터로 명령줄 테스트를 실행할 수 있습니다. 로직에 문제가 없는 것을 확인한 후 맥도날드 MCP Token을 설정하고 Skill을 WorkBuddy에 설치하면 됩니다.

실제로 사용할 때는 데이터 형식의 차이, 매장 인터페이스의 제한, 세트 메뉴의 주문 가능 상태 및 2차 확인 절차에 특히 주의해야 합니다. 모든 가격, 판매 상태 및 메뉴 정보는 맥도날드 공식 채널의 실시간 결과를 기준으로 해야 합니다.