Sapo-MCP

sapo-mcp

Model Context Protocol server for Sapo.vn POS & e-commerce platform.

Features

• 4 modes, 105 unique tools: pos-online (51), web (31), pos-counter (15), analytics (10) — 2 read tools shared between pos-online and web
• Two transports: stdio (Claude Desktop, Cursor) and Streamable HTTP (Docker, GoClaw)
• Safe by default: destructive ops gated via SAPO_ALLOW_OPS (default: none); all destructive calls also require confirm: true
• Single-tenant: one shop per server instance via Private App credentials
• Pre-1.0: tool names and schemas may shift on minor bumps. See Post-1.0 roadmap.

Installation

Requires Node.js 20 or newer. Verify with node --version.

Option A — npx (no install)

Recommended for MCP clients (Claude Desktop, Cursor). Always pulls the latest published version:

npx -y sapo-mcp@latest --version

Option B — global install

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

Option C — local project dependency

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

Quick Start

1. Get Credentials

Create a Private App at developers.sapo.vn:

• Store name: mystorename → mystorename.mysapo.net
• API Key + Secret

2. Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "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"
      }
    }
  }
}

Restart Claude Desktop. Tools appear under the 🔌 plug icon.

Cursor

Edit ~/.cursor/mcp.json or per-workspace .cursor/mcp.json:

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

MCP Inspector (test/debug)

npx @modelcontextprotocol/inspector \
  -e SAPO_STORE=mystorename \
  -e SAPO_API_KEY=xxx \
  -e SAPO_API_SECRET=yyy \
  npx -y sapo-mcp --mode=pos-online

Open the printed URL in a browser to inspect/invoke registered tools.

Use --mode=pos-online,web,analytics to register multiple modes (union of tools; shared tools registered once).

3. CLI Flags

Flag	Default	Description
--mode=<modes>	pos-online	Comma-separated list of modes to activate
--transport=<t>	stdio	Transport type (stdio or http)
--port=<port>	3333	HTTP port (ignored for stdio)
--help	—	Print usage and exit
--version	—	Print version and exit

Environment Variables

Variable	Required	Default	Description
SAPO_STORE	Yes	—	Store subdomain
SAPO_API_KEY	Yes	—	Private App API Key
SAPO_API_SECRET	Yes*	—	Private App API Secret
SAPO_API_SECRET_FILE	Yes*	—	Path to file containing secret (takes precedence)
SAPO_ALLOW_OPS	No	""	CSV of allowed destructive categories
SAPO_MAX_AUTO_PAGES	No	10	Max auto-pagination pages
SAPO_RETRY_MAX	No	3	HTTP retry attempts
SAPO_LOG_LEVEL	No	info	Log level (error/warn/info/debug/trace)
SAPO_HTTP_HOST	No†	127.0.0.1	HTTP bind host (loopback by default)
SAPO_HTTP_PORT	No	3333	HTTP port
SAPO_HTTP_MAX_SESSIONS	No	100	Max concurrent MCP sessions
SAPO_HTTP_SESSION_IDLE_MS	No	1800000	Idle session GC threshold (30 min)
SAPO_MCP_AUTH_TOKEN	No†	—	Bearer token. Required if host is non-loopback
SAPO_HTTP_CORS_ORIGINS	No	—	CSV of allowed CORS origins (default: disabled)

*One of SAPO_API_SECRET or SAPO_API_SECRET_FILE is required. †HTTP-only. Token is enforced when SAPO_HTTP_HOST is not 127.0.0.1/localhost/::1.

Modes

Mode	Status	Description
pos-online	0.5.0	Online orders, customers, fulfillment (51 tools)
web	0.5.0	Storefront, collections, articles, SEO (31 tools)
pos-counter	0.5.0	POS counter: locations, inventory write, suppliers, shifts, stock transfers (15 tools)
analytics	0.5.0	Composed reports: revenue, top products/customers, LTV, tax, channel breakdown, discount usage, shift report (10 tools)

Note: pos-counter excludes 5 internal-only endpoints (purchase_orders, purchase_returns, stock_adjustments, cash_transactions, cashbook) — these return HTTP 403 for Private App credentials and require an OAuth Partner App (post-1.0 roadmap).

Analytics tools auto-paginate up to SAPO_MAX_AUTO_PAGES; results carry truncated: true when the cap is hit.

Tool Verification Status

Verification levels for the 105 unique tools (last updated 2026-04-30):

