BOS MCP Server

MCP (Model Context Protocol) server cho phép AI assistants (Claude, Cursor, Trae) tương tác trực tiếp với BOS ERP System qua REST API.

Tính năng

• 69 tools cho business operations
• TypeScript + Node.js 18+
• Token bucket rate limiting (60 RPM)
• Exponential backoff retry
• Stdio & HTTP transport
• JSON-RPC 2.0

Cài đặt

npm install
npm run build

Environment Variables

| Variable | Default | Mô tả | |----------|---------|--------| | BOS_API_URL | https://bos.ai.vn | BOS domain root (NO /api suffix) | | BOS_API_TOKEN | | Bearer token cho auth (optional) | | `MCP_API_KEY` | | API key cho MCP M2M auth (required) | | BOS_API_TIMEOUT | 30000 | Request timeout (ms) |

Chạy

# Stdio mode (default - cho Claude Code)
npm start

# HTTP mode (cho web deployments)
npm run http

Claude Code Integration

{
  "mcpServers": {
    "bos": {
      "command": "node",
      "args": ["/path/to/bos-mcp/dist/index.js"],
      "env": {
        "BOS_API_URL": "https://bos.ai.vn/api"
      }
    }
  }
}

Docker

FROM node:18-alpine
WORKDIR /app
COPY package.json dist/
RUN npm install
CMD ["node", "dist/http.js"]

Tools Categories (69 total)

Health & Management (18 tools)

• boscli_health_* - System health checks
• boscli_module_* - Module CRUD
• boscli_route_* - Route listing
• boscli_cache_* - Cache management
• boscli_system_* - System info, logs, git, deploy

Products (6 tools)

• bos_product_list, bos_product_show, bos_product_search
• bos_product_create, bos_product_update, bos_product_delete

Orders (6 tools)

• bos_order_list, bos_order_show, bos_order_create
• bos_order_update_status, bos_order_cancel, bos_order_count_by_status

Cart (7 tools)

• bos_cart_get, bos_cart_add_item, bos_cart_update_item
• bos_cart_remove_item, bos_cart_clear
• bos_cart_apply_voucher, bos_cart_remove_voucher

Customers (5 tools)

• bos_customer_list, bos_customer_show, bos_customer_create
• bos_customer_update, bos_customer_orders

Inventory (4 tools)

• bos_inventory_list, bos_inventory_check, bos_inventory_update
• bos_inventory_low_stock

Vouchers (4 tools)

• bos_voucher_list, bos_voucher_validate, bos_voucher_create
• bos_customer_vouchers

Loyalty (5 tools)

• bos_loyalty_points_balance, bos_loyalty_points_history
• bos_loyalty_earn, bos_loyalty_redeem, bos_loyalty_tiers

Stores (3 tools)

• bos_store_list, bos_store_show, bos_store_nearby

Checkout & Payment (4 tools)

• bos_checkout_calculate, bos_checkout_create
• bos_payment_methods, bos_payment_verify

Promotions (3 tools)

• bos_promotion_list, bos_promotion_show, bos_promotion_apply

Home & Engagement (4 tools)

• bos_home, bos_banners
• bos_notifications, bos_notification_mark_read

License

MIT