Pancake POS MCP

Pancake POS REST API를 래핑하는 MCP(Model Context Protocol) 서버로, Claude와 같은 AI 어시스턴트가 23개의 전문 도구와 7개의 참조 리소스를 사용하여 베트남 전자상거래 POS 운영을 관리할 수 있도록 지원합니다.

개요

Pancake POS MCP는 Pancake POS API(https://pos.pages.fm/api/v1)를 MCP 도구로 노출하여 Claude 및 기타 AI 어시스턴트가 다음 분야 전반에 걸쳐 POS 관리를 자동화할 수 있도록 합니다:

• 핵심 POS: 주문, 상품, 고객, 재고

• 공급망: 창고, 공급업체, 구매, 이전, 재고 조사

• 판매: 반품, 교환, 콤보, 프로모션, 바우처

• CRM: 연락처, 거래, 활동

• 멀티 채널: 전자상거래(Shopee/Lazada/TikTok), 라이브 커머스

• 운영: 직원, 웹훅, 분석, 매장 정보, 주소 조회

사전 요구 사항

• Bun (런타임) — https://bun.sh 에서 설치 (curl -fsSL https://bun.sh/install | bash)

• Pancake POS API 키 + 매장 ID — 아래의 Pancake POS 자격 증명 얻기를 참조하세요. 참고: 이는 Pancake POS(전자상거래/재고) API이며, Pancake 사용자/소셜 받은 편지함 API가 아닙니다. 제품과 키가 서로 다릅니다.

• Node.js 18+ (선택 사항, 개발 도구용)

빠른 시작

약 5분 안에 작동하는 MCP 서버를 구축하세요:

# 1. Clone the repo
git clone https://github.com/nguyennguyenit/pancake-pos-mcp.git
cd pancake-pos-mcp

# 2. Install dependencies
bun install

# 3. Configure credentials
cp .env.example .env
# Open .env and fill in PANCAKE_POS_API_KEY + PANCAKE_POS_SHOP_ID
# (See "Getting Pancake POS credentials" section below)

# 4. Verify it runs
bun run src/index.ts
# Expected output:
#   [pancake-pos-mcp] Server started on stdio transport
# Press Ctrl+C to stop.

# 5. Connect Claude Desktop — see "Stdio Transport" section below

4단계에서 오류가 발생하면 .env 값을 다시 확인하고 bun install을 실행했는지 확인하세요. 일반적인 문제는 문제 해결에 나열되어 있습니다.

Pancake POS 자격 증명 얻기

⚠️ Pancake POS ≠ Pancake (소셜 받은 편지함). 이 MCP는 https://pos.pages.fm의 Pancake POS 제품(전자상거래/재고/주문 관리 시스템)에서만 작동합니다. pages.fm의 Pancake 사용자/받은 편지함 API는 다른 제품이며 다른 API 키를 사용하므로 여기서는 지원되지 않습니다.

Pancake POS 계정에서 다음 두 가지 값이 필요합니다:

1. PANCAKE_POS_SHOP_ID — 매장의 숫자 ID

   • https://pos.pages.fm에 로그인하여 URL 또는 매장 설정에서 숫자 매장 ID를 확인하세요.

2. PANCAKE_POS_API_KEY — Pancake POS API 토큰

   • Pancake POS 대시보드 → Cài đặt(설정) → API → Generate API key(API 키 생성)

   • 키를 즉시 복사하세요. 한 번만 표시됩니다.

두 값 모두 비밀로 유지하세요. 절대 git에 커밋하지 마세요. .gitignore는 이미 .env와 .dev.vars를 제외하고 있습니다.

구성

필수(빠른 시작에서 설정):

선택 사항:

사용법

Stdio 전송 (Claude Desktop)

기본 모드입니다. Claude Desktop 설정 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "pancake-pos": {
      "command": "bun",
      "args": ["run", "/path/to/pancake-pos-mcp/src/index.ts"]
    }
  }
}

HTTP 전송 (원격 액세스)

스트리밍 가능한 HTTP 전송을 활성화하세요:

bun run src/index.ts --http

서버가 http://localhost:3000/mcp에서 시작됩니다. 상태 확인: http://localhost:3000/health

