Toàn cảnh Sapo MCP — 105 tools, 4 modes, 2 transports

Cài đặt & kết nối

Ba cách dùng: npx (khuyến nghị cho MCP client), global, hoặc local dependency. Yêu cầu Node 20+.

# Pull latest, no install
npx -y sapo-mcp@latest --version

npm install -g sapo-mcp
sapo-mcp --help

npm install sapo-mcp
npx sapo-mcp --mode=pos-online

{
  "mcpServers": {
    "sapo": {
      "command": "npx",
      "args": ["-y", "sapo-mcp",
        "--mode=pos-online,web,analytics"],
      "env": {
        "SAPO_STORE": "mystorename",
        "SAPO_API_KEY": "xxx",
        "SAPO_API_SECRET": "yyy"
      }
    }
  }
}

4 Modes — chọn surface phù hợp use-case

Mỗi mode = một tập tools rời nhau (trừ 2 read-only variant tools dùng chung giữa pos-online và web). Bật nhiều mode bằng CSV: --mode=pos-online,web,analytics.

Toàn bộ 105 tools, nhóm theo resource

Ký hiệu trạng thái: ● canary-monitored, ● live-verified, ● docs-only, ● composed, ● broken. Tool có nhãn destructive yêu cầu cả SAPO_ALLOW_OPS phù hợp lẫn confirm: true trong args.

pos-online · 51 tools

web · 31 tools

pos-counter · 15 tools

analytics · 10 tools (all composed)

Tool verification status — biết tool nào tin được

5 cấp độ verification phản ánh độ chắc chắn schema khớp Sapo API. Canary nightly probe phát hiện drift trong 24h.

Canary-monitored endpoints (12)

Destructive ops — gated bằng 2 lớp

Mặc định mọi tool destructive (cancel, delete, set inventory, refund) đều bị block. Bật từng category qua SAPO_ALLOW_OPS, đồng thời mỗi call vẫn cần confirm: true trong args để tránh LLM nhỡ tay.

# Allow order cancel + standard deletes
SAPO_ALLOW_OPS=cancel,delete npx sapo-mcp --mode=pos-online

# Wildcard (chỉ dùng môi trường dev/test)
SAPO_ALLOW_OPS=*

CLI flags & environment variables

Toàn bộ knob cấu hình. Một trong SAPO_API_SECRET hoặc SAPO_API_SECRET_FILE là bắt buộc — file mode an toàn hơn vì không lộ qua ps//proc.

CLI flags

Environment variables

* Một trong hai bắt buộc. † HTTP-only; token enforce khi host khác 127.0.0.1 / localhost / ::1.

Hai transport: stdio + Streamable HTTP

stdio cho MCP client local (Claude Desktop, Cursor). HTTP cho remote agents, Docker, GoClaw — bind loopback mặc định, public bind yêu cầu auth token.

# Local-only (no auth)
sapo-mcp --mode=pos-online \
  --transport=http --port=3333

# Public bind — token required
SAPO_HTTP_HOST=0.0.0.0 \
SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
sapo-mcp --mode=pos-online --transport=http

Session model: mỗi MCP client một UUID session, isolated bằng McpServer instance. Idle session vượt SAPO_HTTP_SESSION_IDLE_MS bị evict tự động. Concurrent cap SAPO_HTTP_MAX_SESSIONS → 503 khi đầy. CORS off mặc định, bật bằng SAPO_HTTP_CORS_ORIGINS (CSV hoặc *).

Có sẵn examples/Dockerfile + examples/docker-compose.yml để tự host.

Probing & canary scripts

Trước khi cấu hình client, verify endpoint nào available trên store của bạn. Write-probe có safeguard: chỉ chạy nếu SAPO_STORE chứa test, dev hoặc sandbox.

# Read-only probe — safe, GET only
SAPO_STORE=mystore SAPO_API_KEY=xxx SAPO_API_SECRET=yyy npm run probe

# Schema drift check (probe + Zod validate vs fixtures)
npm run canary

# Write probe — chỉ chạy được trên test/dev/sandbox stores
npm run probe:write

Post-1.0 roadmap — đang chờ stable cut

Pre-1.0 nên tool name & schema có thể đổi giữa các minor bump. Các hạng mục dưới đây là gating cho 1.0.0: