Oh-My-McDonald란
Oh-My-McDonald는 맥도날드 공식 MCP를 기반으로 하는 대화형 AI Skill입니다. 자연어로 예산, 취향, 제외 조건을 AI에 알려 실제 메뉴를 조회할 수 있습니다. 또한 매장별 가격 비교, 쿠폰 및 행사 확인, 영양 데이터 계산을 수행하고, 확인 후 먹은 메뉴와 방문한 매장을 기록할 수 있습니다.
이 프로젝트는 맥도날드 공식 MCP에서 업무 데이터를 가져온 다음 로컬 Python 스크립트로 데이터 처리, 기록 저장, 이미지 렌더링을 수행합니다. 웹 인터페이스가 필요하지 않으며 OpenAI API나 기타 이미지 생성 API에도 의존하지 않습니다.
프로젝트로 해결할 수 있는 문제
- 한 번의 대화에서 메뉴, 매장, 가격, 할인, 영양 정보를 조회할 수 있습니다.
- 예산, 취향, 제외 조건에 따라 MCP가 반환한 실제 후보 메뉴 중에서 선택할 수 있습니다.
- 선택한 최대 3개 매장에서 동일 상품, 동일 규격의 가격을 비교할 수 있습니다.
- 내 쿠폰함, 할인 만료 시간, 이미 게시된 행사를 확인할 수 있습니다.
- 정확히 일치하는 메뉴의 에너지, 단백질, 지방, 탄수화물, 나트륨, 칼슘을 계산할 수 있습니다.
- 사용자가 실제로 먹었거나 매장을 방문했다고 확인한 후 메뉴 도감과 매장 방문 기록을 저장할 수 있습니다.
- 조회 결과를 보기와 공유에 편리한 복셀 스타일 PNG 이미지로 변환할 수 있습니다.
네 가지 복셀 시각화 장면
프로젝트에는 Python 복셀 렌더러가 내장되어 있으며, 현재 43개의 굵은 복셀 모델을 포함하고 셀당 8픽셀 규칙으로 이미지를 생성합니다.
메뉴 도감
메뉴 도감은 구역별 전시관, 굽은 산책로, 메뉴 전시대를 사용해 탐색 진행 상황을 보여 줍니다. 실제로 먹고 저장을 확인한 메뉴만 불이 켜지며, 확인되지 않은 메뉴는 회색으로 유지됩니다.
할인 캘린더
할인 캘린더는 내 쿠폰함의 유효 날짜를 기준으로 집계하며, 오늘 사용 가능한 쿠폰, 곧 만료되는 쿠폰, 게시된 행사를 중점적으로 표시합니다. 전체 상세 내용은 다음 페이지에 배치해 한 이미지에 정보가 지나치게 몰리지 않도록 할 수 있습니다.
매장 가격 비교
매장 가격 비교 장면은 선택한 매장을 복셀 거리 안에 배치하고 입구에 해당 가격을 표시합니다. 이 거리 자체는 데이터 시각화만을 위한 것으로 실제 도로나 매장 간 지리적 관계를 나타내지 않습니다.
영양 식탁
영양 장면은 이번 식사의 음식을 하나의 식판에 배치하고 영양 데이터를 영수증으로 보여 줍니다. 채소, 과일, 유제품은 식사 외 추가 구성 참고 항목이며 식판 안 음식의 영양 합계에는 포함되지 않습니다.
설치 전 준비
시작하기 전에 다음 조건을 충족하는지 확인하세요.
- Python 3.11 이상.
- Python 가상 환경을 정상적으로 생성하고 사용할 수 있어야 합니다.
- 중국어를 지원하는 글꼴을 설치해야 하며 Noto Sans CJK를 권장합니다.
- 실시간 조회가 필요한 경우 맥도날드 공식 MCP 접속 인증 정보를 준비해야 합니다.
프로젝트의 주요 의존성은 Pillow >=10,<13 및 NumPy >=1.24,<3이며, 전체 의존성은 requirements.txt에 기록되어 있습니다.
첫 번째 단계: 프로젝트 복제
git clone https://github.com/xiaozhangup/Oh-My-McDonald.git
cd Oh-My-McDonald두 번째 단계: 가상 환경 생성
Linux 또는 macOS에서 실행합니다.
python -m venv .venv
source .venv/bin/activateWindows PowerShell 사용자는 다음을 실행합니다.
.venv\Scripts\Activate.ps1세 번째 단계: 의존성 설치
python -m pip install -r requirements.txt시스템 Python의 다른 패키지와 충돌하지 않도록 항상 활성화된 가상 환경에서 의존성을 설치하는 것이 좋습니다.
네 번째 단계: 중국어 글꼴 설정
복셀 이미지에는 중국어 메뉴명, 매장명, 할인 제목이 포함되므로 사용할 수 있는 중국어 글꼴이 필요합니다. Noto Sans CJK를 설치한 후 OMM_FONT으로 글꼴 파일 경로를 지정할 수 있습니다.
export OMM_FONT="/path/to/your/font.ttf"예시 경로를 컴퓨터에 실제로 존재하는 글꼴 파일로 바꾸세요. 이미지에서 중국어가 정상적으로 표시되지 않으면 먼저 이 환경 변수와 글꼴 경로를 확인해야 합니다.
다섯 번째 단계: 명령어 도움말 확인
python oh-my-mcdonald/scripts/oh_my_mcdonald.py --help이 명령은 로컬 보조 스크립트가 제공하는 하위 명령과 매개변수를 표시합니다. 더 자세한 설명은 저장소의 oh-my-mcdonald/references/commands.md에 있습니다.
맥도날드 공식 MCP 연결
MCP Token 받기
맥도날드 MCP 콘솔에 접속해 공식 페이지의 안내에 따라 MCP Token을 받으세요. 인증 정보는 로컬 환경 변수나 Codex 설정에 저장해야 하며, 실제 Token을 프로젝트 파일에 작성하거나 Git 저장소에 커밋하지 마세요.
환경 변수로 Token 설정
export MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN"Codex 설정에서 인증 정보 읽기
로컬 설정 파일에 이미 mcd-mcp 설정이 포함되어 있다면 --codex-config으로 파일을 명시할 수 있습니다.
python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
--codex-config /本机/config.toml stores --city 武汉 --keyword 东澜岸두 방법 모두 로컬 컴퓨터에서만 인증 정보를 읽습니다. 전체 연결 과정은 저장소 루트의 MCP_INTEGRATION.md를 참고하세요.
프로젝트에서 사용하는 MCP 도구
query-nearby-stores: 주변 매장을 조회합니다.query-meals: 메뉴를 조회합니다.query-meal-detail: 메뉴 상세 정보를 조회합니다.query-store-coupons: 매장 할인 정보를 조회합니다.query-my-coupons: 사용자 쿠폰함을 조회합니다.calculate-price: 지정 상품의 가격을 계산합니다.campaign-calendar: 행사 캘린더를 조회합니다.list-nutrition-foods: 영양 계산에 필요한 메뉴 데이터를 가져옵니다.order-list: 주문 기록을 조회합니다.
기본 사용법 1: 매장 조회
다음 명령은 우한시의 이름이나 위치에 “东澜岸”이 포함된 매장을 조회합니다.
python oh-my-mcdonald/scripts/oh_my_mcdonald.py stores \
--city 武汉 \
--keyword 东澜岸매장 결과를 받은 후 유효한 매장 ID를 사용해 메뉴 상세 정보와 가격을 계속 조회할 수 있습니다.
기본 사용법 2: 메뉴 상세 정보 조회
python oh-my-mcdonald/scripts/oh_my_mcdonald.py detail \
--store 1960151 \
--code 9900005456--store는 매장 ID를 지정합니다.--code는 메뉴 코드를 지정합니다.
예시의 ID는 매개변수 형식을 설명하기 위한 것입니다. 실제 사용 시에는 MCP의 현재 조회 결과에서 반환된 유효한 매장 ID와 메뉴 코드를 사용해야 합니다.
기본 사용법 3: 장바구니 가격 조회
장바구니 내용은 JSON 파일로 제공되며, 프로젝트는 지정한 매장과 현재 테스트 방안에 따라 가격을 계산합니다.
python oh-my-mcdonald/scripts/oh_my_mcdonald.py quote \
--store 1960151 \
--basket examples/basket.json매장별 가격을 비교할 때는 동일 상품과 동일 규격을 비교해야 합니다. 프로젝트는 선택한 최대 3개 매장만 비교하며 일부 매장 결과를 바탕으로 다른 매장의 가격을 추정하지 않습니다.
기본 사용법 4: 오프라인에서 복셀 모델 확인
MCP Token이 아직 없어도 로컬 렌더링 환경을 먼저 검증하고 내장 모델을 확인할 수 있습니다.
python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
--out output models생성 결과는 output 디렉터리에 기록됩니다. 이 단계는 Pillow, NumPy, 중국어 글꼴이 올바르게 설정되었는지 확인하는 데 적합합니다.
AI 클라이언트에서 Skill 사용
프로젝트는 oh-my-mcdonald/SKILL.md를 제공하며, 이를 통해 Skill을 지원하는 AI 클라이언트에 프로젝트의 기능, 작업 흐름, 제한 사항을 설명합니다. 클라이언트에는 MCP 연결 기능과 로컬 명령 실행 기능도 필요합니다.
일반적인 흐름은 다음과 같습니다.
- 사용자가 자연어로 예산, 취향, 매장, 할인 또는 영양 요구 사항을 제시합니다.
- AI가 적절한 MCP 도구를 선택해 실제 업무 데이터를 가져옵니다.
- AI가 예산과 제외 조건에 따라 반환된 결과를 필터링합니다.
- 필요에 따라 로컬 Python 스크립트를 호출해 데이터를 처리합니다.
- 시각화가 필요하면 로컬 렌더러가 PNG를 생성합니다.
- 식사 또는 매장 방문 기록과 관련된 경우 먼저 사용자의 명확한 확인을 기다린 후 기록에 저장합니다.
AI에게 다음과 같은 요청을 할 수 있습니다.
- 오늘 예산은 35위안이고 매운 음식은 싫어요. 무엇을 추천하나요?
- 조건에 맞는 실제 메뉴 중 하나를 무작위로 골라 주세요.
- 이 세트 메뉴의 주변 3개 매장 가격을 비교해 주세요.
- 오늘 사용할 수 있는 쿠폰과 최근 행사를 확인해 주세요.
- 이번 식사의 에너지와 단백질을 계산해 주세요.
- 방금 이 햄버거를 먹었다고 확인합니다. 기록해 주세요.
- 내가 먹은 메뉴로 도감 이미지를 만들어 주세요.
후보 메뉴는 반드시 MCP 조회 결과에서 가져와야 하며 AI가 만들어 내서는 안 됩니다. 한 번의 무작위 선택에는 최대 6개의 후보 메뉴 조합만 사용할 수 있습니다.
고급 팁과 사용 원칙
먼저 매장, 상품, 규격을 명확히 정하기
가격은 매장, 상품 규격, 할인 방안의 영향을 받습니다. 비교하기 전에 상품과 규격을 고정하고 AI가 이번에 선택한 매장을 명확히 나열하도록 해야 합니다. 그래야 결과를 비교할 수 있습니다.
영양 데이터 누락을 엄격하게 처리하기
영양 계산에는 정확히 일치하는 메뉴만 사용합니다. 일부 영양 필드가 누락된 경우 누락된 항목을 별도로 표시해야 하며, 누락 값을 0으로 간주하거나 이름은 비슷하지만 확인할 수 없는 상품으로 대체해서는 안 됩니다.
식사 내 통계와 식사 외 제안 구분하기
영양 식탁에는 채소, 과일, 유제품 등의 추가 제안을 표시할 수 있지만, 이번 식사의 영양 값은 식판에 있는 음식만 집계합니다. 생성된 이미지를 해석할 때 식사 외 참고 항목을 합계에 포함해서는 안 됩니다.
기록 전에 사용자 확인 받기
주문 기록은 확인이 필요한 정보일 뿐 사용자가 특정 메뉴를 이미 먹었다는 증거가 될 수 없습니다. 사용자가 실제로 먹었다고 명확히 확인한 후에만 프로젝트가 기록을 저장하고 도감을 밝힐 수 있습니다. 매장 방문 기록도 같은 원칙을 따릅니다.
할인 캘린더 올바르게 이해하기
캘린더는 내 쿠폰함의 유효 날짜를 기준으로 쿠폰 수를 집계합니다. 쿠폰을 특정 시간대, 매장, 상품에서 사용할 수 있는지는 MCP가 반환한 구체적인 조건을 따라야 합니다.
로컬 인증 정보 보호하기
우선 MCD_MCP_TOKEN 환경 변수나 로컬 Codex 설정을 통해 Token을 읽으세요. 인증 정보를 스크립트, 예시 JSON, 스크린샷, 버전 관리 파일에 작성하지 마세요.
자동화 테스트 실행
프로젝트는 Python unittest를 사용하며, 저장소 루트 디렉터리에서 다음 명령을 실행할 수 있습니다.
python -m unittest discover -s tests -vREADME에 기록된 기존 테스트는 총 51개이며, 합성 데이터를 사용해 비즈니스 처리, 출력 및 렌더링 로직을 검증합니다. 실제 MCP 쿼리의 검증 현황과 제한 사항은 docs/VALIDATION.md에 기록되어 있습니다.
알아 두어야 할 구현 범위
- 프로젝트는 자동 주문, 결제 또는 쿠폰 수령을 지원하지 않습니다.
- 프로젝트는 클라우드 동기화와 백그라운드 폴링을 제공하지 않습니다.
- 가격 비교는 최대 3개의 선택한 매장까지 지원하며, 동일한 상품, 동일한 규격 및 현재 테스트 방식에만 적용됩니다.
- 복셀 거리는 예시 장면이며, 실제 도로나 지리적 위치 관계를 포함하지 않습니다.
- 미리보기의 실제 MCP 데이터는 특정 날짜의 스냅샷이며, 이후의 실시간 결과를 나타내지 않습니다.
- 식사 기록과 매장 방문 기록은 모두 사용자의 확인을 거쳐야 합니다.
프로젝트 디렉터리 한눈에 보기
oh-my-mcdonald/SKILL.md: AI 클라이언트용 Skill 설명 파일입니다.oh-my-mcdonald/scripts/oh_my_mcdonald.py: 로컬 보조 스크립트이자 주요 명령 진입점입니다.oh-my-mcdonald/references/commands.md: 자세한 명령어 참고 문서입니다.docs/images/: 장면 미리보기 이미지입니다.docs/VALIDATION.md: 실제 쿼리 검증 결과와 제한 사항입니다.examples/basket.json: 장바구니 JSON 예시입니다.MCP_INTEGRATION.md: MCP 연동 및 호출 절차 설명입니다.tests/: 자동화 테스트입니다.
맺음말
Oh-My-McDonald는 맥도날드 공식 MCP, 자연어 상호작용 및 로컬 복셀 렌더링을 결합하여 메뉴 선택, 가격 비교 및 영양 분석을 지원하고, 확인을 거친 개인 탐방 기록도 작성할 수 있도록 합니다. 먼저 오프라인 모델 렌더링과 테스트를 완료한 후 MCP Token을 구성하는 것을 권장합니다. 가격, 혜택 및 영양 정보와 관련해서는 항상 현재 MCP가 반환하는 실제 데이터를 기준으로 삼으세요.
프로젝트는 MIT License로 오픈 소스이며, GitHub Issues를 통해 문제를 제보하거나 Pull Request를 제출해 개선에 참여할 수 있습니다.