资源
社区译文；来源： MCP 80041ab0
模型上下文协议（MCP）为服务器向客户端暴露资源提供了标准化方式。资源允许服务器共享能够为语言模型提供上下文的数据，例如文件、数据库 schema 或应用特定信息。每个资源都由一个 URI 唯一标识。
_meta 请求元数据（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientInfo 和 io.modelcontextprotocol/clientCapabilities）。每个请求 MUST 包含必需的 _meta 字段；请参阅 _meta
。用户交互模型
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 根据请求携带的授权而变化，例如只返回调用者获授作用域允许的资源。
协议消息
列出资源
客户端通过发送 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 使用 resources/read 的 InputRequiredResult
响应，表示读取资源之前需要额外输入。此过程遵循多轮往返请求
机制。重试请求时，客户端在请求参数中包含 inputResponses，并在服务器提供了 requestState 时一并包含该字段。
此外，如果 uri 的 scheme 为 https://，客户端可以直接从 Web 获取该资源。更多信息请参阅常见 URI scheme
。
资源模板
资源模板允许服务器使用 URI 模板 暴露参数化资源。参数可以通过自动补全 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"
}订阅
客户端通过发送 subscriptions/listen（英文）
请求订阅特定资源的变更通知，并在 notifications.resourceSubscriptions 中列出资源 URI。每当受监视资源发生变化时，服务器就在生成的流上发送 notifications/resources/updated。
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"_meta": { "io.modelcontextprotocol/subscriptionId": 4 },
"uri": "file:///project/src/main.rs"
}
}完整的协议机制（确认、subscriptionId 关联和取消）请参阅订阅
。
消息流
sequenceDiagram
participant Client
participant Server
Note over Client,Server: Resource Discovery
Client->>Server: resources/list
Server-->>Client: List of resources
Note over Client,Server: Resource Template Discovery
Client->>Server: resources/templates/list
Server-->>Client: List of resource templates
Note over Client,Server: Resource Access
Client->>Server: resources/read
Server-->>Client: Resource contents
Note over Client,Server: Subscribe to changes
Client->>Server: subscriptions/listen (resourceSubscriptions)
Server--)Client: notifications/subscriptions/acknowledged
Note over Client,Server: Resource updated
Server--)Client: notifications/resources/updated
Client->>Server: resources/read
Server-->>Client: Updated contents
数据类型
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"
}注解
资源、资源模板和内容块支持可选注解，用于提示客户端如何使用或展示资源：
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"
}
}客户端可以使用这些注解：
- 根据预期受众筛选资源
- 确定要纳入上下文的资源优先级
- 展示修改时间或按最近修改时间排序
常见 URI Scheme
协议定义了几种标准 URI scheme。此列表并不穷尽所有情况，实现始终可以使用其他自定义 URI scheme。
https://
用于表示 Web 上可用的资源。
仅当客户端能够自行直接从 Web 获取并加载资源，即无需通过 MCP 服务器读取资源时，服务器才 SHOULD 使用此 scheme。
对于其他用例，即使服务器本身会通过互联网下载资源内容，也 SHOULD 优先使用其他 URI scheme，或定义自定义 scheme。
file://
用于标识行为类似文件系统的资源。不过，这些资源无需映射到实际的物理文件系统。
MCP 服务器 MAY 使用 XDG MIME 类型
（例如 inode/directory）标识 file:// 资源，以表示没有其他标准 MIME 类型的非常规文件（例如目录）。
git://
Git 版本控制集成。
自定义 URI Scheme
自定义 URI scheme 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 清理文件路径，以防止目录遍历攻击