MGC

작성일: 2026-07-04 (KST)
대상 앱: 메가MGC커피 Android 앱 co.kr.waldlust.megacoffee
확인 버전: 2.0.7 / versionCode=85
기준 방식: ADB 연결 단말의 앱 화면 및 APK smali 분석, 앱 API 실호출

1. 목적

이 문서는 메가MGC커피 앱에서 사용하는 API를 바탕으로, 상품 검색, 매장 검색, 매장별 sold_out 재고 상태 조회를 재현하고 MCP 도구로 호출하는 절차를 정리합니다.

현재 MCP 서버는 다음 작업을 지원합니다.

• 메가MGC커피 매장 조회
• 앱 메뉴 검색
• 단일 매장 상품 재고 조회
• 전국 매장 대상 상품 재고 조회
• 지역 매장 대상 상품 재고 조회
• 전체 매장 리스트 캐싱 및 캐시 기반 지역 검색

2. 핵심 엔드포인트

베이스 URL:

• https://app.annhouse.co.kr/api/

APK 분석에서 확인된 추가 베이스 URL:

• https://preview-app.mgcglobal.co.kr/api/
• https://devapp.annhouse.co.kr/api/

현재 구현에서 사용하는 핵심 엔드포인트:

• 메뉴 목록: POST /api/menu/general/list
• 추천 메뉴 목록: POST /api/menu/rcmnd/list
• 메뉴 검색: POST /api/menu/search
• 메뉴 옵션: POST /api/menu/option
• 매장 목록: POST /api/store/list

재고 판정에 사용하는 필드:

• 상품 코드: item_cd
• 상품명: item_nm
• 가격: price
• 이미지: img
• 품절 여부: sold_out
• 매장 코드: store_cd

3. 공통 요청 조건

실측 기준 최소 헤더:

• content-type: application/json
• accept: application/json
• user-agent: okhttp/4.12.0

환경 변수로 API 베이스 URL과 User-Agent를 바꿀 수 있습니다.

• MGC_APP_API_BASE_URL
• MGC_APP_USER_AGENT

실행 인자로도 같은 값을 지정할 수 있습니다.

• --app-api-base-url
• --app-user-agent
• --stock-api-url

4. 재현 명령

A. 전체 메뉴 목록 조회

curl -sS 'https://app.annhouse.co.kr/api/menu/general/list' \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'user-agent: okhttp/4.12.0' \
  --data '{"store_cd":""}' \
  | jq '.all.upper_ctg_list[0].ctg_list[0].item_list[0] | {item_cd,item_nm,price,sold_out,img}'

기대 결과:

• item_cd, item_nm 존재
• sold_out 값 확인 가능

B. 특정 매장 기준 메뉴 목록 조회

curl -sS 'https://app.annhouse.co.kr/api/menu/general/list' \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'user-agent: okhttp/4.12.0' \
  --data '{"store_cd":"001638"}' \
  | jq '.. | objects | select(.item_cd? == "107350") | {item_cd,item_nm,price,sold_out}'

기대 결과:

• 해당 매장에서 상품이 노출되면 item_cd: "107350" 반환
• sold_out: true이면 품절
• sold_out: false이면 판매 가능
• 결과가 없으면 해당 매장 메뉴에 노출되지 않은 상태

C. 매장 목록 조회

curl -sS 'https://app.annhouse.co.kr/api/store/list' \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'user-agent: okhttp/4.12.0' \
  --data '{
    "use_location": false,
    "latitude": "0",
    "longitude": "0",
    "keyword": "",
    "amenities_cd_list": [],
    "page": 1,
    "page_size": 20,
    "item_list": []
  }' \
  | jq '.store_list[0] | {store_cd,name,addr,status,latitude,longitude}'

기대 결과:

• store_cd, name, addr 존재

D. 위치 기반 근처 매장 조회

