規範
規範（草案）
服務器功能
資源

資源

協議版本: 草案

模型上下文協議 (MCP) 為服務器提供了向客戶端公開資源的標準化方式。資源允許服務器共享為語言模型提供上下文的數據，如文件、數據庫模式或應用程序特定信息。每個資源都由 URI 唯一標識。

用戶交互模型

MCP 中的資源設計為應用程序驅動，主機應用程序根據其需求決定如何整合上下文。

例如，應用程序可以：

  • 通過 UI 元素在樹形或列表視圖中公開資源，供明確選擇
  • 允許用戶搜索和過濾可用資源
  • 基於啟發式算法或 AI 模型的選擇實現自動上下文包含

資源上下文選擇器示例

然而，實現可以通過任何適合其需求的界面模式公開資源——協議本身不強制任何特定的用戶交互模型。

能力

支持資源的服務器必須聲明 resources 能力：

{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}

該能力支持兩個可選功能：

  • subscribe：客戶端是否可以訂閱以接收單個資源變更的通知。
  • listChanged：服務器是否會在可用資源列表變更時發出通知。

subscribe 和 listChanged 都是可選的——服務器可以都不支持、支持其中之一或都支持：

{
  "capabilities": {
    "resources": {} // 兩個功能都不支持
  }
}
{
  "capabilities": {
    "resources": {
      "subscribe": true // 僅支持訂閱
    }
  }
}
{
  "capabilities": {
    "resources": {
      "listChanged": true // 僅支持列表變更通知
    }
  }
}

協議消息

列出資源

要發現可用資源，客戶端發送 resources/list 請求。此操作支持分頁。

請求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "cursor": "可選的遊標值"
  }
}

響應：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "description": "主應用程序入口點",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "下一頁遊標"
  }
}

讀取資源

要檢索資源內容，客戶端發送 resources/read 請求：

請求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

響應：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "file:///project/src/main.rs",
        "mimeType": "text/x-rust",
        "text": "fn main() {\n    println!(\"Hello world!\");\n}"
      }
    ]
  }
}

資源模板

資源模板允許服務器使用 URI 模板 公開參數化資源。參數可以通過補全 API 自動完成。

請求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}

響應：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "項目文件",
        "description": "訪問項目目錄中的文件",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

列表變更通知

當可用資源列表發生變化時，聲明瞭 listChanged 能力的服務器應該發送通知：

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
}

訂閱

協議支持可選的資源變更訂閱。客戶端可以訂閱特定資源並在其變更時接收通知：

訂閱請求：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

更新通知：

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

消息流 

  sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: 資源發現
    Client->>Server: resources/list
    Server-->>Client: 資源列表

    Note over Client,Server: 資源訪問
    Client->>Server: resources/read
    Server-->>Client: 資源內容

    Note over Client,Server: 訂閱
    Client->>Server: resources/subscribe
    Server-->>Client: 訂閱確認

    Note over Client,Server: 更新
    Server--)Client: notifications/resources/updated
    Client->>Server: resources/read
    Server-->>Client: 更新後的內容

數據類型

資源

資源定義包括：

  • uri：資源的唯一標識符
  • name：人類可讀的名稱
  • description：可選的描述
  • mimeType：可選的 MIME 類型
  • size：可選的字節大小

資源內容

資源可以包含文本或二進制數據：

文本內容 

{
  "uri": "file:///example.txt",
  "mimeType": "text/plain",
  "text": "資源內容"
}

二進制內容 

{
  "uri": "file:///example.png",
  "mimeType": "image/png",
  "blob": "base64編碼的數據"
}

常見 URI 方案

協議定義了幾種標準 URI 方案。此列表並非詳盡無遺——實現始終可以自由使用額外的自定義 URI 方案。

https://

用於表示網絡上可用的資源。

服務器應該僅在客戶端能夠自行直接從網絡獲取和加載資源時使用此方案——也就是說，它不需要通過 MCP 服務器讀取資源。

對於其他用例，服務器應該優先使用另一個 URI 方案，或定義一個自定義方案，即使服務器本身將通過互聯網下載資源內容。

file://

用於標識行為類似文件系統的資源。然而，資源不需要映射到實際的物理文件系統。

MCP 服務器可以使用 XDG MIME 類型，如 inode/directory，標識 file:// 資源，以表示沒有標準 MIME 類型的非常規文件（如目錄）。

git://

Git 版本控制集成。

錯誤處理

服務器應該為常見故障情況返回標準 JSON-RPC 錯誤：

  • 資源未找到：-32002
  • 內部錯誤：-32603

錯誤示例：

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "資源未找到",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

安全考慮

  1. 服務器必須驗證所有資源 URI
  2. 應該為敏感資源實現訪問控制
  3. 二進制數據必須正確編碼
  4. 應該在操作前檢查資源權限
提示工具