메가MGC커피 앱 재고조회 MCP 재현 가이드

작성일: 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커피 매장 조회

• 앱 메뉴 검색

• 단일 매장 상품 재고 조회

• 전국 매장 대상 상품 재고 조회

• 지역 매장 대상 상품 재고 조회

• 전체 매장 리스트 캐싱 및 캐시 기반 지역 검색

Related MCP server: Daiso MCP Server

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)는 제한 없이 계산됨