Pancake POS MCP

Servidor del Protocolo de Contexto de Modelo (MCP) que envuelve la API REST de Pancake POS, permitiendo a asistentes de IA como Claude gestionar operaciones de POS de comercio electrónico vietnamita con 23 herramientas especializadas y 7 recursos de referencia.

Descripción general

Pancake POS MCP expone la API de Pancake POS (https://pos.pages.fm/api/v1) como herramientas del Protocolo de Contexto de Modelo, permitiendo a Claude y otros asistentes de IA automatizar la gestión del POS en:

• POS principal: Pedidos, productos, clientes, inventario

• Cadena de suministro: Almacenes, proveedores, compras, transferencias, inventarios

• Ventas: Devoluciones, cambios, combos, promociones, cupones

• CRM: Contactos, tratos, actividades

• Multicanal: Comercio electrónico (Shopee/Lazada/TikTok), comercio en vivo (livestream)

• Operaciones: Empleados, webhooks, análisis, información de la tienda, búsqueda de direcciones

Requisitos previos

• Bun (entorno de ejecución) — instálelo desde https://bun.sh (curl -fsSL https://bun.sh/install | bash)

• Clave de API de Pancake POS + ID de tienda — consulte Obtención de credenciales de Pancake POS a continuación. Nota: esta es la API de Pancake POS (comercio electrónico / inventario), no la API de usuario/bandeja de entrada social de Pancake; son productos diferentes, claves diferentes.

• Node.js 18+ (opcional, para herramientas de desarrollo)

Inicio rápido

Llegue de cero a un servidor MCP funcional en unos 5 minutos:

# 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

Si el paso 4 imprime un error, verifique sus valores en .env y asegúrese de haber ejecutado bun install. Los problemas comunes se enumeran en Solución de problemas.

Obtención de credenciales de Pancake POS

⚠️ Pancake POS ≠ Pancake (bandeja de entrada social). Este MCP solo funciona con el producto Pancake POS en https://pos.pages.fm — el sistema de comercio electrónico / inventario / gestión de pedidos. La API de usuario/bandeja de entrada de Pancake en pages.fm es un producto diferente con una clave de API diferente y no es compatible aquí.

Necesita dos valores de su cuenta de Pancake POS:

1. PANCAKE_POS_SHOP_ID — el ID numérico de su tienda

   • Inicie sesión en https://pos.pages.fm y verifique la URL o la configuración de la tienda para encontrar el ID numérico de la tienda

2. PANCAKE_POS_API_KEY — su token de API de Pancake POS

   • Panel de control de Pancake POS → Cài đặt (Configuración) → API → Generate API key

   • Copie la clave inmediatamente; solo se muestra una vez

Mantenga ambos valores en secreto. Nunca los suba a git. El archivo .gitignore ya excluye .env y .dev.vars.

Configuración

Obligatorio (establecido en Inicio rápido):

Opcional:

Uso

Transporte Stdio (Claude Desktop)

Modo predeterminado. Añadir a la configuración de Claude Desktop claude_desktop_config.json:

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

Transporte HTTP (Acceso remoto)

Habilitar transporte HTTP transmitible:

bun run src/index.ts --http

El servidor se inicia en http://localhost:3000/mcp. Verificación de estado: http://localhost:3000/health

Con autenticación (recomendado para producción):

# .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)

Despliegue globalmente en Cloudflare Workers para acceso de baja latencia desde cualquier lugar:

# 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

URL de Workers: https://pancake-pos-mcp.<su-subdominio>.workers.dev/mcp

Conectar Claude Desktop mediante mcp-remote:

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

Características de Workers: tiempo de espera de 8s por llamada ascendente, 2 reintentos, limitador de tasa deshabilitado (modelo sin estado por solicitud). Nivel gratuito: 100k solicitudes/día. Consulte la guía de despliegue para obtener todos los detalles.

Herramientas disponibles

Recursos disponibles

Recursos de referencia estáticos (no se requiere autenticación):

Arquitectura

• Cliente API: Limitación de tasa de cubo de tokens (1000/min, 10000/hora), reintentos con retroceso exponencial (3 intentos)

• Herramientas: 23 herramientas MCP organizadas por dominio de negocio

• Validación de esquema: Zod con uniones discriminadas para una validación estricta en tiempo de ejecución

• Transporte: Stdio (predeterminado) + HTTP transmitible + Cloudflare Workers con autenticación opcional de token de portador

• Manejo de errores: Respuestas de error estructuradas con código y mensaje

Desarrollo

Verificación de tipos

bun run typecheck

Ejecutar pruebas

bun run test       # vitest (includes Workers tests)

Estructura del proyecto

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)

Consulte docs/code-standards.md para conocer las pautas completas de desarrollo.

Documentación

• codebase-summary.md — Resumen de arquitectura e implementación

• system-architecture.md — Diseño detallado del sistema y flujos de datos

• code-standards.md — Estándares de TypeScript e implementación de herramientas

• project-overview-pdr.md — Requisitos y características del proyecto

• deployment-guide.md — Instrucciones de configuración y despliegue

• project-roadmap.md — Progreso de implementación e hitos

• poscake-api-docs.md — Referencia completa de la API de Pancake POS

Solución de problemas

Algunos problemas no obvios:

• 429 Too Many Requests — alcanzó el límite de tasa de Pancake (1000/min, 10000/hora). El cubo de tokens incorporado limita automáticamente; reduzca el paralelismo en el lado del llamador.

• Las pruebas fallan con Cannot find package 'cloudflare:test' — use bun run test (vitest), no bun test nativo. Las pruebas de Workers necesitan el complemento vitest pool worker.

• Claude Desktop no ve las herramientas — la ruta command/args en claude_desktop_config.json debe ser absoluta. Reinicie Claude Desktop después de editar la configuración.

Para otros errores, verifique el mensaje de error y verifique las credenciales en .env.

Licencia

Licencia MIT — Consulte el archivo LICENSE para ver el texto completo.