AI 튜토리얼

McButler 튜토리얼: 맥도날드 MCP로 추천, 영양 분석, 매장 가격 비교 및 단체 주문 구성하기

이 튜토리얼에서는 McButler를 설치하고 사용하는 방법을 소개합니다. 6개의 명령어로 메뉴 추천, 세트 영양 성분 분석, 매장별 전체 비용 비교, 여러 명의 단체 주문 구성, 맥험 점수 계산 및 인터랙티브 미니극 생성을 수행할 수 있습니다.

2026년 10월 24일약 14분 소요

McButler 튜토리얼: 맥도날드 MCP로 추천, 영양 분석, 매장 가격 비교 및 단체 주문 구성하기

McButler란 무엇인가

McButler(맥도날드 셀프 버틀러)는 맥도날드 공식 MCP를 기반으로 한 주문 보조 프로젝트입니다. 단순히 가격을 기준으로 세트를 추천하는 것이 아니라, 예산, 건강, 시간, 기피 음식, 개인 선호 등의 제약 조건을 동시에 고려합니다.

이 프로젝트는 WorkBuddy Skill로 사용할 수 있으며, 로컬 CLI를 통해 내장된 데모 데이터로 실행할 수도 있습니다. 개발자는 데이터 파싱 및 점수 계산 모듈을 재사용하여 맥도날드 MCP가 반환하는 데이터를 자체 클라이언트에 연결할 수 있습니다.

프로젝트 저장소는 GitHub에 있으며, 맥도날드 작은 극장은 온라인 체험 페이지도 제공합니다. McButler는 독립 출품작이며 맥도날드 공식 제품이 아니라는 점에 유의하세요.

6가지 핵심 기능

1. 일일 추천

recommend는 절약, 건강, 인기의 세 가지 모드를 지원합니다. 각 모드는 서로 다른 정렬 로직을 사용하며 단순히 정렬 필드 하나만 바꾸는 방식이 아닙니다.

절약 모드: 가격 정규화 값, 할인 폭, 100kcal당 가격을 종합하여 총액이 낮다는 이유만으로 소량 메뉴가 앞에 배치되지 않도록 합니다.
건강 모드: 건강 점수와 에너지 적합도를 결합하고, 실제 영양 데이터가 있는 후보를 우선 고려합니다.
인기 모드: 인기 메뉴 태그, 과거 주문 빈도, 할인을 종합합니다.

2. 건강 점검

health는 프로젝트의 기술적 핵심입니다. 영양 인터페이스는 단품 데이터만 제공하므로 McButler는 먼저 세트 상세 정보를 읽고, 세트를 기본 구성품으로 나눈 다음 각 항목을 영양 표와 매칭하여 열량, 단백질, 지방, 나트륨, 칼슘 등의 데이터를 합산합니다.

세트 상세 정보
→ 기본 구성 읽기
→ 각 단품의 영양 데이터 매칭
→ 영양 값 합산
→ 건강 점수 및 감점 항목 계산

건강 점수는 100점 만점으로, 에너지 범위, 단백질, 지방의 에너지 비율, 나트륨, 당류·지방 부담, 채소·과일 가산점을 고려합니다. 자세한 공식은 저장소의 references/model-spec.md에서 확인할 수 있습니다.

3. 매장 전체 비용 비교

stores는 가장 가까운 매장, 가장 저렴한 매장 또는 전체 비용을 종합하여 매장을 선택할 수 있습니다. 종합 모드에서는 상품 가격뿐 아니라 왕복 거리, 도보 시간, 대기 시간을 비용으로 환산합니다.

전체 비용 = 상품 가격
         + 거리 비용(왕복 0.5위안/km)
         + 시간 비용(왕복 도보 시간 + 대기 시간) × 0.30위안/분

따라서 가장 가까운 매장이 반드시 가장 경제적인 것은 아닙니다. 대기 시간은 현재 MCP 인터페이스가 직접 제공하는 데이터가 아니므로 사용자가 입력하거나 추정해야 합니다.

