1. 什么是资源？ #

资源（Resources）是服务器向客户端暴露的可读数据，供语言模型作为上下文使用。每个资源由 URI 唯一标识。

协议版本：2025-11-25

2. 本章你将学到 #

• 资源的能力声明与协议消息
• 如何列出、读取资源
• 资源模板与订阅
• 数据结构、URI 方案、错误处理

3. 典型场景 #

用户打开 VS Code 中的 main.rs，连接文件系统 MCP 服务器。客户端通过 resources/list 获取文件列表，用户选择 main.rs 后，客户端调用 resources/read 获取内容，将其作为上下文发给 LLM，LLM 据此回答问题或生成代码。

4. 能力 #

服务器必须声明 resources 能力：

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

两者均为可选，可都不支持、支持其一或两者都支持。

5. 协议消息 #

5.1 列出资源（resources/list） #

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": { "cursor": "optional-cursor-value" }
}

支持分页。

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Main File",
        "description": "Primary entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

5.2 读取资源（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}"
      }
    ]
  }
}

5.3 资源模板（resources/templates/list） #

资源模板使用 URI 模板 暴露参数化资源，如 file:///{path}。参数可通过补全 API 自动补全。

5.4 列表变更通知 #

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

5.5 订阅 #

订阅：

{
  "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" }
}

6. 流程示意 #

7. 数据结构 #

7.1 资源定义 #

7.2 资源内容 #

7.3 注解 #

8. 常用 URI 方案 #

9. 错误处理 #

10. 安全要点 #