Pancake POS MCP

Model Context Protocol (MCP) 服务器，封装了 Pancake POS REST API，使 Claude 等 AI 助手能够通过 23 个专用工具和 7 个参考资源管理越南电子商务 POS 运营。

概述

Pancake POS MCP 将 Pancake POS API (https://pos.pages.fm/api/v1) 作为 Model Context Protocol 工具公开，允许 Claude 和其他 AI 助手自动化管理以下 POS 业务：

• 核心 POS： 订单、产品、客户、库存

• 供应链： 仓库、供应商、采购、调拨、盘点

• 销售： 退货、换货、组合商品、促销、优惠券

• CRM： 联系人、交易、活动

• 多渠道： 电子商务（Shopee/Lazada/TikTok）、直播带货

• 运营： 员工、Webhook、分析、店铺信息、地址查询

前置要求

• Bun (运行时) — 从 https://bun.sh 安装 (curl -fsSL https://bun.sh/install | bash)

• Pancake POS API Key + Shop 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

   • 立即复制密钥 — 它仅显示一次

请妥善保管这两个值。切勿将其提交到 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 工具

• 模式验证： 使用 Zod 和判别联合类型进行严格的运行时验证

• 传输： Stdio（默认）+ 可流式传输 HTTP + Cloudflare Workers（可选 Bearer 令牌认证）

• 错误处理： 带有代码和消息的结构化错误响应

开发

类型检查

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 run test (vitest)，而不是原生的 bun test。Workers 测试需要 vitest pool worker 插件。

• Claude Desktop 看不到工具 — claude_desktop_config.json 中的 command/args 路径必须是绝对路径。编辑配置后请重启 Claude Desktop。

对于其他错误，请检查错误消息并验证 .env 凭据。

许可证

MIT 许可证 — 详见 LICENSE 文件。