Pancake POS MCP

Pancake POS REST APIをラップしたModel Context Protocol (MCP) サーバー。ClaudeなどのAIアシスタントが、23の専用ツールと7つの参照リソースを使用してベトナムのEコマースPOS運用を管理できるようにします。

概要

Pancake POS MCPは、Pancake POS API (https://pos.pages.fm/api/v1) をModel Context Protocolツールとして公開し、Claudeやその他のAIアシスタントが以下のPOS管理を自動化できるようにします。

• コアPOS: 注文、商品、顧客、在庫

• サプライチェーン: 倉庫、サプライヤー、仕入れ、移動、棚卸し

• 販売: 返品、交換、コンボ、プロモーション、クーポン

• CRM: 連絡先、案件、活動

• マルチチャネル: Eコマース (Shopee/Lazada/TikTok)、ライブストリームコマース

• 運用: 従業員、Webhook、分析、店舗情報、住所検索

前提条件

• Bun (ランタイム) — https://bun.sh からインストール (curl -fsSL https://bun.sh/install | bash)

• Pancake POS APIキー + 店舗ID — 以下のPancake POS認証情報の取得を参照してください。これはPancake POS (Eコマース/在庫) 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製品（Eコマース/在庫/注文管理システム）でのみ動作します。pages.fmのPancakeユーザー/インボックスAPIは別の製品であり、異なるAPIキーを使用するため、ここではサポートされていません。

Pancake POSアカウントから2つの値が必要です:

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

   • キーは一度しか表示されないため、すぐにコピーしてください

両方の値を秘密にしてください。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回のリトライ、レート制限無効 (リクエストごとのステートレスモデル)。無料枠: 1日10万リクエスト。詳細はデプロイガイドを参照してください。

利用可能なツール

利用可能なリソース

静的参照リソース (認証不要):

アーキテクチャ

• APIクライアント: トークンバケットレート制限 (1000/分, 10000/時間)、指数バックオフリトライ (3回試行)

• ツール: ビジネスドメインごとに整理された23のMCPツール

• スキーマ検証: 厳密なランタイム検証のための判別共用体を持つ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ファイルを参照してください。