curl -sS 'https://app.annhouse.co.kr/api/store/list' \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'user-agent: okhttp/4.12.0' \
  --data '{
    "use_location": true,
    "latitude": "37.4979",
    "longitude": "127.0276",
    "keyword": "",
    "amenities_cd_list": [],
    "page": 1,
    "page_size": 10,
    "item_list": []
  }' \
  | jq '.store_list[] | {store_cd,name,addr}'

기대 결과:

• 지정 좌표 주변 매장 목록 반환

E. 전국 매장별 상품 노출 및 품절 상태 재현

전국 조회는 다음 절차를 반복합니다.

1. POST /api/store/list를 page 증가 방식으로 호출해 전체 매장 수집
2. 전체 매장 리스트를 data/mgc-stores.json에 캐싱
3. 지역 조건이 있으면 캐시된 매장명/주소 기준으로 필터링
4. 각 store_cd로 POST /api/menu/general/list 호출
5. item_cd 또는 상품명으로 메뉴 검색
6. 메뉴가 있으면 sold_out으로 판매 가능/품절 판정
7. 메뉴가 없으면 notListed로 분류

캐시 파일:

• 기본 경로: 패키지 내부 data/mgc-stores.json
• 기본 TTL: 720시간(30일)
• 환경 변수: MGC_STORE_CACHE_PATH

캐시 파일에는 다음 값이 저장됩니다.

• refreshedAt
• count
• stores[].storeCode
• stores[].name
• stores[].address
• stores[].latitude
• stores[].longitude

이전 방식처럼 매번 전체 매장을 새로 수집하는 대신, 기본적으로 패키지에 포함된 캐시를 우선 사용합니다. GitHub 배포 사용자는 저장소에 포함된 data/mgc-stores.json을 바로 사용합니다. MGC_STORE_CACHE_PATH 또는 storeCachePath를 지정하면 해당 경로를 사용자 실행 폴더 기준으로 사용합니다.

전국 재고 조회 내부 흐름:

1. 캐시가 없거나 만료되었으면 전체 매장 리스트 새로 수집
2. 각 store_cd로 POST /api/menu/general/list 호출
3. item_cd 또는 상품명으로 메뉴 검색
4. 메뉴가 있으면 sold_out으로 판매 가능/품절 판정
5. 메뉴가 없으면 notListed로 분류

실측 예시:

• 상품명: 와앙 핫 치즈스틱 & 딥
• 상품 코드: 107350
• 수집 매장: 4,286개
• 상품 노출 매장: 41개
• 판매 가능: 40개
• 품절: 1개
• 품절 매장: 001583 송파나루역점

전체 실측 결과 파일:

• mgc-cheesestick-national.json

5. MCP 구현 매핑

refresh_mgc_stores

전체 매장 리스트 캐시 갱신 도구입니다.

입력:

{
  "cachePath": "data/mgc-stores.json",
  "maxStores": 5000
}

출력:

• cachePath
• refreshedAt
• count
• sampleStores

list_mgc_stores_by_region

캐시된 전체 매장 리스트에서 지역 조건에 맞는 매장을 조회합니다.

입력:

{
  "regionQuery": "서울 종로구",
  "resultLimit": 100
}

혜화/대학로권처럼 앱 주소에 행정동이 직접 들어가지 않는 경우:

{
  "city": "서울",
  "district": "종로구",
  "neighborhoods": ["혜화", "대학로"],
  "resultLimit": 100
}

출력:

• totalStores
• matchedStores
• storeCache.fromCache
• storeCache.cachePath
• storeCache.refreshedAt
• stores

find_mgc_stores

매장 검색 도구입니다.

입력:

• latitude
• longitude
• sigungu
• limit

소스:

• 앱 API: POST /api/store/list
• 보조 소스: 메가MGC커피 공개 웹 매장 조회

출력:

• appStores[].storeCode
• appStores[].name
• appStores[].address
• appStores[].latitude
• appStores[].longitude

search_mgc_menu

메뉴 검색 도구입니다.

입력:

