載入中
載入中

MCP 伺服器中的資源讓您可以向用戶端公開資料,類似於一般 HTTP 伺服器中的 GET 請求處理程式。它們非常適合用於需要擷取資訊而非執行動作的情境。

透過範例了解資源

假設您想要建立一個文件提及功能,使用者可以輸入 @document_name 來引用檔案。這需要兩個操作:

  • 取得所有可用文件的清單(用於自動完成)
  • 擷取特定文件的內容(被提及時)

在聊天提示中輸入「@」會開啟一份文件清單,例如 deposition.md 和 spec.md,每個都標記為「Resource」。

當使用者輸入 @ 時,您需要顯示可用的文件。當他們提交帶有提及的訊息時,您會自動將該文件的內容注入到傳送給 Claude 的提示中。

輸入 at 符號會列出文件,例如 design.md,每個都標記為「Resource」,而提及則會注入 report.pdf 的內容。

資源如何運作

資源遵循請求-回應模式。您的用戶端傳送帶有 URI 的 ReadResourceRequest,MCP 伺服器則回應資料。URI 就像是您要存取的資源的位址。

一個 MCP 伺服器包含兩個資源定義的示意圖,list_docs 和 fetch_doc,如下方程式碼所示。

資源的類型

資源有兩種類型:

直接資源(URI 中沒有參數)和範本化資源(含 doc_id)的裝飾器程式碼,如下所述。

  • 直接資源: 不會改變的靜態 URI,例如 docs://documents
  • 範本化資源: 帶有參數的 URI,例如 docs://documents/{doc_id}

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

實作資源

資源是使用 @mcp.resource() 裝飾器定義的。以下是建立這兩種類型的方法:

直接資源(列出文件)

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

範本化資源(擷取文件)

python
@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 類型

資源可以回傳任何類型的資料——字串、JSON、二進位等。mime_type 參數會向用戶端提示您回傳的資料種類:

  • application/json - 結構化 JSON 資料
  • text/plain - 純文字內容
  • 任何其他適用於不同資料格式的有效 MIME 類型

MCP Python SDK 會自動序列化您的回傳值。您不需要手動轉換為 JSON 字串。

測試資源

您可以使用 MCP Inspector 來測試您的資源。使用以下指令執行您的伺服器:

bash
uv run mcp dev mcp_server.py

然後在瀏覽器中連接到 inspector。您會看到:

MCP Inspector 的 Resources 分頁,Resources 下列出了 docs://documents,而 Resource Templates 下則沒有任何項目。

  • Resources: 列出您的直接/靜態資源
  • Resource Templates: 顯示接受參數的範本化資源

點選任何資源以測試它,並查看您的用戶端將收到的確切回應結構。

MCP Inspector 的 Resources 分頁:讀取 docs://documents 會回傳一份 JSON 檔案名稱清單,例如 deposition.md 和 plan.md。

重點整理

  • 資源公開資料,工具則執行動作
  • 靜態資料使用直接資源,參數化查詢使用範本化資源
  • MIME 類型有助於用戶端理解回應格式
  • SDK 會自動處理序列化
  • 範本化 URI 中的參數名稱會成為函式引數

資源提供了一種簡潔的方式,讓資料可供 MCP 用戶端使用,實現文件提及、檔案瀏覽等功能,或任何您需要從伺服器擷取資訊的情境。