4. 단체 식사 구성

bulk는 행정, HR, 학급 및 팀 단체 주문 상황을 위한 기능입니다. 인원수, 1인당 예산, 소고기 제외, 매운 음식 제외 등의 조건에 따라 그룹별로 식사를 구성하고, 가격 계산 과정에 계속 전달할 수 있는 orderItems를 출력합니다.

결과에는 그룹별 인원수, 세트 수량, 총액, 1인당 가격, 절약 금액, 1인당 열량 등의 정보가 포함됩니다. 다만 ‘소고기 제외’는 현재 메뉴 이름의 키워드 필터링에 의존하므로, 메뉴에 성분이 명확히 표시되지 않은 음식까지 식별한다고 보장할 수는 없습니다.

5. 맥 리스크 점수

credit는 소비자 신용평가 카드를 참고하여 계정과 개별 주문에 대해 300~950점의 맥 리스크 점수를 계산합니다. 여섯 가지 기준은 결제 이행 안정성, 소비 주기, 예산 관리, 혜택 활용률, 계정 자산, 취향 다양성입니다.

점수 결과에는 각 기준의 점수와 데이터 출처가 표시되므로, 설명할 수 없는 총점 하나만 출력하지 않습니다. 이 기능은 재미를 위한 소비 분석이며 실제 금융 신용 평가를 의미하지 않습니다.

6. 맥도날드 작은 극장

theater는 쿠폰, 맥 리스크 점수, 열량 데이터를 바탕으로 다섯 캐릭터 사이의 주문 논쟁을 생성하고 단일 파일 HTML 페이지를 출력합니다. 생성된 페이지에는 추가 의존성이 필요하지 않으며 브라우저에서 바로 열 수 있습니다.

실행 환경 준비

로컬 모드에는 Python 3.8 이상만 필요하며, Python 표준 라이브러리만 사용하므로 서드파티 패키지를 설치할 필요가 없습니다. 온라인 MCP 모드에서는 사용 가능한 MCP Token이 필요합니다.

저장소 복제 및 자체 테스트 실행

git clone https://github.com/jouaaaaaa/mcd-self-butler.git
cd mcd-self-butler
python scripts/selftest.py

자체 테스트에는 건강 점검, 세 가지 추천 방식, 계정 및 주문 맥 리스크 점수, 단체 식사, 매장 비교, 텍스트 전용 작은 극장을 다루는 9개의 오프라인 사례가 포함되어 있습니다. 모두 통과하면 로컬 환경과 데모 데이터가 정상적으로 작동한다는 뜻입니다.

방법 1: WorkBuddy에 Skill로 설치

저장소의 SKILL.md, scripts/, references/를 다음 디렉터리에 넣습니다.
```
~/.workbuddy/skills/mcd-self-butler/
```
WorkBuddy에서 ‘전문가·스킬·커넥터’로 들어간 뒤, ‘커넥터’, ‘사용자 지정 커넥터’, ‘MCP 구성’을 차례로 선택합니다.

맥도날드 MCP의 Streamable HTTP 설정을 입력하고 자리표시자를 자신의 Token으로 바꿉니다.

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

mcd-mcp 커넥터를 활성화한 뒤 자연어로 요청합니다.

다음 요청부터 시작할 수 있습니다.

“난징시루에 있는데, 근처 맥도날드 중 빅맥 3종 세트를 가장 저렴하게 살 수 있는 곳은 어디야?”
“이 세트의 칼로리와 더 건강하게 바꿀 방법을 알려줘.”
“부서 30명 단체 식사야. 1인당 30위안이고, 5명은 소고기를 먹지 않아.”
“내 맥 리스크 점수는 몇 점이야?”
“식사를 기다리느라 너무 지루해. 서로 싸우게 해줘.”

방법 2: 로컬 CLI 사용

