載入中
載入中

MCP 伺服器中的資源允許您向客戶端公開資料,類似於典型 HTTP 伺服器中的 GET 請求處理器。它們非常適合需要取得資訊而非執行動作的情境。

理解資源

將資源想像成唯讀端點,可以回傳任何類型的資料——字串、JSON、二進位檔案等。您需要設定一個 'mime_type',以便向客戶端提示您回傳的是哪種資料。

MCP 伺服器持有兩個資源的示意圖,直接的 list_docs 以及範本化的 fetch_doc,如下方程式碼所示。

資源透過 URI(本質上是位址)來公開資料。當客戶端需要資料時,它會發送帶有特定 URI 的 ReadResourceRequest,而您的伺服器會以所請求的資訊作為回應。

兩種資源類型

您可以建立的資源主要有兩種類型:

  • 直接資源(Direct Resources) - 具有靜態 URI,不包含任何參數(例如 docs://documents)
  • 範本化資源(Templated Resources) - 在其 URI 中包含參數(例如 docs://documents/{doc_id})

直接資源(無 URI 參數),與範本化資源(其 URI 參數由 Python SDK 傳遞給您的函式)並列。

對於範本化資源,Python SDK 會自動從 URI 中解析參數,並將其作為關鍵字參數傳遞給您的函式。URI 中的參數名稱會成為您函式中的引數名稱。

實作資源

使用 @mcp.resource() 裝飾器即可輕鬆建立資源。以下說明如何實作這兩種類型:

python
@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 會自動序列化您回傳的任何內容。您不需要手動將資料轉換為 JSON 字串——只需回傳適當的 Python 資料結構即可。

測試您的資源

您可以使用 MCP Inspector 工具測試資源。使用 uv run mcp dev mcp_server.py 啟動您的伺服器,並瀏覽至網頁介面。

MCP Inspector 的 Resources 分頁:docs://documents 資源、fetch_doc 範本,以及列出六份文件的 JSON 回應。

檢測器(inspector)將直接資源與範本化資源分開顯示。直接資源出現在主要的「Resources」區段中,而範本化資源則顯示在「Resource Templates」之下。您可以點選任何資源來測試它,並查看您的伺服器回傳的確切回應結構。

實際使用案例

資源非常適合用於:

  • 提供自動完成資料(例如文件清單)
  • 擷取檔案內容或資料庫記錄
  • 公開設定資料
  • 提供客戶端所需的任何唯讀資訊

其主要優勢在於,資源允許客戶端主動取得資料,而無需依賴工具或複雜的互動。這使得它們非常適合用於文件提及(document mentions)等功能,您希望根據使用者的參照自動將內容注入提示中。