MCP tool get_admin_entity_class_schema được thiết kế để giúp AI lấy danh sách các lớp entity mà admin runtime đang sử dụng, sau đó dùng thông tin đó để viết JPQL, hiểu mapping bảng/entity, hoặc hỗ trợ các truy vấn báo cáo dữ liệu admin chính xác hơn.

Bối cảnh

Khi AI cần trả lời các câu hỏi như “đếm số đơn hàng hôm nay”, “liệt kê user mới”, “tìm các bản ghi theo trạng thái”, vấn đề đầu tiên không phải là viết SQL ngay, mà là biết hệ thống admin đang có những entity nào, entity đó map với bảng nào, và kiểu khóa chính là gì.
Thay vì để AI đoán tên bảng hoặc thử các truy vấn metadata như SHOW TABLES, information_schema, hệ thống cung cấp MCP tool riêng để lấy schema entity của admin.
Tool này giúp AI có một catalog entity đáng tin cậy trước khi chạy các tool dữ liệu như admin_graphql_data_fetching.

Tool Chính

Tool cần dùng là:
get_admin_entity_class_schema
Tool này không yêu cầu input:
{}
Khi gọi tool, kết quả trả về không phải toàn bộ schema entity. Thay vào đó, tool trả về hướng dẫn download schema từ admin server, ví dụ:
curl --create-dirs -o .agents/admin-entity-class-schema.json {adminUrl}/graphql/api/v1/schemas/admin/entity-class
Thiết kế này có chủ ý: file schema có thể lớn, nên không nên nạp toàn bộ vào context chat. AI client nên lưu file vào thư mục local, ví dụ .agents/admin-entity-class-schema.json, rồi tìm kiếm cục bộ khi cần.

Schema Entity Chứa Gì

Endpoint schema admin entity trả về JSON array. Mỗi phần tử mô tả một entity class mà admin runtime scan được.
Thông tin chính gồm:
{
  "tableName": "example_table",
  "entityClass": "com.example.ExampleEntity",
  "idClass": "java.lang.Long"
}
Ý nghĩa:
tableName: tên bảng database lấy từ annotation table của entity. Nếu entity không khai báo tên bảng, giá trị có thể rỗng.
entityClass: tên đầy đủ của lớp entity JPA.
idClass: kiểu khóa chính. Nếu entity dùng IdClass, hệ thống lấy class trong annotation đó. Nếu không, hệ thống tìm field có annotation Id và dùng kiểu của field đó.
Schema được tạo bằng cách scan các package mà admin runtime đang quản lý, lấy các class có annotation JPA Entity, chuyển thành JSON, rồi sắp xếp theo tableName.

Luồng Hoạt Động

flowchart TD
    A[AI client cần biết entity admin] --> B[Gọi tools/call: get_admin_entity_class_schema]
    B --> C[Tool trả về URL download schema]
    C --> D[AI client dùng curl lưu vào .agents/admin-entity-class-schema.json]
    D --> E[Tìm entity/table/idClass trong file local]
    E --> F[Viết JPQL hoặc SQL phù hợp]
    F --> G[Gọi admin_graphql_data_fetching để lấy dữ liệu]
Điểm quan trọng là AI không nên đọc toàn bộ file schema vào hội thoại. File nên được cache local và chỉ tìm những phần liên quan đến câu hỏi hiện tại.

Khi Nào Nên Dùng

Dùng get_admin_entity_class_schema khi:
  • Cần biết entity class tương ứng với một bảng admin.
  • Muốn viết JPQL thay vì SQL native.
  • Không chắc tên entity, tên bảng, hoặc kiểu khóa chính.
  • Cần tạo truy vấn báo cáo nhưng chưa biết mô hình dữ liệu admin.
  • Query trước đó fail vì sai tên bảng hoặc entity.
Không nhất thiết dùng tool này nếu đã có query canonical chắc chắn, hoặc câu hỏi chỉ cần gọi một tool domain-specific có sẵn.

Kết Hợp Với Data Fetching

Sau khi biết entity/table, AI có thể dùng tool:
admin_graphql_data_fetching
Tool này nhận:
{
  "queryType": "SQL",
  "queryString": "select id, name from example_table where status = 'ACTIVE'",
  "skip": 0,
  "limit": 100
}
Hoặc với JPQL:
{
  "queryType": "JPQL",
  "queryString": "select e.id, e.name from ExampleEntity e where e.status = 'ACTIVE'",
  "skip": 0,
  "limit": 100
}
Tool data fetching chỉ cho phép truy vấn đọc. Query phải là một câu SELECT, không được có comment, dấu chấm phẩy, nhiều statement, DDL, DML, lock clause hoặc truy vấn vào system metadata. limit tối đa là 1000.

Prompt Gợi Ý

Prompt tổng quát cho AI client:
Bạn đang làm việc với MCP server admin.

Khi cần trả lời câu hỏi liên quan đến dữ liệu admin:
1. Nếu cần biết entity/table/id class, hãy gọi tool get_admin_entity_class_schema.
2. Không đọc toàn bộ schema vào context. Hãy dùng lệnh curl mà tool trả về để lưu file vào .agents/admin-entity-class-schema.json.
3. Tìm kiếm trong file local để xác định entityClass, tableName và idClass liên quan.
4. Nếu cần lấy dữ liệu, dùng admin_graphql_data_fetching với một câu SELECT duy nhất.
5. Không dùng information_schema, SHOW TABLES hoặc metadata/system tables.
6. Trả lời người dùng kèm bộ lọc, khoảng thời gian và giả định đã dùng.
Prompt cho trường hợp cần viết JPQL:
Hãy dùng get_admin_entity_class_schema để lấy catalog entity admin.
Lưu schema vào .agents/admin-entity-class-schema.json, sau đó tìm entity phù hợp với nghiệp vụ người dùng hỏi.
Dựa trên entityClass tìm được, viết JPQL SELECT ngắn nhất có thể và chạy bằng admin_graphql_data_fetching với queryType = JPQL.
Không đoán entity nếu schema không có thông tin phù hợp.
Prompt cho trường hợp cần viết SQL:
Hãy kiểm tra admin entity schema bằng get_admin_entity_class_schema.
Dùng tableName trong schema để xác định bảng cần truy vấn.
Sau đó gọi admin_graphql_data_fetching với queryType = SQL.
Query phải là một SELECT duy nhất, chọn cột rõ ràng, có limit phù hợp, không dùng comment, semicolon hoặc system metadata.

Lưu Ý An Toàn

MCP endpoint admin chạy trong ngữ cảnh admin đã đăng nhập và có kiểm tra quyền. Với data fetching, hệ thống kiểm tra quyền truy cập API fetch data trước khi chạy query.
Tuy nhiên, phía AI client vẫn nên prompt chặt chẽ:
  • Không query metadata hệ thống.
  • Không tự ý chạy truy vấn rộng nếu chưa có filter.
  • Không dùng select * cho báo cáo người dùng.
  • Luôn giới hạn số dòng trả về.
  • Với ngày tương đối như “hôm nay”, “tháng này”, cần đổi sang ngày tuyệt đối trước khi trả lời.

Kết Luận

get_admin_entity_class_schema là tool nền tảng để AI hiểu mô hình entity admin mà không phải đoán schema database. Cách dùng đúng là gọi tool, lưu schema ra file local, tìm kiếm có chọn lọc, rồi mới dùng admin_graphql_data_fetching để chạy truy vấn đọc an toàn.
Thiết kế này giúp giảm token, giảm query sai, và làm cho các câu trả lời báo cáo dữ liệu admin đáng tin cậy hơn.