• query
• limit

소스:

• 앱 API: POST /api/menu/general/list
• 보조 소스: 메가MGC커피 공개 웹 메뉴 조회

출력:

• appMenus[].itemCode
• appMenus[].name
• appMenus[].price
• appMenus[].soldOut
• appMenus[].imageUrl

check_mgc_stock

단일 매장 또는 기본 메뉴 기준 재고 조회 도구입니다.

입력:

• productName
• storeCode
• storeId
• storeName
• sigungu
• latitude
• longitude

소스:

• 기본: POST /api/menu/general/list
• 커스텀 연동: MGC_STOCK_API_URL

판정:

• sold_out: false -> available
• sold_out: true -> sold_out
• 메뉴를 찾지 못하면 공개 웹 근거만 반환하며 unknown

check_mgc_stock_nationwide

전국 또는 지역 필터 기반 재고 조회 도구입니다.

입력:

{
  "itemCode": "107350",
  "productName": "와앙 핫 치즈스틱 & 딥",
  "regionQuery": "서울 종로구",
  "refreshStores": false,
  "storeCacheTtlHours": 720,
  "maxStores": 5000,
  "concurrency": 8,
  "resultLimit": 100
}

지역 입력:

• regionQuery: 자유형 지역 문자열
• city: 시/도, 예: 서울
• district: 시/군/구, 예: 종로구
• neighborhoods: 동/도로명/역명/매장명 키워드 배열, OR 조건
• regionKeyword: 공백 토큰 전체가 매장명/주소에 포함되어야 함
• regionKeywords: 여러 지역 문구 중 하나라도 매칭되면 포함
• refreshStores: 재고 조회 전 매장 캐시 강제 갱신
• storeCachePath: 매장 캐시 파일 경로
• storeCacheTtlHours: 매장 캐시 TTL. 기본값은 720시간입니다.

regionQuery 해석 규칙:

• 서울 종로구 -> 서울 AND 종로구
• 서울 종로구 이화동 혜화동 -> 서울 AND 종로구 AND (이화동 OR 혜화동)

소스:

• 매장 수집: POST /api/store/list
• 매장별 메뉴 조회: POST /api/menu/general/list

출력:

• checkedStores
• totalStores
• matchedStores
• matchedStoreSamples
• storeCache
• foundCount
• availableCount
• soldOutCount
• notListedCount
• errorsCount
• availableStores
• soldOutStores

check_mgc_stock_by_region

지역 매장 대상 재고 조회 전용 도구입니다.

서울 종로구 전체 조회:

{
  "itemCode": "107350",
  "regionQuery": "서울 종로구",
  "maxStores": 5000,
  "concurrency": 8,
  "resultLimit": 100
}

서울 종로구의 이화동/혜화동 키워드 조회:

{
  "itemCode": "107350",
  "city": "서울",
  "district": "종로구",
  "neighborhoods": ["이화동", "혜화동"],
  "maxStores": 5000,
  "concurrency": 8,
  "resultLimit": 100
}

주의:

• 앱 매장 주소가 행정동 이름을 항상 포함하지는 않습니다.
• 예를 들어 혜화권 매장이 혜화동 대신 혜화로, 대학로, 서울혜화초교점처럼 저장될 수 있습니다.
• 이 경우 neighborhoods에 혜화로, 대학로, 혜화 같은 실제 주소/매장명 키워드를 같이 넣으면 됩니다.

6. 설치 및 실행

npm install
npm run build
node dist/server.js

앱 API 베이스 URL을 실행 인자로 바꾸려면:

node dist/server.js \
  --app-api-base-url https://app.annhouse.co.kr/api/ \
  --app-user-agent okhttp/4.12.0

검증:

npm run build
npm test

현재 확인 결과:

• TypeScript 빌드 통과
• Vitest 테스트 통과
• checkNationwideStock({ itemCode: "107350", maxStores: 20 }) 스모크 테스트 통과