Symbol	Level	What it means
✅	Canary-monitored	Endpoint + schema verified live; daily nightly probe via .github/workflows/canary.yml
🟢	Live-verified	Endpoint hit during development, schema captured to fixture, not in daily canary
🟡	Docs-only	Schema from docs/sapo-api-reference.md (Sapo official); mock tests only, no live probe
🔵	Composed	Not a Sapo endpoint — internal aggregation logic, logic-tested via unit tests
🚨	Broken	Known non-functional, see notes

Canary-monitored endpoints (drift detected within 24h)

Resource	Mode(s)	Endpoint
store	all	/admin/store.json
products (read)	pos-online, pos-counter	/admin/products.json
orders	pos-online, pos-counter	/admin/orders.json
customers	pos-online, pos-counter	/admin/customers.json
inventory_levels	pos-online, pos-counter	/admin/inventory_levels.json
locations	pos-counter	/admin/locations.json
draft_orders	pos-online	/admin/draft_orders.json
price_rules	pos-online	/admin/price_rules.json
pages	web	/admin/pages.json
suppliers	pos-counter	/admin/suppliers.json
stock_transfers	pos-counter	/admin/stock_transfers.json
payment_methods	pos-counter	/admin/payment_methods.json

🚨 Broken — needs investigation

Tool	Resource	Issue
list_pos_shifts	pos_shifts	/admin/pos_shifts.json returns Content-Type: text/html (Sapo POS web app shell), not JSON.
get_pos_shift	pos_shifts	Same as above. JSON API endpoint not yet located.

These 2 tools may fail at runtime. POS shift management currently requires admin UI.

Per-tool status

Click each section to expand the full tool list with status icons.

Customers (7)

• ✅ list_customers, get_customer, search_customers, count_customers, list_customer_orders
• 🟢 create_customer, update_customer

Customer Addresses (4)

• 🟡 list_customer_addresses, add_customer_address, update_customer_address, set_default_customer_address

Products (read) (4)

• ✅ list_products, get_product, search_products, count_products

Variants (read) (2)

• 🟡 list_variants_for_product, get_variant

Inventory (read) (1)

• ✅ get_inventory_levels

Orders (4)

• ✅ list_orders, get_order, count_orders, search_orders

Order Transactions (2)

• 🟢 list_order_transactions, create_order_transaction

Fulfillments (4)

• 🟢 list_fulfillments_for_order, get_fulfillment
• 🟡 create_fulfillment, update_fulfillment_tracking

Refunds (3)

• 🟢 list_refunds, get_refund, create_refund (create_refund destructive: SAPO_ALLOW_OPS=refund)

Draft Orders (7)

• ✅ list_draft_orders, get_draft_order
• 🟡 create_draft_order, update_draft_order, complete_draft_order, send_draft_order_invoice, delete_draft_order (destructive: delete)

Price Rules (5)

• ✅ list_price_rules, get_price_rule
• 🟡 create_price_rule, update_price_rule, delete_price_rule (destructive: delete)

Discount Codes (3)

• 🟡 list_discount_codes, create_discount_code, delete_discount_code (destructive: delete)

Destructive (cancel/delete-strict) (4)

• 🟡 cancel_order, close_order, cancel_fulfillment (destructive: cancel)
• 🟡 delete_customer, delete_variant (destructive: delete_strict)

Store (1)

• ✅ get_store_info

Articles (5)

• 🟡 list_articles, get_article, create_article, update_article, delete_article (destructive: delete)

Blogs (5)

• 🟡 list_blogs, get_blog, create_blog, update_blog, delete_blog (destructive: delete)

Pages (4)

• ✅ list_pages, get_page
• 🟡 update_page_seo, delete_page (destructive: delete)

Collections (10)

• 🟡 list_custom_collections, get_custom_collection, create_custom_collection, update_custom_collection, delete_custom_collection (destructive: delete)
• 🟡 list_smart_collections, get_smart_collection
• 🟡 list_collects, create_collect, delete_collect (destructive: delete)

Script Tags (3)

• 🟡 list_script_tags, create_script_tag, delete_script_tag (destructive: delete)

Products SEO (1)

• 🟡 update_product_seo

Variants (read, shared) (2)

• 🟡 list_variants_for_product, get_variant

Locations (2)

• ✅ list_locations, get_location

Payment Methods (1)

• ✅ list_payment_methods

Inventory (write) (3)

• 🟡 adjust_inventory_level, connect_inventory_level
• 🟡 set_inventory_level (destructive: inventory_set)

