GraphQL plugin cung cấp một MCP server qua endpoint HTTP JSON-RPC để các MCP client có thể đọc tài liệu, schema hoặc hướng dẫn vận hành được expose bởi hệ thống. MCP resource trong plugin được thiết kế theo mô hình tự đăng ký: khi một resource handler được khai báo đúng quy ước, plugin sẽ tự đưa resource đó vào resources/list và cho phép đọc qua resources/read.

MCP Resources là gì

Trong MCP, resource là một đơn vị dữ liệu hoặc tài liệu mà server cho phép client đọc theo URI. Có thể hiểu resource giống như “tệp ảo” được cung cấp qua giao thức MCP: client không cần biết dữ liệu nằm trong file thật, database hay được sinh động lúc runtime; client chỉ cần gọi resources/list để xem danh sách và resources/read để đọc nội dung theo uri.

Resource phù hợp cho các nội dung mang tính tham khảo hoặc ngữ cảnh, ví dụ:

guide://mcp-tool-installation
schema://admin-view
schema://web-event
doc://project-conventions

Khác với MCP tool, resource không dùng để thực hiện một hành động nghiệp vụ. Tool phù hợp cho các thao tác có input và side effect, ví dụ tạo dữ liệu, gọi service, sinh file hoặc thực thi workflow. Resource phù hợp để đọc thông tin: hướng dẫn cài đặt, schema, tài liệu API, quy ước code, hoặc dữ liệu ngữ cảnh mà AI/client cần tham khảo trước khi làm việc.

Luồng cơ bản của MCP resource gồm hai bước:

flowchart LR
    A[MCP client] -->|resources/list| B[MCP server]
    B --> C[Danh sách resource metadata]
    A -->|resources/read với uri| B
    B --> D[Nội dung resource]

Trong GraphQL plugin, MCP resource được dùng để expose các hướng dẫn và schema theo cách chuẩn hóa, giúp MCP client hoặc AI agent có thể tự khám phá tài nguyên sẵn có trước khi gọi tool hoặc sinh mã.

Kiến trúc tổng quát

MCP server của GraphQL plugin nhận request tại:

/graphql/mcp

Endpoint này dùng JSON-RPC 2.0, yêu cầu phiên admin đã xác thực, và hỗ trợ các method MCP như:

initialize
ping
tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get
completion/complete
logging/setLevel

Resource không được khai báo bằng danh sách tĩnh. Thay vào đó, plugin quét các event handler đã đăng ký trong container và gom chúng theo hậu tố event name.

flowchart LR
    A[MCP client] --> B[POST /graphql/mcp]
    B --> C[MCP server]
    C --> D{method}
    D -->|resources/list| E[Quét resource schema handlers]
    D -->|resources/read| F[Tìm resource reader theo uri]
    E --> G[Trả danh sách resources]
    F --> H[Trả nội dung resource]

MCP Resource là gì trong GraphQL plugin

Một MCP resource gồm hai phần:

Resource schema handler

Dùng để mô tả resource cho resources/list.

Resource read handler

Dùng để trả nội dung resource cho resources/read.

Hai handler này liên kết với nhau bằng cùng một uri.

Ví dụ URI:

guide://mcp-tool-installation
guide://ezy-function-installation

Quy ước event name

GraphQL plugin nhận diện MCP resource bằng hậu tố event name.

Resource schema handler phải có event name dạng:

<resource_uri>_mcp_resource_schema_event

Resource read handler phải có event name dạng:

<resource_uri>_mcp_resource_event

Ví dụ với resource:

guide://my-custom-guide

Bạn cần có hai event name:

guide://my-custom-guide_mcp_resource_schema_event
guide://my-custom-guide_mcp_resource_event

Cài đặt resource schema handler

Resource schema handler trả metadata để MCP client hiển thị resource trong danh sách.

Metadata nên có các trường:

{
  "uri": "guide://my-custom-guide",
  "name": "my_custom_guide",
  "title": "My Custom Guide",
  "description": "Explains how to use this custom resource.",
  "mimeType": "text/plain"
}

Trong đó:

uri: định danh duy nhất của resource.

name: tên ngắn, nên dùng snake_case.

title: tiêu đề thân thiện cho người dùng.

description: mô tả resource.

mimeType: kiểu nội dung, ví dụ text/plain hoặc application/json.

