EN
AI
Đang vận hành

Core Agent Stack — MCP cho S Store

Lớp agent của S Store. Một bộ định nghĩa tool nghiệp vụ dùng cho hai MCP server: bản stdio cho Claude Code và bản Streamable HTTP cho từng cửa hàng trong backend. Cả hai dùng chung cơ chế xác nhận và phân quyền.

Thiết kế kiến trúc & bảo mật agent

Core Agent Stack — MCP cho S Store

189

Tool nghiệp vụ

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 SDKMCP 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 manifestexport-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àngHeader 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ướcThao 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 GatewayTrợ 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ỏ.

Hình ảnh

Một bộ tool nghiệp vụ, hai MCP server (stdio cho Claude Code, Streamable HTTP cho từng cửa hàng), chung một lớp quyền ở backend