로컬 CLI는 저장소에 포함된 데모 스냅샷을 사용하므로 Token이나 인터넷 연결이 필요하지 않습니다. 여섯 가지 기능은 모두 scripts/mcd_butler.py를 통해 호출합니다.

세트 영양 확인

python scripts/mcd_butler.py health \
  --nutrition demo/nutrition.txt \
  --combo demo/combo_9900011128.json

이 명령은 세트를 분해하고 영양 표와 매칭한 뒤 요약 결과를 생성합니다. 출력에는 각 구성 항목의 영양 데이터, 세트 합계, 건강 점수, 구체적인 감점 사유가 포함됩니다.

건강 추천 받기

python scripts/mcd_butler.py recommend \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --mode healthy \
  --meal lunch \
  --budget 45 \
  --top 5 \
  --details demo/details.json

--mode healthy는 건강 모드를 사용한다는 뜻이고, --meal lunch는 점심 상황을 지정하며, --budget 45는 예산을 45위안으로 제한하고, --top 5는 상위 5개 결과를 반환합니다.

다른 전략을 살펴보려면 CLI가 지원하는 모드에 따라 절약 또는 인기 로직으로 바꿔 사용할 수 있습니다. 각 모드는 서로 다른 가치 함수를 사용하므로 결과가 크게 달라질 수 있습니다.

맥 리스크 점수 계산

python scripts/mcd_butler.py credit \
  --orders demo/orders.json \
  --account demo/account.json \
  --coupons demo/coupons.md \
  --nutrition demo/nutrition.txt

이 명령은 과거 주문, 계정 정보, 쿠폰, 영양 데이터를 결합하여 총점, 등급, 여섯 가지 기준의 상세 내역을 출력합니다. 데모 데이터의 예시 결과는 771점, 빅맥 등급이지만 실제 점수는 입력 데이터에 따라 달라집니다.

30인 단체 식사 구성

python scripts/mcd_butler.py bulk \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --headcount 30 \
  --budget 30 \
  --no-beef 5 \
  --no-spicy 4

여기서는 30명, 1인당 예산 30위안, 소고기를 먹지 않는 5명, 매운 음식을 먹지 않는 4명을 설정했습니다. 프로그램은 그룹별로 세트를 선택하고 수량을 계산할 수 있는 주문 항목을 생성합니다.

매장 전체 비용 비교

python scripts/mcd_butler.py stores \
  --stores demo/stores.json \
  --mode balanced

balanced 모드는 거리, 시간, 가격을 종합합니다. 자체 데이터를 사용할 때는 대기 시간을 명확히 제공하거나 추정해야 하며, 예시 값을 실시간 결과로 간주해서는 안 됩니다.

맥도날드 작은 극장 생성

python scripts/mcd_butler.py theater \
  --context demo/theater_context.json \
  --out theater.html

실행하면 현재 디렉터리에 theater.html이 생성됩니다. 브라우저에서 바로 열어 캐릭터 대화, 한 글자씩 표시되는 말풍선, 최종 판정 효과를 볼 수 있습니다.

방법 3: 자체 MCP 클라이언트 연결

개발자는 두 가지 통합 방법을 사용할 수 있습니다.

원시 응답 저장: MCP 클라이언트에서 매장, 메뉴, 상세 정보, 영양, 주문 또는 쿠폰 등의 도구를 호출하고, 원시 응답을 demo/ 예시와 같은 용도의 파일로 저장한 뒤 CLI에 전달합니다.
모듈 직접 호출: scripts/lib/의 함수를 가져와 MCP가 반환한 Python dict를 직접 전달합니다.

데이터 로드 계층의 mcdata.py는 {"success": true, "data": ...} 형태의 MCP 원시 응답과 사람이 간소화한 형식을 모두 지원합니다. 따라서 일반적으로 도구 응답을 그대로 저장할 수 있으며, 먼저 수동으로 정리할 필요가 없습니다.

프로젝트 아키텍처 이해

McButler의 처리 과정은 네 계층으로 요약할 수 있습니다.

