AI 튜토리얼

McOracle 맥도날드 신탁 튜토리얼: 무작위 신탁부터 실제 메뉴 추천과 안전한 주문까지

이 글에서는 McOracle의 작동 원리, Python 환경 설치, WorkBuddy Skill 구성, 중국 맥도날드 MCP 연동, 운명 카드 생성, 스크립트 사용법, 테스트 및 주문 보안 메커니즘을 소개합니다.

2026년 10월 13일약 14분 소요

McOracle 맥도날드 신탁 튜토리얼: 무작위 신탁부터 실제 메뉴 추천과 안전한 주문까지

McOracle란 무엇인가

McOracle(맥도날드 신탁)은 순수한 Skill 형태의 AI 신탁 체험입니다. 사용자는 어떤 질문이든 할 수 있으며, 시스템은 104개의 중국어 오리지널 신탁 중 Python secrets 모듈을 사용해 진정한 무작위 방식으로 답변 하나를 추출합니다. 그런 다음 맥도날드 중국 공식 MCP를 통해 실제 매장, 판매 가능한 메뉴와 가격을 조회하여 하나의 「맥도날드 계시록」과 운명 카드를 생성합니다.

프로젝트의 핵심 원칙은 다음과 같습니다. 신탁은 무작위일 수 있지만, 상품과 가격은 반드시 실제여야 합니다. 신탁은 저장소에 있는 고정 데이터에서 가져오며 모델이 즉석에서 만들어 내지 않습니다. 메뉴, 매장, 가격은 MCP가 반환한 데이터만 사용합니다. 가격을 확인하지 못한 경우에는 「가격 미확인」으로 표시합니다. 사용자가 명확히 확인하기 전에는 시스템이 주문을 생성하지 않으며, 주문 생성이 결제 성공을 의미하지도 않습니다.

전체 작업 흐름

McOracle의 표준 흐름은 다섯 단계로 구성됩니다.

사용자가 질문을 하거나 맥도날드 신탁을 직접 요청합니다.
scripts/draw-oracle.py가 references/oracle-library.json에서 신탁을 진정한 무작위 방식으로 추출하고 이번 결과를 고정합니다.
사용자가 메뉴 추천을 원하면 Skill이 MCP를 통해 주변 매장, 판매 가능한 메뉴와 메뉴 상세 정보를 조회합니다.
calculate-price로 가격을 확인한 뒤 scripts/generate-card.py를 사용해 1200×1600 PNG 운명 카드를 생성합니다.
사용자가 「주문 확인」이라고 명확히 답한 경우에만 시스템이 주문 정보를 재확인하고 create-order를 호출합니다. 이후에도 사용자가 공식 페이지를 통해 직접 결제해야 합니다.

사용자가 신탁만 뽑고 싶다면 첫 번째 단계에서 흐름이 종료됩니다. 위치를 강제로 요청하지 않으며 MCP도 호출하지 않습니다.

핵심 모듈과 프로젝트 구조

프로젝트는 주로 다음 모듈로 구성됩니다.

Oracle Engine: draw-oracle.py와 신탁 라이브러리가 무작위 추출, 결과 고정 및 재추출 제어를 담당합니다.
Recommendation Engine: recommendation-rules.md가 신탁 태그를 메뉴 방향으로 매핑하고 실제 메뉴 및 예산을 바탕으로 추천을 제공합니다.
MCP Adapter: SKILL.md와 MCP_INTEGRATION.md가 도구 호출 순서, 매개변수 규칙 및 예외 처리를 설명합니다.
Card Generator: generate-card.py가 Pillow로 버건디와 금색 템플릿을 프로그래밍 방식으로 그린 뒤 공식 상품 이미지를 합성합니다.
Order Safety Controller: validate-order.py가 상태 머신으로 확인 절차를 제어하여 확인되지 않은 주문을 방지합니다.
Skill Orchestrator: SKILL.md가 트리거 조건, 실행 흐름, 출력 형식 및 안전 요구 사항을 정의합니다.

