MCP Server (Model Context Protocol)

🔌 MCP Server — Model Context Protocol

Thông tin nhanh

• Vị trí mã nguồn: mcp-server/
• SDK: @modelcontextprotocol/sdk v1.x
• Transport: stdio (stdin/stdout)
• Tools: 7 CRM tools
• Dùng với: OpenFang, OpenClaw, hoặc bất kỳ MCP-compatible agent

Xem thêm: Agent API · OpenFang/OpenClaw

Kiến trúc

graph LR
    style AGENT fill:#2d333b,stroke:#d2a8ff,color:#e6edf3
    style MCP fill:#2d333b,stroke:#f0883e,color:#e6edf3
    style CLIENT fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style API fill:#2d333b,stroke:#3fb950,color:#e6edf3

    AGENT["🤖 AI Agent<br/>(OpenFang/OpenClaw)"]
    MCP["🔌 MCP Server<br/>(index.js)"]
    CLIENT["📡 CRM Client<br/>(crm-client.js)"]
    API["⚙️ CRM API<br/>(api.salehay.com)"]

    AGENT -->|"stdio (JSON-RPC)"| MCP
    MCP -->|"Tool call → method"| CLIENT
    CLIENT -->|"HTTP + X-Agent-Token"| API

Mô tả: Agent giao tiếp với MCP Server qua stdio. Khi agent gọi tool (ví dụ crm_search), MCP Server chuyển thành HTTP request qua CRM Client tới Agent API.

Cấu trúc files

mcp-server/
├── index.js         # Server entry point — khởi tạo Server, connect stdio transport
├── tools.js         # Tool definitions (inputSchema cho mỗi tool)
├── crm-client.js    # HTTP wrapper — gọi Agent API endpoints
└── package.json     # Dependencies: @modelcontextprotocol/sdk

Biến môi trường

Biến	Bắt buộc	Mô tả	Default
CRM_AGENT_TOKEN	✅	Agent token (tạo trong Admin)	—
CRM_BASE_URL	❌	URL API backend	https://api.salehay.com

7 CRM Tools

crm_create_lead

Tạo lead mới. Auto-create customer nếu phone chưa tồn tại.

Param	Type	Required	Mô tả
phone	string	✅	SĐT Việt Nam (0xxx, 9-11 số)
name	string	❌	Tên khách hàng
email	string	❌	Email
source	string	❌	Nguồn (default: agent)
service_interest	string	❌	Dịch vụ quan tâm
note	string	❌	Ghi chú
priority	string	❌	low / normal / high

crm_search

Tìm kiếm leads theo phone, name, hoặc status.

Param	Type	Required	Mô tả
query	string	❌	SĐT hoặc tên
status	string	❌	Filter status
limit	number	❌	Max results (default 20, max 50)

crm_update_lead

Cập nhật status, priority, hoặc note.

Param	Type	Required	Mô tả
lead_id	string	✅	Lead UUID
status	string	❌	Trạng thái mới
priority	string	❌	Priority mới
note	string	❌	Ghi chú mới

crm_log_call

Ghi nhận cuộc gọi tới lead hoặc booking.

Param	Type	Required	Mô tả
lead_id	string	❌*	Lead UUID
booking_id	string	❌*	Booking UUID
outcome	string	✅	answered / no_answer / busy / voicemail / rejected
duration_seconds	number	❌	Thời lượng (giây)
note	string	❌	Ghi chú
reject_reason	string	❌	Lý do từ chối

crm_get_bookings

Lấy danh sách bookings hôm nay + status summary. Không cần params.

crm_send_message

Log tin nhắn gửi qua Zalo, WhatsApp, SMS, Telegram.

Param	Type	Required	Mô tả
lead_id	string	❌*	Lead UUID
customer_id	string	❌*	Customer UUID
channel	string	✅	zalo / whatsapp / sms / telegram
message_text	string	❌	Nội dung tin nhắn
template_name	string	❌	Template name

crm_get_analytics

Analytics tổng hợp: pipeline, today’s metrics, hot leads, 30-day conversion. Không cần params.

CRM Client (crm-client.js)

HTTP wrapper đơn giản, gọi Agent API:

const crm = new CrmClient('https://api.salehay.com', 'agent_xxx');

// Các method:
crm.createLead({ phone: '0901234567', name: 'Test' });
crm.searchLeads('0901', { status: 'new', limit: 10 });
crm.updateLead('lead-uuid', { status: 'contacted' });
crm.logCall({ lead_id: 'uuid', outcome: 'answered' });
crm.getBookingsToday();
crm.sendMessage({ lead_id: 'uuid', channel: 'zalo', message_text: '...' });
crm.getAnalytics();

Mỗi request tự gắn header X-Agent-Token và Content-Type: application/json.

Quick Start

# 1. Install
cd mcp-server && npm install

# 2. Run
CRM_BASE_URL=https://api.salehay.com \
CRM_AGENT_TOKEN=agent_abc123... \
node index.js

Server sẽ log SaleHay CRM MCP Server running on stdio nếu thành công.

Xem hướng dẫn kết nối OpenFang/OpenClaw tại: Integration Guide