클라이언트 계층: WorkBuddy Agent 또는 다른 MCP 클라이언트가 요청을 시작합니다.
MCP 서비스 계층: 매장, 메뉴, 상세 정보, 영양, 가격 계산, 쿠폰, 포인트, 주문 등의 데이터를 가져옵니다.
데이터 로드 계층: mcdata.py가 압축 해제, 정규화, 이름 퍼지 매칭을 담당합니다.
비즈니스 모델 계층: health.py, credit.py, bulk.py, recommend.py, theater.py가 각각 점수 계산, 식사 구성, 추천, 대본 생성을 수행합니다.

mcd_butler.py는 통합 CLI 진입점으로 Markdown 또는 JSON을 출력할 수 있어 사람이 확인하기에도 적합하고 후속 프로그램에 연결하기도 쉽습니다.

고급 사용 팁

세트 상세 정보를 우선 제공

영양 인터페이스는 단품 데이터만 제공합니다. 세트를 분석할 때는 세트 상세 정보도 함께 전달하여 프로그램이 기본 구성에 따라 항목별로 조회하도록 하는 것이 좋습니다. 영양 데이터가 하나도 매칭되지 않으면 프로젝트는 결과를 임의로 만들어내지 않고 건강 점수를 ‘—’로 표시합니다.

상황에 맞는 추천 모드 선택

예산이 엄격할 때는 절약 모드를 사용하고 100kcal당 가격을 확인합니다.
체중 감량이나 운동 상황에서는 건강 모드를 사용하고 단백질, 지방, 나트륨의 감점 내역도 함께 확인합니다.
인기 메뉴와 개인의 과거 선호를 함께 고려하려면 인기 모드를 사용합니다.

재현을 위해 MCP 원본 데이터 저장

추천 결과를 디버깅할 때는 해당 MCP 원본 응답을 저장하는 것이 좋습니다. 이렇게 하면 이후 메뉴, 가격 또는 판매 상태가 변경되더라도 동일한 데이터로 계산 과정을 재현할 수 있습니다.

데이터 품질 구분

McButler는 세 가지 데이터 표기를 사용합니다.

실측: 세트 메뉴를 분해한 후 항목별로 합산하여 얻은 데이터입니다.
공식: 단품 영양 정보표에서 직접 가져온 데이터입니다.
추정: 완전한 데이터가 없을 때의 대략적인 추정치이며, 명확히 표시됩니다.

자동화된 결과를 표시할 때 이러한 표기를 삭제해서는 안 됩니다. 표기는 사용자에게 데이터 출처와 신뢰도를 구분하도록 안내하는 역할을 합니다.

업무 범위 확인

현재 단체 주문 기능에는 기업 단체 주문의 할인 규칙을 중복 적용하는 최적화가 아직 연동되지 않았습니다. 소고기 제외 여부는 주로 메뉴명 키워드로 판단하며, 대기 시간도 명시적으로 입력해야 합니다. 실제 주문에 사용하기 전에는 맥도날드 공식 채널을 통해 가격, 판매 상태 및 메뉴 구성 성분을 다시 확인해야 합니다.

영양 분석은 참고용일 뿐이며, 의료·영양 또는 기타 전문적인 조언을 대신하지 않습니다. 질병, 임신 또는 어린이 식단과 관련된 경우 전문가와 상담해야 합니다.

맺음말

McButler는 MCP 원본 데이터를 설명 가능한 소비 의사결정으로 전환하는 방법을 보여 줍니다. 세트 메뉴 분석, 영양 점수 및 매장 기준 총비용부터 단체 주문 그룹화, 재미 점수와 인터랙티브 콘텐츠까지, 모두 통합 CLI 또는 WorkBuddy Skill을 통해 사용할 수 있습니다.

처음 사용한다면 먼저 python scripts/selftest.py를 실행한 다음 health, recommend, stores를 차례로 시도하는 것이 좋습니다. 오프라인 흐름을 확인한 후 MCP Token을 구성하여 실시간 데이터를 연동하세요.