📚 SBH MCP Server

Model Context Protocol (MCP) adapter dành cho hệ thống Sổ Bán Hàng (SBH) – giúp kết nối tự động giữa n8n và API của SBH một cách chuẩn hóa, nhanh chóng và có thể mở rộng.

🚀 Mục tiêu của dự án

Dự án này cung cấp MCP Server (dựa trên fastmcp + Node.js) để thực thi các business tools cho hệ sinh thái SBH. Nó đóng vai trò như cầu nối giữa n8n workflow (frontend) và hệ thống backend SBH, qua chuẩn MCP của OpenAI.

🧩 Khi nào sử dụng?

• Khi bạn cần tích hợp SBH vào luồng workflow tự động (ví dụ: xử lý hóa đơn, sản phẩm, khách hàng...).
• Khi bạn muốn xây dựng các "tools" có thể gọi từ ChatGPT hoặc custom agent.
• Khi bạn cần chuẩn hóa cách gọi API SBH qua mô hình command-based.

🖼️ Kiến trúc hệ thống

graph TD
    A[n8n Workflow] --> B[MCP Client]
    B --> C[MCP Server<br/>Node.js + fastmcp]
    C --> D[SBH API]

✨ Tính năng chính

• 🧠 Dễ tích hợp vào n8n workflow hoặc OpenAI custom GPT
• 🔒 Giao tiếp an toàn qua signature + timestamp
• 🧪 Tích hợp kiểm thử (Vitest), linting (ESLint), và chuẩn mã hóa
• 📦 Viết bằng TypeScript với cấu trúc module rõ ràng

🛠️ Yêu cầu hệ thống

• Node.js >= 18
• pnpm package manager

⚙️ Cài đặt và khởi chạy

Cài đặt dependencies

pnpm install

Phát triển (Development)

# Chạy kèm hot reload
pnpm dev:watch

# Chạy thủ công (không auto-reload)
pnpm dev

Kiểm thử & format

pnpm test        # chạy unit tests
pnpm lint        # kiểm tra code style
pnpm format      # format lại toàn bộ codebase

📦 Build Production

pnpm clean       # xoá build cũ
pnpm build       # build TypeScript
pnpm start       # chạy production mode
pnpm preview     # build + start thử nghiệm

🧪 Kiểm thử endpoint MCP

Sử dụng MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Hoặc dùng FastMCP CLI (trực tiếp source):

npx fastmcp dev src/index.ts

📄 Thông tin bổ sung

• 📁 Source repo: https://code.finan.one/ai-agent/sbh-mcp
• 📧 Liên hệ kỹ thuật: [email protected]
• 📄 Giấy phép sử dụng: MIT License

🧠 Ghi chú cho Dev

• Cấu trúc dự án được tổ chức theo module TypeScript.
• Sử dụng zod cho validation và type safety.
• Thêm tool mới? → Xem file src/index.ts để biết cách thêm tool mới.
• Cấu hình môi trường được quản lý qua .env file.