신탁 라이브러리에는 104개의 오리지널 콘텐츠가 포함되어 있으며, 긍정형, 부정형, 대기형, 행동형, 반전형, 행운형, 유머형, 맥도날드 전용형의 8개 분류를 다룹니다. 각 신탁에는 번호, 본문, 분류, 태그, 해석, 행동 안내, 추천 태그 및 시각적 테마가 포함됩니다.

Python 의존성 설치

프로젝트에는 Python 3.9 이상이 필요합니다. 개발 환경은 Python 3.13을 사용합니다. 정식 운명 카드는 Pillow로 레이아웃을 구성하므로 Pillow를 설치해야 합니다. 신탁 추출 및 주문 안전 스크립트 자체는 이미지 생성 API에 의존하지 않습니다.

git clone <your-repo-url> McOracle
cd McOracle
pip install Pillow

macOS 또는 Linux에서 실행하는 경우 시스템에 중국어를 표시할 수 있는 글꼴이 있는지 확인하세요. 스크립트가 후보 목록에 따라 사용 가능한 글꼴을 선택합니다. 정식 카드를 생성하는 데 이미지 생성 API Key는 필요하지 않습니다.

WorkBuddy Skill로 설치

프로젝트를 가져오고 의존성을 설치합니다.
전체 McOracle/ 디렉터리를 사용자 수준 Skill 디렉터리인 ~/.workbuddy/skills/McOracle/ 또는 현재 작업 공간의 {workspace}/.workbuddy/skills/McOracle/에 복사합니다.
WorkBuddy의 커넥터에서 맥도날드 중국 MCP를 활성화합니다.
대화를 열고 「맥도날드 신탁」, 「제비 하나 뽑아 줘」, 「오늘의 신탁」 등의 표현으로 Skill을 실행합니다.

「퇴사해야 할까?」와 같이 일반적인 질문을 바로 할 수도 있습니다. 전체 흐름을 실행하려면 「오늘의 맥도날드 운명을 전부 보고 싶어」라고 말하면 됩니다. WorkBuddy 버전에 따라 Skill 등록 메타데이터 요구 사항이 다를 수 있으므로 현지 버전에 맞는 설정을 추가해야 합니다.

맥도날드 중국 공식 MCP 구성

실제 매장, 메뉴 및 가격을 기반으로 추천하려면 먼저 공식 MCP 사용 안내에서 Token 신청 방법을 확인한 뒤, WorkBuddy의 「커넥터」→「사용자 지정 커넥터」→「MCP 구성」에서 설정을 입력해야 합니다.

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

YOUR_MCP_TOKEN을 자신의 Token으로 바꾸고 Token을 저장소에 커밋하지 마세요. 프로젝트에서 사용하는 주요 도구는 now-time-info, query-nearby-stores, query-meals, query-meal-detail, calculate-price입니다. 주문 관련 도구인 create-order는 사용자가 명확히 확인한 후에만 호출할 수 있습니다.

처음 사용하기: 신탁 추출

프로젝트 루트 디렉터리에서 다음 명령을 실행하면 특정 질문에 대한 신탁 하나를 추출할 수 있습니다.

python scripts/draw-oracle.py --question '오늘 뭐 먹지?'

추출 결과는 scripts/_oracle_state.json에 기록되고 이번 세션 동안 고정됩니다. 따라서 이후의 해석, 추천 및 운명 카드는 모두 같은 신탁을 참조하며, 여러 번 읽는 과정에서 실수로 바뀌지 않습니다.

현재 고정된 결과를 확인하거나 다시 추출하려면 다음을 실행합니다.

python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw

--redraw는 사용자가 명확히 다시 추출해 달라고 요청한 경우에만 사용해야 합니다. 시스템은 해석이나 운명 카드를 생성할 때 임의로 신탁을 교체하지 않습니다.

운명 카드 생성