Variants (write) (1)

• 🟡 update_variant

POS Orders (2)

• ✅ list_pos_orders, get_pos_order (uses /admin/orders?source_name=pos)

Suppliers (2)

• ✅ list_suppliers, get_supplier

Stock Transfers (2)

• ✅ list_stock_transfers, get_stock_transfer

POS Shifts (2)

• 🚨 list_pos_shifts, get_pos_shift (see Broken section above — endpoint returns HTML)

All 10 are 🔵 composed (aggregate from multiple Sapo endpoints, no single endpoint to verify):

revenue_summary, top_products, top_customers, customer_ltv, tax_summary, online_vs_counter_breakdown, discount_usage_report, shift_report, inventory_low_stock, inventory_value

Destructive Operations

Destructive tools (cancel, delete, bulk-delete) are blocked by default. To enable specific categories:

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

Supported categories: cancel, delete, delete_strict, inventory_set, refund, shift_close, cashbook_write.

All destructive tool calls also require confirm: true in the tool arguments — this prevents accidental execution when an LLM calls the tool without explicit intent.

Security

ENV credentials are visible to other processes via ps / /proc/<pid>/environ on shared hosts. Use SAPO_API_SECRET_FILE to pass the secret via a file instead of an env var where possible.

Note: full secret-file isolation (reading the secret only at startup, then clearing) is tracked for the post-1.0 roadmap.

Probing

Verify which Sapo API endpoints are available on your store before configuring tools.

# Read-only probe — safe to run against any store (GET only)
SAPO_STORE=mystore SAPO_API_KEY=xxx SAPO_API_SECRET=yyy npm run probe

# Schema drift check — same probe + Zod validation against fixtures
npm run canary

Write-probe (npm run probe:write) refuses to run unless SAPO_STORE contains test, dev, or sandbox — never against production.

HTTP Transport (Remote / Docker)

Run as an HTTP server for remote MCP clients (e.g. GoClaw) or self-hosted Docker:

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

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

Endpoints:

Method	Path	Description
GET	/health	Liveness probe — returns { status, version, modes, sessions }
POST	/mcp	JSON-RPC over Streamable HTTP (creates a session on initialize)
GET	/mcp	SSE long-poll for an existing session (mcp-session-id header)
DELETE	/mcp	Terminate a session

Session model: Each MCP client gets a UUID session, isolated by an McpServer instance. Idle sessions (SAPO_HTTP_SESSION_IDLE_MS) are evicted automatically. Concurrent sessions cap at SAPO_HTTP_MAX_SESSIONS (503 returned when full).

Security:

• Defaults to 127.0.0.1 — loopback only. Token optional.
• Setting SAPO_HTTP_HOST=0.0.0.0 (or any non-loopback) requires SAPO_MCP_AUTH_TOKEN. The server refuses to start otherwise.
• CORS is off by default. Enable per-origin via SAPO_HTTP_CORS_ORIGINS (CSV of origins, or * for all). Only enable when serving browser-based agents.

Docker

See examples/Dockerfile and examples/docker-compose.yml.

docker build -f examples/Dockerfile -t sapo-mcp:local .
docker run --rm -p 3333:3333 \
  -e SAPO_STORE=mystore \
  -e SAPO_API_KEY=xxx -e SAPO_API_SECRET=yyy \
  -e SAPO_HTTP_HOST=0.0.0.0 \
  -e SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  sapo-mcp:local

Development

npm install
npm run typecheck   # Type check
npm run lint        # Lint
npm run test        # Run tests
npm run build       # Build for release

Post-1.0 roadmap

The 1.0.0 stable cut is gated on the following items, deferred from this release:

• MCP Resources — sapo://shop/info, sapo://orders/today, sapo://orders/pending, sapo://inventory/low-stock. Read-heavy data is more efficient as a Resource than repeated tool calls.
• MCP Prompts — templated workflows (respond_to_complaint, weekly_report, seo_optimize_product, customer_followup).
• Webhook receiver — sub-package surfacing Sapo webhooks as MCP events.
• OAuth 2.0 Partner App — multi-tenant SaaS deployments. Unlocks the 5 internal-only endpoints currently excluded from pos-counter and 4 deferred finance/PO reports (cashflow_summary, pnl_summary, supplier_purchase_summary, daily_pos_report).
• Storefront GraphQL module — verify Private App access; scope tools if available.

Changelog

See CHANGELOG.md for the per-version history.

License

MIT — See LICENSE