Pancake POS MCP

Model Context Protocol (MCP)-Server, der die Pancake POS REST-API umschließt und es KI-Assistenten wie Claude ermöglicht, vietnamesische E-Commerce-POS-Vorgänge mit 23 spezialisierten Tools und 7 Referenzressourcen zu verwalten.

Übersicht

Pancake POS MCP stellt die Pancake POS API (https://pos.pages.fm/api/v1) als Model Context Protocol-Tools bereit, wodurch Claude und andere KI-Assistenten die POS-Verwaltung in folgenden Bereichen automatisieren können:

• Kern-POS: Bestellungen, Produkte, Kunden, Inventar

• Lieferkette: Lager, Lieferanten, Einkäufe, Umlagerungen, Inventur

• Verkauf: Retouren, Umtausch, Kombi-Angebote, Werbeaktionen, Gutscheine

• CRM: Kontakte, Deals, Aktivitäten

• Multi-Channel: E-Commerce (Shopee/Lazada/TikTok), Livestream-Handel

• Betrieb: Mitarbeiter, Webhooks, Analysen, Shop-Informationen, Adresssuche

Voraussetzungen

• Bun (Laufzeitumgebung) — Installation über https://bun.sh (curl -fsSL https://bun.sh/install | bash)

• Pancake POS API-Schlüssel + Shop-ID — siehe Pancake POS-Anmeldedaten abrufen unten. Hinweis: Dies ist die Pancake POS (E-Commerce / Inventar) API, nicht die Pancake Benutzer/Social-Inbox-API — es handelt sich um unterschiedliche Produkte mit unterschiedlichen Schlüsseln.

• Node.js 18+ (optional, für Entwicklungstools)

Schnellstart

In ca. 5 Minuten zum funktionierenden MCP-Server:

# 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

Falls Schritt 4 einen Fehler ausgibt, überprüfen Sie Ihre .env-Werte und ob Sie bun install ausgeführt haben. Häufige Probleme sind unter Fehlerbehebung aufgeführt.

Pancake POS-Anmeldedaten abrufen

⚠️ Pancake POS ≠ Pancake (Social Inbox). Dieses MCP funktioniert nur mit dem Pancake POS-Produkt unter https://pos.pages.fm — dem E-Commerce / Inventar / Bestellverwaltungssystem. Die Pancake Benutzer/Inbox-API unter pages.fm ist ein anderes Produkt mit einem anderen API-Schlüssel und wird hier nicht unterstützt.

Sie benötigen zwei Werte aus Ihrem Pancake POS-Konto:

1. PANCAKE_POS_SHOP_ID — die numerische ID Ihres Shops

   • Melden Sie sich bei https://pos.pages.fm an und überprüfen Sie die URL oder die Shopeinstellungen, um die numerische Shop-ID zu finden.

2. PANCAKE_POS_API_KEY — Ihr Pancake POS API-Token

   • Pancake POS Dashboard → Cài đặt (Einstellungen) → API → Generate API key

   • Kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt.

Behandeln Sie beide Werte vertraulich. Committen Sie sie niemals in Git. Die .gitignore schließt .env und .dev.vars bereits aus.

Konfiguration

Erforderlich (im Schnellstart festgelegt):

Optional:

Verwendung

Stdio-Transport (Claude Desktop)

Standardmodus. Fügen Sie dies zur Claude Desktop-Konfiguration claude_desktop_config.json hinzu:

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

HTTP-Transport (Fernzugriff)

Aktivieren Sie den Streamable HTTP-Transport:

bun run src/index.ts --http

Der Server startet unter http://localhost:3000/mcp. Gesundheitsprüfung: http://localhost:3000/health

Mit Authentifizierung (empfohlen für die Produktion):

# .env
PORT=3000
MCP_AUTH_TOKEN=your_secret_token

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

Cloudflare Workers (Serverless Edge)

Weltweite Bereitstellung auf Cloudflare Workers für latenzarmen Zugriff von überall:

# 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.<ihr-subdomain>.workers.dev/mcp

Verbinden Sie Claude Desktop über mcp-remote:

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

Workers-Eigenschaften: 8s Timeout pro Upstream-Aufruf, 2 Wiederholungsversuche, Ratenbegrenzung deaktiviert (zustandsloses Modell pro Anfrage). Kostenloser Tarif: 100.000 Anfragen/Tag. Siehe Bereitstellungsanleitung für vollständige Details.

Verfügbare Tools

Verfügbare Ressourcen

Statische Referenzressourcen (keine Authentifizierung erforderlich):

Architektur

• API-Client: Token-Bucket-Ratenbegrenzung (1000/Min, 10000/Stunde), exponentielle Backoff-Wiederholungen (3 Versuche)

• Tools: 23 MCP-Tools, organisiert nach Geschäftsbereichen

• Schema-Validierung: Zod mit diskriminierten Unions für strikte Laufzeitvalidierung

• Transport: Stdio (Standard) + Streamable HTTP + Cloudflare Workers mit optionaler Bearer-Token-Authentifizierung

• Fehlerbehandlung: Strukturierte Fehlerantworten mit Code und Nachricht

Entwicklung

Typenprüfung

bun run typecheck

Tests ausführen

bun run test       # vitest (includes Workers tests)

Projektstruktur

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)

Siehe docs/code-standards.md für vollständige Entwicklungsrichtlinien.

Dokumentation

• codebase-summary.md — Architektur- und Implementierungsübersicht

• system-architecture.md — Detailliertes Systemdesign und Datenflüsse

• code-standards.md — TypeScript- und Tool-Implementierungsstandards

• project-overview-pdr.md — Projektanforderungen und Funktionen

• deployment-guide.md — Einrichtungs- und Bereitstellungsanweisungen

• project-roadmap.md — Implementierungsfortschritt und Meilensteine

• poscake-api-docs.md — Vollständige Pancake POS API-Referenz

Fehlerbehebung

Ein paar nicht offensichtliche Fallstricke:

• 429 Too Many Requests — Pancake-Ratenbegrenzung erreicht (1000/Min, 10000/Stunde). Der integrierte Token-Bucket drosselt automatisch; reduzieren Sie die Parallelität auf der Aufruferseite.

• Tests schlagen fehl mit Cannot find package 'cloudflare:test' — verwenden Sie bun run test (vitest), nicht das native bun test. Workers-Tests benötigen das vitest pool worker-Plugin.

• Claude Desktop sieht die Tools nicht — der Pfad für command/args in claude_desktop_config.json muss absolut sein. Starten Sie Claude Desktop nach dem Bearbeiten der Konfiguration neu.

Bei anderen Fehlern überprüfen Sie die Fehlermeldung und verifizieren Sie die .env-Anmeldedaten.

Lizenz

MIT-Lizenz — Siehe LICENSE-Datei für den vollständigen Text.