운명 카드는 고정된 버건디와 금색 시각 템플릿을 사용하며 이미지 생성 서비스에 의존하지 않습니다. 배경에는 짙은 버건디 그라데이션, 금색 이중 테두리, 중앙 발광 링과 별 장식이 포함됩니다. 텍스트는 Pillow로 프로그래밍 방식으로 배치하여 중국어, 번호 및 가격이 깨지거나 넘치지 않도록 합니다.

MCP가 공식 상품 이미지를 반환하고 가격이 calculate-price를 통해 확인된 경우 다음과 같이 정식 카드를 생성할 수 있습니다.

python scripts/generate-card.py \
  --oracle-id 'NO.021' \
  --answer '한밤중에는 결정을 내리지 마세요.' \
  --interpretation '새벽 한 시의 당신과 오전 열 시의 당신은 같은 사람이 아닙니다.' \
  --item-name '그릴드 치킨버거 세트' \
  --item-price 34.5 \
  --price-verified \
  --item-image-url 'https://menu-img.mcd.cn/.../MS_9900005462_320.png' \
  --out examples/oracle-card-NO021-official.png

정식 출력 크기는 1200×1600 PNG입니다. --price-verified는 가격이 실제로 MCP를 통해 확인된 경우에만 사용할 수 있으며, 예시 가격을 실시간 가격으로 사용해서는 안 됩니다.

이미지 소재의 대체 전략

상품 이미지는 다음 우선순위에 따라 처리됩니다.

먼저 query-meals 또는 query-meal-detail이 반환한 공식 상품 이미지를 사용합니다.
공식 이미지가 없으면 --item-image로 별도의 콘셉트 일러스트를 지정할 수 있으며, 콘셉트 일러스트임을 정확히 표시해야 합니다.
외부 소재를 사용할 수 없으면 스크립트가 내장된 햄버거, 감자튀김 및 콜라 프로그램 일러스트를 사용합니다.
모든 소재를 사용할 수 없으면 「메뉴 시각 소재 없음」 대체 카드를 출력하고, 종료 코드 2와 JSON ok=false로 실패를 보고합니다.

프로젝트는 빈 원형 링을 메뉴 이미지처럼 사용하지 않으며, 콘셉트 일러스트를 공식 실사 이미지로 표시하지도 않습니다.

대화에서 전체 체험 진행하기

일반적인 대화는 다음과 같이 진행할 수 있습니다.

사용자: 맥도날드 신탁, 오늘 퇴사해도 될까요?
McOracle: 신탁을 추출하고 본문, 해석, 행동 안내 및 주요 사항 알림을 반환합니다. 오늘의 추천 메뉴도 제공할 수 있습니다.

사용자: 주문할 준비가 됐어요
McOracle: 매장, 수령 방식, 상품과 가격으로 구성된 주문 요약을 표시하고 확인을 요청합니다.

사용자: 주문 확인
McOracle: 가격을 다시 확인한 뒤 create-order를 호출하고 실제 주문 번호와 공식 결제 페이지를 반환합니다.

「봐 줘」, 「추천해 줘」, 「주문할 준비가 됐어요」는 최종 확인에 해당하지 않습니다. 사용자가 명확히 「주문 확인」이라고 답한 후에만 주문 절차를 계속할 수 있습니다.

주문 안전 메커니즘

주문 안전 컨트롤러는 주문 상태와 핵심 매개변수를 검사합니다. 매장, 상품, 수량, 가격 또는 수령 방식이 변경되면 이전 확인은 무효가 되며, 시스템은 요약을 다시 표시하고 확인을 다시 요청해야 합니다.

프로젝트는 자동으로 결제하지 않으며 주문 번호나 주문 성공 메시지를 위조하지도 않습니다. 주문을 생성한 후에도 공식 결제 절차가 완료되지 않은 결제 대기 상태이므로 사용자가 공식 페이지에서 직접 결제를 완료해야 합니다. 매장 수령과 드라이브스루는 orderType=1을 사용하고, 배달은 배송 주소와 함께 orderType=2를 사용합니다. 두 종류의 매개변수는 혼용할 수 없습니다.

