Vai trò
Cho phép agent AI (Claude Code, Claude Desktop, Cursor, trợ lý trong app) làm việc trên dữ liệu thật của cửa hàng, với quyền không vượt quá quyền của khoá hay người dùng đang gọi.
Công nghệ sử dụng
| Công nghệ | Dùng để làm gì, dùng như thế nào |
|---|---|
| core-agent-mcp: TypeScript + MCP SDK | MCP server chạy qua stdio. Mỗi tool ứng với một endpoint /api/internal/*, tham số khai báo bằng zod. Dùng cho Claude Code khi phát triển và vận hành; test bằng Vitest. |
| Script sinh manifest | export-mcp-manifest xuất mcp-tools.json để backend nhúng vào bản build. register-gateway-tools đăng ký bộ tool lên SPARK AI Gateway. Thêm tool chỉ cần sửa ở một nơi. |
| MCP trong backend (C# / .NET 8) | Viết tay, không dùng SDK: JSON-RPC 2.0 qua Streamable HTTP tại /api/mcp trên tên miền từng cửa hàng. Mỗi lời gọi tool được chuyển thành request tới API nội bộ của chính backend. |
| Khoá API theo cửa hàng | Header Bearer ck_…, quyền theo vai trò, giới hạn tần suất. Có Mcp-Session-Id, kiểm Origin để chống DNS rebinding. |
| Xác nhận 2 bước | Thao tác ghi quan trọng trả về 409 requiresConfirmation kèm mô tả việc sẽ làm. Agent phải hỏi người dùng rồi gửi lại kèm confirm: true. |
| Nhật ký | Mỗi phiên và mỗi lời gọi được lưu vào PostgreSQL trong 90 ngày, giá trị bí mật được che. |
| SPARK AI Gateway | Trợ lý trong app lấy danh sách tool đọc theo vai trò rồi gọi LLM qua Gateway. Model trả về tool_calls, backend tự chạy tool bằng khoá ngắn hạn. |
Thiết kế phân quyền
- Phân quyền theo vai trò, cách ly dữ liệu bằng RLS và bước xác nhận đều nằm ở backend, không nằm ở lớp agent. Định danh người dùng lấy từ khoá hoặc phiên đã xác thực, không bao giờ lấy từ tham số do LLM sinh ra.
- Thiết kế ban đầu có một middleware ReAct riêng (Python/FastAPI) làm lớp phân quyền. Sau đó phân quyền được chuyển vào backend để MCP, REST và trợ lý AI dùng chung một lớp, nên middleware được bỏ.
