Trong hệ thống admin, nhiều logic nghiệp vụ không nhất thiết được gọi qua REST endpoint. Một phần trong số đó được đóng gói thành các EzyFunction: các hàm có tên, được đăng ký qua event bus, có thể được gọi từ template hoặc từ các công cụ nội bộ bằng tên function. MCP tool get_admin_ezy_function_schema được thiết kế để giúp AI lấy danh sách schema của các EzyFunction trong admin một cách tiết kiệm context và an toàn hơn.

EzyFunction Là Gì

EzyFunction là một event handler đặc biệt có tên bắt đầu bằng prefix ezy_function_. Khi hiển thị ra cho người dùng hoặc khi gọi trong template, phần prefix này được bỏ đi.
Ví dụ:
Event name nội bộ: ezy_function_get_user_summary
Tên function dùng để gọi: get_user_summary
Cách gọi trong template: ezyfunctions.call('get_user_summary')
Nói ngắn gọn, EzyFunction là cách biến một event handler thành một hàm có thể gọi lại theo tên. Nó phù hợp cho các tác vụ như lấy dữ liệu phụ trợ cho giao diện admin, xử lý logic dùng lại, hoặc expose một thao tác nhỏ mà không cần tạo REST API riêng.

Schema Có Vai Trò Gì

EzyFunction schema là bản mô tả hợp đồng dữ liệu của các function hiện có. Nó giúp AI hoặc developer biết:
  • function nào đang tồn tại,
  • function đó dùng để làm gì,
  • dữ liệu đầu vào gồm những trường nào,
  • kiểu dữ liệu và trường bắt buộc là gì,
  • dữ liệu trả về có cấu trúc ra sao,
  • có ví dụ gọi function hay không.
Schema được sinh dưới dạng JSON, theo cấu trúc tổng quát: 
{
  "get_user_summary": {
    "description": "Lấy thông tin tóm tắt của người dùng.",
    "argumentSchema": {
      "name": "argument",
      "dataType": "java.util.Map",
      "fields": []
    },
    "resultSchema": {
      "name": "result",
      "dataType": "java.util.Map"
    },
    "examples": []
  }
}
Điểm quan trọng: file schema là một object lớn, trong đó key là function name không có prefix ezy_function_, còn value là schema chi tiết của function đó.

Vì Sao Cần MCP Tool Này

Schema EzyFunction có thể rất lớn. Nếu AI đọc toàn bộ nội dung schema trực tiếp vào context, cuộc trò chuyện sẽ nhanh chóng tốn token và dễ làm loãng ngữ cảnh làm việc.
Vì vậy, MCP tool get_admin_ezy_function_schema không trả toàn bộ JSON schema ngay trong kết quả tool call. Thay vào đó, nó trả về đường dẫn tải schema và hướng dẫn lưu file vào thư mục .agents/ của project.
Cách thiết kế này giúp AI:
  • biết chính xác endpoint lấy schema,
  • tải schema về workspace khi cần phân tích,
  • tránh nhồi một file JSON lớn vào context,
  • có thể dùng các công cụ đọc file/tìm kiếm cục bộ để tra đúng function cần dùng.

Luồng Hoạt Động

sequenceDiagram
    participant User as Người dùng
    participant AI as Trợ lý AI
    participant MCP as MCP Server Admin
    participant API as Schema API
    participant Gen as Bộ sinh EzyFunction Schema

    User->>AI: Hỏi về EzyFunction schema admin
    AI->>MCP: tools/call get_admin_ezy_function_schema
    MCP-->>AI: Trả đường dẫn tải và lệnh curl
    AI->>API: Tải /graphql/api/v1/schemas/admin/ezy-function
    API->>Gen: Sinh JSON schema từ các EzyFunction đã đăng ký
    Gen-->>API: JSON schema
    API-->>AI: File admin-ezy-function-schema.json
    AI->>AI: Tìm function cần dùng trong file schema
    AI-->>User: Giải thích input/output hoặc soạn payload mẫu

Cách Gọi MCP Tool

Tool cần gọi là:
get_admin_ezy_function_schema
Tool này không cần input argument.
Khi gọi thành công, nó trả về hướng dẫn dạng text tương tự:
Admin ezy-function schema is available for download at:
/graphql/api/v1/schemas/admin/ezy-function

Save to the project's .agents/ folder instead:
curl --create-dirs -o .agents/admin-ezy-function-schema.json {adminUrl}/graphql/api/v1/schemas/admin/ezy-function
Sau khi tải xong, AI nên đọc file .agents/admin-ezy-function-schema.json theo nhu cầu, ví dụ tìm một function cụ thể thay vì đọc toàn bộ file vào câu trả lời.

Prompt Nên Dùng

Khi chỉ muốn tải schema admin:
> Hãy dùng MCP tool để lấy admin EzyFunction schema và lưu vào .agents/admin-ezy-function-schema.json. Đừng đọc toàn bộ file vào context.
Khi muốn tìm function phù hợp với một mục đích:
> Hãy lấy admin EzyFunction schema, sau đó tìm function liên quan đến việc lấy thông tin người dùng. Cho tôi biết function name, input cần truyền và output trả về.
Khi đã biết tên function:
> Trong admin EzyFunction schema, kiểm tra function get_user_summary nhận tham số gì và trả về dữ liệu gì.
Khi muốn AI soạn ví dụ gọi:
> Dựa vào admin EzyFunction schema, hãy soạn ví dụ gọi get_user_summary cho user ID 123. Chỉ dùng các trường có trong schema, không tự đoán tên field.

Lưu Ý Khi Sử Dụng

Tool này chỉ lấy schema của admin EzyFunction, khác với web EzyFunction schema. Với function admin, schema được lấy qua endpoint:
/graphql/api/v1/schemas/admin/ezy-function
MCP server admin yêu cầu phiên admin đã xác thực và tính năng AI Tools/MCP được bật. Đây không phải endpoint công khai cho client chưa đăng nhập.
Một điểm nữa cần nhớ: trong schema và khi gọi bằng ezyfunctions.call(...), dùng tên function không có prefix ezy_function_. Prefix chỉ là quy ước đăng ký event handler nội bộ.

Kết Luận

get_admin_ezy_function_schema là tool giúp AI khám phá hợp đồng dữ liệu của các EzyFunction trong admin mà không phải đoán cấu trúc input/output. Thay vì trả một JSON lớn vào context, tool hướng dẫn tải schema về .agents/admin-ezy-function-schema.json, rồi AI có thể tra cứu cục bộ theo từng function. Đây là cách dùng phù hợp khi muốn AI thao tác chính xác với các function admin: lấy schema trước, hiểu contract dữ liệu, rồi mới soạn lời gọi hoặc payload mẫu.