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

Defining resources

📖 Nội dung bài học

Gia đình phông chữ

Tóm tắt

Tài nguyên trong máy chủ MCP cho phép bạn cung cấp dữ liệu cho client, tương tự như trình xử lý yêu cầu GET trong một máy chủ HTTP thông thường. Chúng hoàn hảo cho các tình huống bạn cần lấy thông tin thay vì thực hiện các hành động.

Tìm hiểu về Tài nguyên thông qua một Ví dụ

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

  • Lấy danh sách tất cả các tài liệu có sẵn (để tự động hoàn thành)
  • Lấy nội dung của một tài liệu cụ thể (khi được đề cập)

Khi người dùng đề cập đến một tài liệu, hệ thống của bạn tự động chèn nội dung của tài liệu vào prompt được gửi đến Claude, loại bỏ nhu cầu Claude dùng tool để lấy thông tin.

Cách hoạt động của Tài nguyên

Tài nguyên tuân theo mẫu yêu cầu-phản hồi. Khi client của bạn cần dữ liệu, nó sẽ gửi ReadResourceRequest với URI để xác định tài nguyên nào nó muốn. Máy chủ MCP xử lý yêu cầu này và trả về dữ liệu trong ReadResourceResult.

Luồng hoạt động như sau: code của bạn yêu cầu một tài nguyên từ client MCP, client này chuyển tiếp yêu cầu đến máy chủ MCP. Máy chủ xử lý URI, chạy hàm thích hợp và trả về kết quả.

Các loại Tài nguyên

Có hai loại tài nguyên:

Tài nguyên Trực tiếp

Tài nguyên trực tiếp có URI tĩnh, không bao giờ thay đổi. Chúng hoàn hảo cho các thao tác không cần tham số.

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

Tài nguyên Mẫu

Tài nguyên mẫu bao gồm các tham số trong URI của chúng. SDK Python tự động phân tích cú pháp các tham số này và chuyển chúng dưới dạng đối số từ khóa cho hàm của bạn.

@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]

Chi tiết Triển khai

Tài nguyên có thể trả về bất kỳ loại dữ liệu nào - chuỗi, JSON, dữ liệu nhị phân, v.v. Dùng tham số mime_type để cho client biết loại dữ liệu bạn đang trả về:

  • "application/json" cho dữ liệu có cấu trúc
  • "text/plain" cho văn bản thuần túy
  • "application/pdf" cho các tệp nhị phân

SDK Python MCP tự động tuần tự hóa các giá trị trả về của bạn. Bạn không cần phải tự chuyển đổi các đối tượng thành chuỗi JSON - chỉ cần trả về cấu trúc dữ liệu và để SDK xử lý việc tuần tự hóa.

Kiểm tra Tài nguyên của bạn

Bạn có thể kiểm tra tài nguyên bằng cách dùng MCP Inspector. Khởi động máy chủ của bạn bằng:

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 hai phần:

  • Resources - Liệt kê các tài nguyên trực tiếp/tĩnh của bạn
  • Resource Templates - Liệt kê các tài nguyên mẫu của bạn

Bấm vào bất kỳ tài nguyên nào để kiểm tra nó. Đối với tài nguyên mẫu, bạn sẽ cần cung cấp các giá trị cho các tham số. Inspector hiển thị cho bạn cấu trúc phản hồi chính xác mà client của bạn sẽ nhận được, bao gồm loại MIME và dữ liệu được tuần tự hóa.

Tài nguyên cung cấp một cách rõ ràng để cung cấp dữ liệu chỉ đọc từ máy chủ MCP của bạn, giúp client dễ dàng lấy thông tin mà không cần sự phức tạp của tool calls.

🔁 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?