资源 - Model Context Protocol 中文文档

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

用户交互模型

MCP 中的资源被设计为应用驱动，由宿主应用根据自身需求决定如何纳入上下文。例如，应用可以：

通过树视图或列表视图中的 UI 元素公开资源，以便用户明确选择
允许用户搜索和筛选可用资源
基于启发式规则或 AI 模型的选择，自动纳入上下文

不过，实现可以自由地通过任何适合自身需求的界面模式公开资源；协议本身并不强制规定任何特定的用户交互模型。

能力

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

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

该能力支持两个可选特性：

listChanged：服务器是否会在可用资源列表变化时发出通知。
subscribe：服务器是否支持针对通过 subscriptions/listen 并使用 resourceSubscriptions 过滤器请求的资源，发送资源特定的更新通知。

服务器可以独立公告任一特性、同时公告两者，或都不公告。既不支持 listChanged 也不支持 subscribe 的服务器可以省略它：

{
  "capabilities": {
    "resources": {}
  }
}

声明 resources 能力的服务器 MUST 响应 resources/list 请求，并返回当前对请求客户端可用的一组资源。该集合 MAY 为空，也 MAY 随时间变化（见列表变化通知），但 MUST NOT 因连接不同或连接上其他请求的副作用而变化。该集合 MAY 随请求中提供的授权而变化，例如只返回调用方已授予 scope 允许的资源，因为凭据是逐请求输入，而不是连接状态。

协议消息

列出资源

为了发现可用资源，客户端会发送 resources/list 请求。此操作支持分页和缓存。 请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "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",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

读取资源

为了检索资源内容，客户端会发送 resources/read 请求。此操作支持缓存。 请求：

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

响应：

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

服务器 MAY 在响应单个 resources/read 请求时返回多个资源内容。例如，当读取目录资源时，服务器可以返回多个文件的内容。服务器 MAY 也可以用 InputRequiredResult 响应 resources/read，表示在读取资源之前需要额外输入。这遵循多轮往返请求机制。重试请求时，客户端会在请求参数中包含 inputResponses，并在服务器提供时包含 requestState。另外，如果 uri 的 scheme 是 https://，客户端可以直接从 Web 获取资源。更多信息见常见 URI 方案章节。

资源模板

资源模板允许服务器使用 URI templates 公开参数化资源。参数可以通过补全 API自动补全。此操作支持分页和缓存。 请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "complete",
    "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"]
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

列表变化通知

当可用资源列表变化时，已声明 listChanged 能力的服务器 SHOULD 发送通知：

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

消息流

数据类型

Resource

资源定义包括：

uri：资源的唯一标识符
name：资源名称。
title：用于显示的可选人类可读资源名称。
description：可选描述
icons：用于在用户界面中显示的可选图标数组
mimeType：可选 MIME 类型
size：以字节为单位的可选大小

资源内容

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

文本内容

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

二进制内容

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

Annotations

资源、资源模板和内容块支持可选 annotations，用于向客户端提示如何使用或显示该资源：

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

带有 annotations 的资源示例：

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

客户端可以使用这些 annotations 来：

根据目标受众筛选资源
对应纳入上下文的资源进行优先级排序
显示修改时间或按新近程度排序

常见 URI 方案

协议定义了几种标准 URI 方案。此列表并不详尽；实现始终可以自由使用其他自定义 URI 方案。

https://

用于表示 Web 上可用的资源。只有当客户端能够自行直接从 Web 获取并加载资源时，服务器才 SHOULD 使用此方案；也就是说，客户端不需要通过 MCP 服务器读取该资源。对于其他用例，即使服务器本身会通过互联网下载资源内容，服务器也 SHOULD 优先使用其他 URI 方案，或定义自定义方案。

file://

用于标识行为类似文件系统的资源。不过，这些资源不需要映射到实际的物理文件系统。 MCP 服务器 MAY 使用 XDG MIME type 来标识 file:// 资源，例如使用 inode/directory 表示目录等没有其他标准 MIME 类型的非常规文件。

git://

Git 版本控制集成。

自定义 URI 方案

自定义 URI 方案 MUST 符合 RFC3986，并考虑上述指导。

错误处理

如果请求的资源不存在，服务器 MUST 返回代码为 -32602（Invalid Params）的 JSON-RPC 错误。服务器 SHOULD 对内部错误返回 -32603。为了向后兼容，客户端 SHOULD 也接受 -32002 作为资源未找到错误，因为早期协议版本使用该代码。服务器 MUST NOT 对不存在的资源返回空 contents 数组。空数组具有歧义，它可能表示资源存在但没有内容，也可能表示资源根本不存在。错误示例：

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

安全注意事项

服务器 MUST 验证所有资源 URI
对敏感资源 SHOULD 实现访问控制
二进制数据 MUST 正确编码
操作前 SHOULD 检查资源权限
服务器在提供 file:// 资源时 MUST 清理文件路径，以防止目录遍历攻击

基础协议

客户端能力

服务器能力

资源

用户交互模型

能力

协议消息

列出资源

读取资源

资源模板

列表变化通知

订阅

消息流

数据类型

Resource

资源内容

文本内容

二进制内容

Annotations

常见 URI 方案

https://

file://

git://

自定义 URI 方案

错误处理

安全注意事项

​用户交互模型

​能力

​协议消息

​列出资源

​读取资源

​资源模板

​列表变化通知

​订阅

​消息流

​数据类型

​Resource

​资源内容

​文本内容

​二进制内容

​Annotations

​常见 URI 方案

​https://

​file://

​git://

​自定义 URI 方案

​错误处理

​安全注意事项

用户交互模型

能力

协议消息

列出资源

读取资源

资源模板

列表变化通知

订阅

消息流

数据类型

Resource

资源内容

文本内容

二进制内容

Annotations

常见 URI 方案

https://

file://

git://

自定义 URI 方案

错误处理

安全注意事项