Pancake POS MCP

Сервер протокола контекста модели (MCP), обертывающий REST API Pancake POS, позволяющий ИИ-ассистентам, таким как Claude, управлять операциями вьетнамской электронной коммерции POS с помощью 23 специализированных инструментов и 7 справочных ресурсов.

Обзор

Pancake POS MCP предоставляет API Pancake POS (https://pos.pages.fm/api/v1) в качестве инструментов протокола контекста модели, позволяя Claude и другим ИИ-ассистентам автоматизировать управление POS в следующих областях:

• Основные POS: Заказы, товары, клиенты, инвентаризация

• Цепочка поставок: Склады, поставщики, закупки, перемещения, инвентаризация

• Продажи: Возвраты, обмены, комплекты, акции, ваучеры

• CRM: Контакты, сделки, активности

• Мультиканальность: Электронная коммерция (Shopee/Lazada/TikTok), прямые трансляции (Livestream Commerce)

• Операции: Сотрудники, вебхуки, аналитика, информация о магазине, поиск адресов

Предварительные требования

• Bun (среда выполнения) — установите с https://bun.sh (curl -fsSL https://bun.sh/install | bash)

• API-ключ Pancake POS + ID магазина — см. Получение учетных данных Pancake POS ниже. Обратите внимание: это API Pancake POS (электронная коммерция / инвентаризация), а не API пользователя/социального инбокса Pancake — это разные продукты с разными ключами.

• Node.js 18+ (опционально, для инструментов разработки)

Быстрый старт

Переход от нуля к работающему MCP-серверу примерно за 5 минут:

# 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 работает только с продуктом Pancake POS по адресу https://pos.pages.fm — системой электронной коммерции / инвентаризации / управления заказами. API пользователя/инбокса Pancake на pages.fm — это другой продукт с другим API-ключом, и он здесь не поддерживается.

Вам нужны два значения из вашей учетной записи Pancake POS:

1. PANCAKE_POS_SHOP_ID — числовой ID вашего магазина

   • Войдите на https://pos.pages.fm и проверьте URL или настройки магазина, чтобы найти числовой ID магазина

2. PANCAKE_POS_API_KEY — ваш API-токен Pancake POS

   • Панель управления Pancake POS → Cài đặt (Настройки) → API → Generate API key

   • Скопируйте ключ сразу — он отображается только один раз

Храните оба значения в секрете. Никогда не добавляйте их в git. Файл .gitignore уже исключает .env и .dev.vars.

Конфигурация

Обязательные (устанавливаются при быстром старте):

Опциональные:

Использование

Stdio Transport (Claude Desktop)

Режим по умолчанию. Добавьте в конфигурацию Claude Desktop claude_desktop_config.json:

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

HTTP Transport (Удаленный доступ)

Включите потоковый 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 (Serverless Edge)

Разверните глобально на 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

URL Workers: https://pancake-pos-mcp.<ваш-поддомен>.workers.dev/mcp

Подключите Claude Desktop через 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: таймаут 8 секунд на вызов, 2 повторные попытки, ограничение частоты запросов отключено (модель без сохранения состояния для каждого запроса). Бесплатный уровень: 100 тыс. запросов в день. Полную информацию см. в руководстве по развертыванию.

Доступные инструменты

Доступные ресурсы

Статические справочные ресурсы (аутентификация не требуется):

Архитектура

• API Client: Ограничение частоты запросов (token-bucket: 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 — Полный справочник API Pancake POS

Устранение неполадок

Несколько неочевидных моментов:

• 429 Too Many Requests — достигнут лимит Pancake (1000/мин, 10000/час). Встроенный механизм token-bucket автоматически ограничивает скорость; уменьшите параллелизм на стороне вызывающего приложения.

• Тесты завершаются ошибкой Cannot find package 'cloudflare:test' — используйте bun run test (vitest), а не нативный bun test. Для тестов Workers нужен плагин vitest pool worker.

• Claude Desktop не видит инструменты — путь command/args в claude_desktop_config.json должен быть абсолютным. Перезапустите Claude Desktop после редактирования конфигурации.

При возникновении других ошибок проверьте сообщение об ошибке и учетные данные в .env.

Лицензия

Лицензия MIT — см. файл LICENSE для получения полного текста.