인증 사용 시(프로덕션 권장):

# .env
PORT=3000
MCP_AUTH_TOKEN=your_secret_token

# Client usage
curl -H "Authorization: Bearer your_secret_token" http://localhost:3000/mcp

Cloudflare Workers (서버리스 엣지)

어디서나 짧은 지연 시간으로 액세스할 수 있도록 Cloudflare Workers에 전 세계적으로 배포하세요:

# Local development (uses .dev.vars for secrets)
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your credentials
bun run dev:workers
# Runs at http://localhost:8787

# Deploy to Cloudflare
wrangler login
bun run deploy

# Set production secrets
wrangler secret put PANCAKE_POS_API_KEY
wrangler secret put PANCAKE_POS_SHOP_ID
wrangler secret put MCP_AUTH_TOKEN

Workers URL: https://pancake-pos-mcp.<your-subdomain>.workers.dev/mcp

mcp-remote를 통해 Claude Desktop 연결:

{
  "mcpServers": {
    "pancake-pos": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://pancake-pos-mcp.<your-subdomain>.workers.dev/mcp",
        "--header", "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Workers 특성: 업스트림 호출당 8초 타임아웃, 2회 재시도, 속도 제한 비활성화(요청별 상태 비저장 모델). 무료 티어: 일일 10만 요청. 자세한 내용은 배포 가이드를 참조하세요.

사용 가능한 도구

사용 가능한 리소스

정적 참조 리소스(인증 불필요):

아키텍처

• API 클라이언트: 토큰 버킷 속도 제한(분당 1000회, 시간당 10000회), 지수 백오프 재시도(3회 시도)

• 도구: 비즈니스 도메인별로 구성된 23개의 MCP 도구

• 스키마 유효성 검사: 엄격한 런타임 유효성 검사를 위한 판별 유니온(discriminated unions)이 포함된 Zod

• 전송: Stdio(기본값) + 스트리밍 가능한 HTTP + 선택적 Bearer 토큰 인증이 포함된 Cloudflare Workers

• 오류 처리: 코드와 메시지가 포함된 구조화된 오류 응답

개발

타입 검사

bun run typecheck

테스트 실행

bun run test       # vitest (includes Workers tests)

프로젝트 구조

src/
├── api-client/              # HTTP layer with rate limiting
│   ├── pancake-http-client.ts
│   ├── request-builder.ts
│   └── response-parser.ts
├── tools/                   # 23 MCP tools (23 files)
├── resources/               # MCP reference resources
├── shared/                  # Schemas, errors, pagination
├── config.ts                # Environment configuration
├── server.ts                # MCP server factory
├── worker.ts                # Cloudflare Workers entry point
└── index.ts                 # Entry point (stdio + HTTP)

전체 개발 지침은 docs/code-standards.md를 참조하세요.

문서

• codebase-summary.md — 아키텍처 및 구현 개요

• system-architecture.md — 상세 시스템 설계 및 데이터 흐름

• code-standards.md — TypeScript 및 도구 구현 표준

• project-overview-pdr.md — 프로젝트 요구 사항 및 기능

• deployment-guide.md — 설정 및 배포 지침

• project-roadmap.md — 구현 진행 상황 및 마일스톤

• poscake-api-docs.md — 전체 Pancake POS API 참조

문제 해결

몇 가지 주의 사항:

• 429 Too Many Requests — Pancake 속도 제한(분당 1000회, 시간당 10000회)에 도달했습니다. 내장된 토큰 버킷이 자동으로 제한하므로 호출 측에서 병렬 처리를 줄이세요.

• 테스트가 Cannot find package 'cloudflare:test' 오류로 실패함 — 네이티브 bun test가 아닌 bun run test(vitest)를 사용하세요. Workers 테스트에는 vitest 풀 워커 플러그인이 필요합니다.

• Claude Desktop에서 도구가 보이지 않음 — claude_desktop_config.json의 command/args 경로는 절대 경로여야 합니다. 설정을 편집한 후 Claude Desktop을 다시 시작하세요.

기타 오류는 오류 메시지를 확인하고 .env 자격 증명을 확인하세요.

라이선스

MIT 라이선스 — 전체 텍스트는 LICENSE 파일을 참조하세요.