MCP tool trong module admin được dùng để cho AI assistant hoặc developer truy xuất metadata về các Java class đang tồn tại trong admin runtime. Công dụng chính là giúp hiểu nhanh hệ thống đang dùng những entity class nào, class đó map với bảng nào, kiểu khóa chính là gì, và khi cần thì lấy schema chi tiết của từng class mà không phải mở trực tiếp mã nguồn.
Nhóm tool này đặc biệt hữu ích khi viết hoặc chỉnh GraphQL fetcher, event handler, script dữ liệu, hoặc logic admin cần tham chiếu tới entity/model class có sẵn.

Công dụng

Tool giúp trả lời các câu hỏi như:
  • Admin hiện đang scan và sử dụng những entity class nào?
  • Một entity tương ứng với table nào?
  • Entity dùng id class nào?
  • Một class cụ thể có những field nào?
  • Field/method trả về kiểu gì?
  • Class có enum values không?
  • Class có builder method hoặc builder class không?
Điểm quan trọng: schema entity có thể rất lớn, nên hệ thống không khuyến khích đọc toàn bộ nội dung vào context của AI. Thay vào đó, tool trả về URL/lệnh tải file để lưu vào thư mục .agents/, rồi AI/dev chỉ tìm kiếm phần cần dùng trong file đó.

Các tool liên quan

Có hai tool chính:
ToolMục đích
get_admin_entity_class_schemaLấy catalog các entity class admin đang dùng. Tool trả về hướng dẫn download schema về file local.
get_admin_class_schemaLấy schema chi tiết cho một hoặc nhiều Java class cụ thể.
Luồng sử dụng thường là:
flowchart TD
    A[AI hoặc developer gọi tools/list] --> B[Xem tool MCP có sẵn]
    B --> C[Gọi get_admin_entity_class_schema]
    C --> D[Tải schema entity về .agents/admin-entity-class-schema.json]
    D --> E[Tìm table/entity/id class cần dùng]
    E --> F[Gọi get_admin_class_schema với classNames]
    F --> G[Nhận field, method, enum, builder metadata]
    G --> H[Dùng thông tin để viết fetcher/event/script an toàn hơn]

Cách gọi MCP endpoint

MCP server của admin nhận JSON-RPC tại endpoint:
POST /graphql/mcp
Request phải là JSON-RPC 2.0. Ví dụ gọi danh sách tool:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
Gọi tool lấy catalog entity class:
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_admin_entity_class_schema",
    "arguments": {}
  }
}
Kết quả không trả trực tiếp schema lớn, mà trả text hướng dẫn tải file, dạng:
curl --create-dirs -o .agents/admin-entity-class-schema.json <admin-url>/graphql/api/v1/schemas/admin/entity-class
Nếu môi trường admin yêu cầu xác thực, cần gọi trong session admin hợp lệ hoặc đính kèm cookie/token admin tương ứng.

Schema entity class gồm gì?

File admin-entity-class-schema.json là một JSON array. Mỗi item mô tả một entity class được admin runtime scan thấy qua annotation @Entity.
Một item có dạng khái niệm như sau:
{
  "tableName": "example_table",
  "entityClass": "com.example.ExampleEntity",
  "idClass": "java.lang.Long"
}
Ý nghĩa:
TrườngÝ nghĩa
tableNameTên bảng lấy từ annotation @Table. Nếu class không có @Table, giá trị là chuỗi rỗng.
entityClassFully-qualified Java class name của entity.
idClassKiểu khóa chính. Ưu tiên lấy từ @IdClass; nếu không có thì lấy kiểu của field đầu tiên có @Id.
Danh sách được sort theo tableName, giúp dễ tìm theo tên bảng.

Lấy schema chi tiết của class

Sau khi đã biết class cần dùng, gọi get_admin_class_schema với danh sách classNames:
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_admin_class_schema",
    "arguments": {
      "classNames": [
        "com.example.ExampleEntity"
      ]
    }
  }
}
Tool trả về JSON schema dạng map, key là tên class, value là schema chi tiết.
Schema chi tiết có thể gồm:
TrườngÝ nghĩa
fieldsDanh sách field không static của class.
methodsDanh sách method không static, trừ getter/setter thông thường đã tương ứng với field.
enumValuesDanh sách giá trị nếu class là enum.
builderClassTên builder class nếu phát hiện được.
hasBuilderMethodtrue nếu class có public static method builder().
Field schema có thể chứa:
{
  "name": "status",
  "type": "java.lang.String",
  "description": "..."
}
Với array, collection hoặc map, schema có thêm thông tin như arrayItemType, itemType, keyType, valueType.

Khi nào dùng tool nào?

Dùng get_admin_entity_class_schema khi bạn chưa biết class nào đang tồn tại hoặc cần tìm entity theo table.
Dùng get_admin_class_schema khi bạn đã có fully-qualified class name và cần biết field/method/type để viết code gọi đúng cấu trúc dữ liệu.
Luồng khuyến nghị:
sequenceDiagram
    participant Dev as Developer/AI
    participant MCP as Admin MCP Server
    participant Runtime as Admin Runtime
    participant File as .agents Schema File

    Dev->>MCP: tools/call get_admin_entity_class_schema
    MCP-->>Dev: Trả URL/lệnh curl
    Dev->>Runtime: Download entity schema
    Runtime-->>File: Lưu admin-entity-class-schema.json
    Dev->>File: Tìm entityClass theo tableName
    Dev->>MCP: tools/call get_admin_class_schema(classNames)
    MCP-->>Dev: Trả schema chi tiết class

Lưu ý quan trọng

Không nên đọc toàn bộ admin-entity-class-schema.json vào context nếu file lớn. Hãy lưu file vào .agents/ và dùng search cục bộ để tìm class cần thiết.
get_admin_class_schema bỏ qua class không load được bằng classpath hiện tại. Vì vậy nếu truyền sai class name hoặc class không nằm trong runtime, kết quả có thể không có entry tương ứng.
Tool này chỉ mô tả metadata class. Nó không tự truy vấn database, không trả dữ liệu bản ghi, và không thay thế authorization của admin API.