Cài đặt resource read handler

Resource read handler nhận request từ resources/read và trả nội dung theo format MCP.

Ví dụ response dạng text:

{
  "contents": [
    {
      "uri": "guide://my-custom-guide",
      "mimeType": "text/plain",
      "text": "Installation steps:n1. Create handler...n2. Restart plugin..."
    }
  ]
}

Nếu resource trả JSON, có thể dùng:

{
  "contents": [
    {
      "uri": "schema://example",
      "mimeType": "application/json",
      "text": "{"type":"object"}"
    }
  ]
}

Luồng hoạt động

sequenceDiagram
    participant Client as MCP client
    participant Server as GraphQL MCP server
    participant Registry as Event handler registry
    participant Resource as Resource handler

    Client->>Server: resources/list
    Server->>Registry: Tìm *_mcp_resource_schema_event
    Registry-->>Server: Danh sách schema handlers
    Server->>Resource: handleEventData()
    Resource-->>Server: metadata
    Server-->>Client: resources[]

    Client->>Server: resources/read { uri }
    Server->>Registry: Tìm <uri>_mcp_resource_event
    Registry-->>Server: read handler
    Server->>Resource: handleEventData(params)
    Resource-->>Server: contents[]
    Server-->>Client: resource content

Kiểm thử bằng JSON-RPC

Gọi resources/list:

curl -X POST <server_base_url>/graphql/mcp \
  -H "Content-Type: application/json" \
  -H "Cookie: admin_access_token=<token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/list",
    "params": {}
  }'

Gọi resources/read:

curl -X POST <server_base_url>/graphql/mcp \
  -H "Content-Type: application/json" \
  -H "Cookie: admin_access_token=<token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "resources/read",
    "params": {
      "uri": "guide://my-custom-guide"
    }
  }'

Checklist cài đặt

Chọn một uri ổn định cho resource.
Tạo schema handler trả metadata của resource.
Đặt event name schema theo mẫu <uri>_mcp_resource_schema_event.
Tạo read handler trả contents.
Đặt event name read theo mẫu <uri>_mcp_resource_event.
Đăng ký handler vào container của plugin.
Restart plugin.
Gọi resources/list để kiểm tra resource đã xuất hiện.
Gọi resources/read với đúng uri để kiểm tra nội dung.

Lưu ý quan trọng

MCP method là phần giao thức, ví dụ resources/list và resources/read. Không nên tạo method MCP mới cho từng tài liệu nghiệp vụ.

Với nội dung ứng dụng, hãy dùng MCP resource. Với hành động có tham số và xử lý logic, hãy dùng MCP tool.

Resource URI là khóa liên kết giữa schema handler và read handler. Nếu URI lệch nhau, resource có thể xuất hiện trong danh sách nhưng không đọc được nội dung.

Endpoint MCP yêu cầu xác thực admin, vì vậy MCP client cần gửi đúng cookie hoặc access token theo cơ chế đăng nhập admin của hệ thống.

Kết luận

Để cài đặt MCP resource tương thích với GraphQL plugin, chỉ cần tuân thủ hai quy ước chính: resource schema handler dùng hậu tố _mcp_resource_schema_event, còn resource read handler dùng hậu tố _mcp_resource_event. Khi hai handler dùng cùng một uri và được đăng ký vào container, GraphQL plugin sẽ tự động expose resource qua resources/list và resources/read.

Hướng dẫn cài đặt MCP Resources tương thích với GraphQL plugin

MCP Resources là gì

Kiến trúc tổng quát

MCP Resource là gì trong GraphQL plugin

Quy ước event name

Cài đặt resource schema handler

Cài đặt resource read handler

Luồng hoạt động

Kiểm thử bằng JSON-RPC

Checklist cài đặt

Lưu ý quan trọng

Kết luận

Table Of Contents

Hướng dẫn cài đặt MCP Resources tương thích với GraphQL plugin

MCP Resources là gì

Kiến trúc tổng quát

MCP Resource là gì trong GraphQL plugin

Quy ước event name

Cài đặt resource schema handler

Cài đặt resource read handler

Luồng hoạt động

Kiểm thử bằng JSON-RPC

Checklist cài đặt

Lưu ý quan trọng

Kết luận

Table Of Contents

Sign In

Register

Forgot Password

Send Successfully