MCP: cho Claude xem báo cáo

Mèo con vừa dựng metrics, audit log & báo cáo - "đôi mắt" của shop. Nhưng để xem, phải mở dashboard và tự nhìn. Sẽ tiện hơn nhiều nếu mèo con hỏi Claude bằng lời: "doanh thu hôm nay bao nhiêu?", "SKU giftcard nào sắp hết kho?", "có giao dịch nạp tiền nào lạ không?" - và Claude trả lời từ số liệu của chính shop.

Cây cầu nối Claude với dữ liệu shop là MCP (Model Context Protocol). Bài này dựng một MCP server read-only cho shop - một cửa sổ chỉ-đọc, có xác thực, để mèo con (qua Claude) xem báo cáo mà không bao giờ đụng được vào tiền hay đơn.

MCP là một chuẩn mở do Anthropic khởi xướng, cho Claude kết nối tới dữ liệu và công cụ bên ngoài theo một cách chuẩn hoá. Nó thường được ví như cổng USB-C cho AI: thay vì mỗi nguồn dữ liệu một kiểu cắm riêng, mọi thứ nói chung một chuẩn. Web của mèo con mở một remote MCP server - một endpoint HTTPS - và Claude (trên claude.ai, Claude Desktop, hay Claude Code) cắm vào đó.

• ▸MCP (Model Context Protocol): chuẩn mở để Claude kết nối dữ liệu/công cụ bên ngoài.
• ▸Remote MCP server = một endpoint HTTPS shop tự mở ra; Claude là phía kết nối tới.
• ▸Mục tiêu bài này: một MCP server CHỈ ĐỌC báo cáo, có xác thực - không phải cổng điều khiển shop.

MCP server phơi ra hai thứ cho Claude. Tool là một hành động có tên và tham số mà Claude gọi được; resource là một mẩu dữ liệu Claude đọc trực tiếp. Cho việc xem báo cáo, mèo con chủ yếu định nghĩa vài tool đọc:

get_doanh_thu(tu_ngay, den_ngay)     -> tổng tiền, số đơn trong khoảng
get_ton_kho_thap(nguong)             -> các SKU giftcard tồn dưới ngưỡng
get_don_gan_day(so_luong)            -> vài đơn mới nhất (đã ẩn bớt thông tin)
get_su_kien_audit(tu_ngay)           -> nhật ký thao tác đáng chú ý
# KHÔNG có tool nào: tạo đơn, đổi giá, hoàn tiền, sửa kho...

• ▸Tool = hành động Claude gọi (có tên + tham số); resource = dữ liệu Claude đọc.
• ▸Báo cáo ⇒ chỉ định nghĩa tool ĐỌC, tuyệt đối không có tool ghi/sửa.
• ▸Mỗi tool trả số liệu tổng hợp đã lọc, không đổ nguyên bảng dữ liệu thô ra ngoài.

Một remote MCP server là một endpoint trên internet. Không khoá thì số liệu shop lộ cho bất kỳ ai biết URL. Vì vậy MCP server bắt buộc có xác thực: Claude kết nối qua OAuth - chủ shop đăng nhập một lần, Claude giữ token và đính kèm cho mỗi lần gọi. Cùng họ "đúng người mới xem được" với bài Đăng nhập Better-auth.

• ▸Remote MCP server công khai trên internet ⇒ phải có xác thực, không để trống.
• ▸MCP dùng OAuth: chủ shop đăng nhập một lần, Claude giữ token và gửi kèm mỗi request.
• ▸Token cấp đúng phạm vi ĐỌC BÁO CÁO - không kèm quyền chạm tiền/đơn/kho.

Mô tả cho Claude khá gọn: một MCP server phơi ra vài tool đọc ở Step 3, mỗi tool truy vấn báo cáo từ database (tái dùng đúng các hàm đã viết ở bài metrics), bọc xác thực, và không có tool ghi.

Dựng cho shop một remote MCP server read-only để xem báo cáo, dùng package
@modelcontextprotocol/sdk. Đặt route ở app/mcp/route.ts (Next.js App Router).

Expose đúng 4 tool ĐỌC sau, mỗi tool tái dùng các hàm truy vấn báo cáo đã viết
ở bài metrics (đừng viết query mới, import lại hàm cũ trong lib/reports):
  - get_doanh_thu(tu_ngay, den_ngay): trả tổng tiền và số đơn trong khoảng.
  - get_ton_kho_thap(nguong): trả các SKU giftcard tồn dưới ngưỡng.
  - get_don_gan_day(so_luong): trả vài đơn mới nhất, đã ẩn bớt PII (không trả
    email, số điện thoại khách).
  - get_su_kien_audit(tu_ngay): trả các dòng audit log đáng chú ý.

Mỗi tool chỉ trả số liệu tổng hợp đã lọc, KHÔNG đổ nguyên bảng dữ liệu thô.
TUYỆT ĐỐI không tạo tool nào ghi/sửa (tạo đơn, đổi giá, hoàn tiền, sửa kho).

Bọc xác thực OAuth bằng Better-auth: mỗi request tới MCP server phải có token
hợp lệ thuộc phạm vi đọc báo cáo, không có token thì trả 401. Tái dùng cấu hình
Better-auth đã có ở bài đăng nhập, đừng dựng hệ xác thực mới.

Xong khi: server chạy được ở localhost, gọi thử 4 tool đều trả số, và không có
tool nào sửa được dữ liệu.

Có server rồi, nối Claude vào. Vì remote MCP cần một URL công khai, mèo con làm bước này sau khi đã deploy shop lên domain (bài kế). Lúc phát triển, test trước bằng Claude Code trỏ vào localhost.

# Claude.ai / Claude Desktop: thêm một "connector"
#   → dán URL MCP server của shop → đăng nhập OAuth

# Claude Code (test khi phát triển hoặc dùng thật):
claude mcp add bao-cao-shop https://meoshop.vn/mcp

# Rồi hỏi bằng lời:
#   "Doanh thu 7 ngày qua thế nào?"
#   "SKU giftcard nào tồn dưới 10?"

Mèo con vừa cho shop một cách trò chuyện với số liệu: hỏi Claude bằng lời, nhận câu trả lời từ chính báo cáo của shop - qua một cửa read-only, có xác thực, không đụng được tiền hay đơn.

• ▸MCP server báo cáo = chỉ tool ĐỌC + xác thực OAuth + trả số tổng hợp (không PII thô).
• ▸Tách hẳn khỏi hành động admin; least privilege; subagent bảo mật rà lại.
• ▸Remote MCP cần URL công khai ⇒ kết nối Claude.ai sau khi deploy + có domain.