7. MCP 설정 예시

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "node",
      "args": ["C:/Users/sh953/Documents/MGC MCP/dist/server.js"]
    }
  }
}

커스텀 재고 API를 우선 사용하려면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "node",
      "args": ["C:/Users/sh953/Documents/MGC MCP/dist/server.js"],
      "env": {
        "MGC_STOCK_API_URL": "https://example.internal/mgc-stock"
      }
    }
  }
}

앱 API 베이스 URL을 바꾸려면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "node",
      "args": ["C:/Users/sh953/Documents/MGC MCP/dist/server.js"],
      "env": {
        "MGC_APP_API_BASE_URL": "https://app.annhouse.co.kr/api/",
        "MGC_APP_USER_AGENT": "okhttp/4.12.0"
      }
    }
  }
}

실행 인자로 앱 API 베이스 URL을 바꾸려면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "node",
      "args": [
        "C:/Users/sh953/Documents/MGC MCP/dist/server.js",
        "--app-api-base-url",
        "https://app.annhouse.co.kr/api/",
        "--app-user-agent",
        "okhttp/4.12.0"
      ]
    }
  }
}

GitHub에 업로드한 저장소를 직접 사용하려면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:maskelog/MGC_MCP",
        "--app-api-base-url",
        "https://app.annhouse.co.kr/api/",
        "--app-user-agent",
        "okhttp/4.12.0"
      ]
    }
  }
}

GitHub 배포 방식에서는 저장소의 data/mgc-stores.json이 패키지에 포함됩니다. 따라서 사용자는 별도 캐시 생성 없이 바로 지역 재고 조회를 실행할 수 있습니다.

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:maskelog/MGC_MCP",
        "--app-api-base-url",
        "https://app.annhouse.co.kr/api/"
      ]
    }
  }
}

캐시를 사용자 작업 폴더에 따로 저장하고 싶으면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:maskelog/MGC_MCP"
      ],
      "env": {
        "MGC_STORE_CACHE_PATH": "data/mgc-stores.json"
      }
    }
  }
}

특정 브랜치나 태그를 고정하려면:

{
  "mcpServers": {
    "mgc-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:maskelog/MGC_MCP#main",
        "--app-api-base-url",
        "https://app.annhouse.co.kr/api/"
      ]
    }
  }
}

8. 캡처 및 분석 메모

ADB 확인:

• 연결 단말: R3CY10A8WCN
• 앱 패키지: co.kr.waldlust.megacoffee
• 메인 액티비티: co.kr.waldlust.megacoffee/.ui.main.MainActivity

APK 분석에서 확인한 항목:

• MegaApi.smali
• GeneralMenuRequest
• StoreInfoRequest
• MegaOrderOptionRequest
• 메뉴 응답 모델의 item_cd, item_nm, sold_out

생성/보관된 작업 파일:

• apk/base.apk
• mgc-current.png
• mgc-product-detail.png
• mgc-cheesestick-national.json

9. 실패 대응

1. 401/403 또는 앱 API 실패

• 앱 최신 버전에서 헤더, 베이스 URL, 세션 요구 여부 재확인
• MGC_APP_USER_AGENT를 실제 앱 User-Agent로 조정

2. 메뉴가 전역 조회에서는 보이지만 매장별 조회에서 없음

• 해당 매장 메뉴에 상품이 노출되지 않은 상태일 수 있음
• 이 경우 MCP는 notListed로 집계

3. 상품명이 오타인 경우

• 가능한 경우 itemCode를 우선 사용
• 예: 와앙 핫 치즈스틱 & 딥 -> 107350

4. 전국 조회가 오래 걸리는 경우

• maxStores를 낮춰 부분 검증
• concurrency를 4~12 범위에서 조정
• 기본값은 concurrency: 8

5. 결과가 너무 큰 경우

• resultLimit로 반환 매장 수 제한
• 집계 수치(checkedStores, foundCount, soldOutCount)는 제한 없이 계산됨