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

Defining resources

📖 Nội dung bài học

Tóm tắt

Resources trong MCP servers cho phép bạn expose dữ liệu cho client, tương tự như GET request handlers 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 fetch thông tin thay vì thực hiện hành động.

Hiểu về Resources

Coi resources như các endpoint chỉ đọc (read-only) có thể trả về bất kỳ loại dữ liệu nào - chuỗi, JSON, file nhị phân, v.v. Bạn đặt 'mime_type' để gợi ý cho client biết loại dữ liệu bạn trả về.

Resources hoạt động bằng cách expose dữ liệu qua URIs (về cơ bản là địa chỉ). Khi client cần dữ liệu, nó gửi một ReadResourceRequest với URI cụ thể, và server của bạn phản hồi với thông tin được yêu cầu.

Hai loại Resources

Có hai loại resources chính bạn có thể tạo:

  • Direct Resources - Có URIs tĩnh, không chứa tham số (ví dụ: docs://documents)
  • Templated Resources - Chứa tham số trong URIs (ví dụ: 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 keyword arguments cho hàm của bạn. Tên tham số trong URI trở thành tên argument trong hàm của bạn.

Triển khai Resources

Việc tạo resources rất đơn giản bằng decorator @mcp.resource(). Đây là cách triển khai cả hai loại:

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

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

MCP Python SDK tự động serialize bất cứ thứ gì bạn trả về. Bạn không cần tự chuyển đổi dữ liệu thành chuỗi JSON - chỉ cần trả về cấu trúc dữ liệu Python phù hợp.

Kiểm thử Resources

Bạn có thể kiểm thử resources bằng công cụ MCP Inspector. Khởi động server của bạn với uv run mcp dev mcp_server.py và điều hướng đến giao diện web.

Inspector phân tách direct resources khỏi templated ones. Direct resources xuất hiện trong phần "Resources" chính, trong khi templated resources hiển thị dưới "Resource Templates". Bạn có thể bấm vào bất kỳ resource nào để kiểm thử và xem cấu trúc response chính xác mà server của bạn trả về.

Các trường hợp sử dụng thực tế

Resources lý tưởng cho:

  • Cung cấp dữ liệu autocomplete (như danh sách tài liệu)
  • Fetch nội dung file hoặc bản ghi database
  • Expose dữ liệu cấu hình
  • Phục vụ bất kỳ thông tin chỉ đọc nào mà client của bạn cần

Ưu điểm chính là resources cho phép client chủ động fetch dữ liệu mà không cần dựa vào tools hoặc các tương tác phức tạp. Điều này làm cho chúng trở nên hoàn hảo cho các tính năng như document mentions, nơi bạn muốn tự động chèn nội dung vào prompt dựa trên tham chiếu của người dùng.

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