주문 안전 데모 독립 실행

주문 스크립트는 실제 주문을 생성하지 않는 순수 로직 Mock 데모를 제공합니다.

python scripts/validate-order.py demo

이 데모는 실제 MCP에 연결하기 전에 확인 규칙을 점검하는 데 적합합니다. 확인 없이는 주문할 수 없는지, 모호한 표현이 확인으로 인정되지 않는지, 주문 매개변수가 변경되면 확인이 무효가 되는지, 주문 생성이 결제 성공을 의미하지 않는지를 확인할 수 있습니다.

테스트 실행

프로젝트에는 신탁 로직, 운명 카드 생성 및 주문 안전 상태 머신을 각각 다루는 세 가지 테스트 모음이 포함되어 있습니다.

python tests/test-oracle.py
python tests/test-card.py
python tests/test-order-safety.py

README에 기록된 현재 결과는 24개 항목 모두 통과입니다. 신탁 테스트는 104개 데이터, 고유 번호, 8개 분류, 무작위성 및 상태 고정을 검증합니다. 운명 카드 테스트는 유효한 PNG, 크기, 소재 없음 대체 처리, 미확인 가격 분기 및 긴 텍스트 레이아웃을 검증합니다. 주문 테스트는 Mock을 사용해 안전한 상태 전환을 검증하며 실제 MCP를 호출하지 않고 주문도 생성하지 않습니다.

고급 사용 권장 사항

오락용 신탁과 현실의 결정을 구분하기

신탁은 오락과 영감을 위한 것일 뿐 미래를 예측하지 않으며 현실적인 판단을 대신할 수 없습니다. 퇴사, 투자, 건강, 법률 또는 재정과 관련된 문제는 객관적인 조건을 함께 고려하고 전문가와 상담해야 합니다.

확인된 가격과 예시 가격을 항상 구분하기

MCP가 반환하는 가격 단위는 「분」이므로 표시하기 전에 100으로 나누어야 하며, 가격에는 유효 기간이 있습니다. 실시간 확인을 완료하지 않았다면 「가격 미확인」으로 표시해야 하며, 카드나 대화에서 예시 가격을 실시간 가격 대신 표시해서는 안 됩니다.

자격 증명과 개인정보 관리

Token과 API Key는 커넥터 설정 또는 환경 변수로만 읽어야 하며 소스 코드에 작성하거나 저장소에 커밋해서는 안 됩니다. 프로젝트는 사용자의 개인정보, Cookie, 주문 번호 또는 개인 자격 증명을 저장해서는 안 됩니다. Issue나 Pull Request를 제출할 때도 이러한 민감한 정보를 포함하지 마세요.

현재 기능 범위 이해하기

매장 조회, 메뉴 조회, 메뉴 상세 정보, 가격 계산, 공식 이미지 다운로드 및 운명 카드 생성은 실제 검증 기록이 있습니다. 완전한 「주문-결제-상태 재조회」 순환 흐름, 맥도날드 배달 흐름, 쿠폰 수령 및 사용 처리에는 아직 충분히 실측되지 않은 부분이 있으므로 이를 엔드투엔드 검증이 완료된 기능으로 설명해서는 안 됩니다.

맺음말

McOracle은 고정된 신탁 데이터, 진정한 무작위 추첨, 공식 MCP 실시간 메뉴, 프로그래밍 방식의 이미지 레이아웃을 결합한 흥미로운 WorkBuddy Skill입니다. 신탁 스크립트만 먼저 사용할 수도 있고, MCP를 구성해 매장, 메뉴 및 가격 추천을 추가로 받을 수도 있습니다. 실제로 사용할 때는 다음 세 가지 원칙을 반드시 기억하세요. 신탁은 오락을 위한 것이며, 가격은 반드시 실시간으로 확인해야 하고, 사용자가 명확히 확인하기 전에는 절대로 주문을 생성해서는 안 됩니다.

운명은 무작위일 수 있지만, 가격은 반드시 실제여야 합니다.