Bỏ qua đến nội dung chính

Defining resources

📖 Nội dung bài học

Bật/Tắt/ hoặc ?

Tóm tắt

Resources trong MCP servers cho phép bạn cung cấp dữ liệu cho client, tương tự như các request handler GET trong một HTTP server thông thường. Chúng rất phù hợp cho các tình huống bạn cần lấy thông tin thay vì thực hiện hành động.

Hiểu về Resources qua Ví dụ

Giả sử bạn muốn xây dựng tính năng nhắc đến tài liệu, nơi người dùng có thể gõ @tên_tài_liệu để tham chiếu đến các tệp. Điều này đòi hỏi hai thao tác:

  • Lấy danh sách tất cả các tài liệu có sẵn (cho tính năng tự động hoàn thành)
  • Truy xuất nội dung của một tài liệu cụ thể (khi được nhắc đến)

Khi người dùng gõ @, bạn cần hiển thị các tài liệu có sẵn. Khi họ gửi một tin nhắn có nhắc đến, bạn tự động chèn nội dung tài liệu đó vào prompt gửi đến Claude.

Cách Resources Hoạt Động

Resources tuân theo mô hình request-response. Client của bạn gửi một ReadResourceRequest với một URI, và MCP server phản hồi với dữ liệu. URI hoạt động như một địa chỉ cho resource bạn muốn truy cập.

Các Loại Resources

Có hai loại resources:

  • Direct Resources: Các URI tĩnh, không thay đổi, như docs://documents
  • Templated Resources: Các URI có tham số, như docs://documents/{doc_id}

Đối với templated resources, Python SDK tự động phân tích các tham số từ URI và truyền chúng dưới dạng các đối số từ khóa cho hàm của bạn.

Triển khai Resources

Resources được định nghĩa bằng decorator @mcp.resource(). Đây là cách tạo cả hai loại:

Direct Resource (Liệt kê Tài liệu)

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

Templated Resource (Truy xuất Tài liệu)

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

MIME Types

Resources có thể trả về bất kỳ loại dữ liệu nào - chuỗi, JSON, nhị phân, v.v. Tham số mime_type cung cấp cho client một gợi ý về loại dữ liệu bạn đang trả về:

  • application/json - Dữ liệu JSON có cấu trúc
  • text/plain - Nội dung văn bản thuần túy
  • Bất kỳ loại MIME hợp lệ nào khác cho các định dạng dữ liệu khác nhau

MCP Python SDK tự động serialize các giá trị trả về của bạn. Bạn không cần phải tự chuyển đổi thành chuỗi JSON.

Kiểm tra Resources

Bạn có thể kiểm tra resources của mình bằng MCP Inspector. Chạy server của bạn với:

uv run mcp dev mcp_server.py

Sau đó kết nối với inspector trong trình duyệt của bạn. Bạn sẽ thấy:

  • Resources: Liệt kê các direct/static resources của bạn
  • Resource Templates: Hiển thị các templated resources chấp nhận tham số

Bấm vào bất kỳ resource nào để kiểm tra và xem cấu trúc phản hồi chính xác mà client của bạn sẽ nhận được.

Điểm chính

  • Resources cung cấp dữ liệu, tools thực hiện hành động
  • Sử dụng direct resources cho dữ liệu tĩnh, templated resources cho các truy vấn có tham số
  • MIME types giúp client hiểu định dạng phản hồi
  • SDK xử lý việc serialize tự động
  • Tên tham số trong URI của templated resources trở thành đối số hàm

Resources cung cấp một cách rõ ràng để cung cấp dữ liệu cho MCP clients, cho phép các tính năng như nhắc đến tài liệu, duyệt tệp hoặc bất kỳ tình huống nào bạn cần truy xuất thông tin từ server của mình.

🔁 Bài học liên quan

📚 Nguồn & ghi nhận

Bài học có hữu ích không?

Góp ý / Báo lỗiPhát hiện sai sót hoặc có ý tưởng cải thiện?