资源

• 1 用户交互模型
• 2 能力
• 3 协议消息
  • 3.1 列出资源
  • 3.2 读取资源
  • 3.3 资源模板
  • 3.4 列表变更通知
  • 3.5 订阅
• 4 消息流程
• 5 数据类型
  • 5.1 Resource
  • 5.2 资源内容
  • 5.3 注解
• 6 常见 URI 方案
  • 6.1 https://
  • 6.2 file://
  • 6.3 git://
  • 6.4 自定义 URI 方案
• 7 错误处理
• 8 安全注意事项

协议版本: 2025-11-25

模型上下文协议（MCP）为服务器向客户端公开资源提供了标准化方式。资源允许服务器共享为语言模型提供上下文的数据，例如文件、数据库模式或应用程序特定信息。每个资源由 URI 唯一标识。

1 用户交互模型

MCP 中的资源被设计为应用程序驱动的，主机应用程序根据其需求确定如何整合上下文。

例如，应用程序可以：

• 通过 UI 元素公开资源以进行显式选择，在树或列表视图中
• 允许用户搜索和过滤可用资源
• 根据启发式或 AI 模型的选择实现自动上下文包含

然而，实现可以通过任何适合其需求的界面模式公开资源——协议本身不强制要求任何特定的用户交互模型。

2 能力

支持资源的服务器必须声明 resources 能力：

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

该能力支持两个可选功能：

• subscribe：客户端是否可以订阅以接收单个资源变更的通知
• listChanged：服务器是否会在可用资源列表更改时发出通知

subscribe 和 listChanged 都是可选的——服务器可以不支持、支持其一或两者都支持：

{
  "capabilities": {
    "resources": {} // 两个功能都不支持
  }
}

{
  "capabilities": {
    "resources": {
      "subscribe": true // 仅支持订阅
    }
  }
}

{
  "capabilities": {
    "resources": {
      "listChanged": true // 仅支持列表变更通知
    }
  }
}

3 协议消息

3.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 Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust",
        "icons": [
          {
            "src": "https://example.com/rust-file-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

3.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}"
      }
    ]
  }
}

3.3 资源模板

资源模板允许服务器使用 URI 模板公开参数化资源。参数可以通过补全 API 自动完成。

请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream",
        "icons": [
          {
            "src": "https://example.com/folder-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ]
  }
}

3.4 列表变更通知

当可用资源列表更改时，声明了 listChanged 能力的服务器应该发送通知：

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

3.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"
  }
}

4 消息流程

5 数据类型

5.1 Resource

资源定义包括：

• uri：资源的唯一标识符
• name：资源的名称
• title：可选的用于显示目的的人类可读资源名称
• description：可选描述
• mimeType：可选 MIME 类型
• size：可选的字节大小

5.2 资源内容

资源可以包含文本或二进制数据：

5.2.1 文本内容

{
  "uri": "file:///example.txt",
  "mimeType": "text/plain",
  "text": "Resource content"
}

5.2.2 二进制内容

{
  "uri": "file:///example.png",
  "mimeType": "image/png",
  "blob": "base64-encoded-data"
}

5.3 注解

资源、资源模板和内容块支持可选注解，这些注解向客户端提供关于如何使用或显示资源的提示：

• audience：一个数组，指示此资源的预期受众。有效值为 "user" 和 "assistant"。例如，["user", "assistant"] 表示对两者都有用的内容。
• priority：一个从 0.0 到 1.0 的数字，表示此资源的重要性。值为 1 表示"最重要"（实际上是必需的），而 0 表示"最不重要"（完全可选）。
• lastModified：一个 ISO 8601 格式的时间戳，表示资源最后修改的时间（例如 "2025-01-12T15:00:58Z"）。

带有注解的资源示例：

{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "title": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

客户端可以使用这些注解来：

• 根据预期受众过滤资源
• 优先考虑在上下文中包含哪些资源
• 显示修改时间或按新近程度排序

6 常见 URI 方案

协议定义了几种标准 URI 方案。此列表并不详尽——实现始终可以使用额外的自定义 URI 方案。

6.1 https://

用于表示网络上可用的资源。

服务器应该仅在客户端能够自行从网络上直接获取和加载资源时使用此方案——即它不需要通过 MCP 服务器读取资源。

对于其他用例，服务器应该优先使用另一个 URI 方案，或定义一个自定义方案，即使服务器本身将通过互联网下载资源内容。

6.2 file://

用于标识行为类似于文件系统的资源。但是，资源不需要映射到实际的物理文件系统。

MCP 服务器可以使用 XDG MIME 类型（如 inode/directory）标识 file:// 资源，以表示没有标准 MIME 类型的非常规文件（如目录）。

6.3 git://

Git 版本控制集成。

6.4 自定义 URI 方案

自定义 URI 方案必须符合 RFC3986，并考虑上述指南。

7 错误处理

服务器应该为常见故障情况返回标准 JSON-RPC 错误：

• 资源未找到：-32002
• 内部错误：-32603

错误示例：

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

8 安全注意事项

1. 服务器必须验证所有资源 URI
2. 应该为敏感资源实施访问控制
3. 二进制数据必须正确编码
4. 应该在操作前检查资源权限