Haravan MCP

Haravan E-commerce OpenAPI MCP Server — Kết nối AI assistants với Haravan stores.

MCP (Model Context Protocol) server cho phép AI assistants (Claude, Cursor, Trae) tương tác trực tiếp với Haravan APIs: quản lý sản phẩm, đơn hàng, khách hàng, tồn kho, webhooks và nhiều hơn.

English below.

---

Bắt đầu nhanh

Sử dụng với Claude / Cursor / Trae

Thêm vào file cấu hình MCP:

{
  "mcpServers": {
    "haravan-mcp": {
      "command": "npx",
      "args": ["-y", "haravan-mcp", "mcp", "-t", "<your_access_token>"]
    }
  }
}

Sử dụng với Docker (HTTP mode)

# Clone repo
git clone <repo-url> && cd HaravanMCP

# Cấu hình token
cp docker/.env.example docker/.env
# Sửa docker/.env → điền HARAVAN_ACCESS_TOKEN

# Chạy
docker compose -f docker/docker-compose.yml up -d

# MCP endpoint: http://localhost:4567/mcp
# Health check: http://localhost:4567/health

Sử dụng với OAuth 2.0

# Bước 1: Login
npx haravan-mcp login -a <app_id> -s <app_secret>

# Bước 2: Cấu hình MCP
{
  "mcpServers": {
    "haravan-mcp": {
      "command": "npx",
      "args": ["-y", "haravan-mcp", "mcp", "-a", "<app_id>", "--oauth"]
    }
  }
}

---

Kiến trúc 2 lớp

Claude Skill Layer (AI reasoning, insights, formatting)
         │
         │ MCP Protocol
         ▼
MCP Server Layer (pagination, rate limiting, aggregation)
         │
         │ HTTPS + Bearer Token
         ▼
Haravan REST API (apis.haravan.com)

Smart Tools (7): Server-side pagination + aggregation cho data lớn Base Tools (63): 1:1 mapping với Haravan API cho detail/CRUD

---

Smart Tools

Tool	Chức năng
hrv_orders_summary	Tổng DT, AOV, status/source/cancel breakdown, so sánh kỳ trước
hrv_top_products	Top N sản phẩm theo doanh thu + variant breakdown
hrv_order_cycle_time	Median/p90 time-to-confirm/close, đơn stuck
hrv_customer_segments	RFM 8 segments + action suggestions
hrv_inventory_health	Phân loại: out_of_stock / low / dead / healthy
hrv_stock_reorder_plan	DSR + reorder point + suggested qty per variant
hrv_inventory_imbalance	Cross-location imbalance + transfer suggestions

---

Base Tools (63 tổng)

Category	Tools	Mô tả
Customers	14	CRUD khách hàng + địa chỉ
Orders	13	CRUD đơn hàng + transactions
Products	11	CRUD sản phẩm + variants
Inventory	5	Kiểm kho + locations
Shop	6	Shop info, kho, nhân viên
Content	11	Pages, blogs, articles, script tags
Webhooks	3	Subscribe/unsubscribe

---

Presets

# Smart tools only (dashboard/analytics)
haravan-mcp mcp -t <token> --tools "preset.smart"

# Default (smart + detail drill-down)
haravan-mcp mcp -t <token> --tools "preset.default"

# Full CRUD cho specific resources
haravan-mcp mcp -t <token> --tools "preset.products,preset.orders"

# Tất cả tools
haravan-mcp mcp -t <token> --tools "all"

# Mix presets + individual tools
haravan-mcp mcp -t <token> --tools "preset.smart,haravan_webhooks_list"

Preset	Tools	Use case
preset.default	17	AI assistant — smart + drill-down
preset.smart	7	Dashboard, analytics
preset.light	7	Read-only minimal
preset.products	11	Product management
preset.orders	13	Order management
preset.customers	14	Customer management
preset.inventory	7	Inventory management
preset.content	11	Content management
preset.webhooks	3	Webhook management

---

CLI Commands

haravan-mcp mcp -t <token>                   # Start server (stdio)
haravan-mcp mcp -t <token> -m http -p 3000   # Start server (HTTP)
haravan-mcp mcp -t <token> --tools "preset.smart"  # Custom tools

haravan-mcp login -a <app_id> -s <secret>    # OAuth login
haravan-mcp whoami                            # Show stored tokens
haravan-mcp logout -a <app_id>        

... [View full README on GitHub](https://github.com/pluginmd/Haravan-MCP#readme)