> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 资源
**协议版本**: 2025-03-26
模型上下文协议（MCP）为服务器以标准化方式向客户端暴露资源提供了机制。资源使服务器能够共享为语言模型提供上下文的数据，例如文件、数据库模式或应用特定信息。每个资源由一个[URI](https://datatracker.ietf.org/doc/html/rfc3986)唯一标识。
## 用户交互模型
MCP中的资源设计为**应用驱动**，由宿主应用根据其需求决定如何整合上下文。
例如，应用可以：
* 通过树状或列表视图中的UI元素显式选择资源
* 允许用户搜索和过滤可用资源
* 根据启发式规则或AI模型的选择自动包含上下文
然而，实现可以自由选择任何适合其需求的界面模式暴露资源——协议本身不强制任何特定的用户交互模型。
## 能力声明
支持资源的服务器**必须**声明`resources`能力：
```json theme={null}
{
"capabilities": {
"resources": {
"subscribe": true,
"listChanged": true
}
}
}
```
该能力支持两个可选功能：
* `subscribe`：客户端是否可以订阅单个资源变更通知。
* `listChanged`：当可用资源列表变更时，服务器是否发送通知。
`subscribe`和`listChanged`都是可选的——服务器可以支持两者之一、其一或都不支持：
```json theme={null}
{
"capabilities": {
"resources": {} // 不支持任何功能
}
}
```
```json theme={null}
{
"capabilities": {
"resources": {
"subscribe": true // 仅支持订阅
}
}
}
```
```json theme={null}
{
"capabilities": {
"resources": {
"listChanged": true // 仅支持列表变更通知
}
}
}
```
## 协议消息
### 列出资源
要发现可用资源，客户端发送`resources/list`请求。此操作支持[分页](/specification/2025-03-26/server/utilities/pagination)。
**请求：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/list",
"params": {
"cursor": "可选的游标值"
}
}
```
**响应：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resources": [
{
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"description": "主要应用程序入口点",
"mimeType": "text/x-rust"
}
],
"nextCursor": "下一页游标"
}
}
```
### 读取资源
要获取资源内容，客户端发送`resources/read`请求：
**请求：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "file:///project/src/main.rs"
}
}
```
**响应：**
```json theme={null}
{
"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模板](https://datatracker.ietf.org/doc/html/rfc6570)暴露参数化资源。参数可以通过[补全API](/specification/2025-03-26/server/utilities/completion)自动补全。
**请求：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/templates/list"
}
```
**响应：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resourceTemplates": [
{
"uriTemplate": "file:///{path}",
"name": "项目文件",
"description": "访问项目目录中的文件",
"mimeType": "application/octet-stream"
}
]
}
}
```
### 列表变更通知
当可用资源列表变更时，声明了`listChanged`能力的服务器**应该**发送通知：
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/resources/list_changed"
}
```
### 订阅
协议支持对资源变更的可选订阅。客户端可以订阅特定资源并在资源变更时接收通知：
**订阅请求：**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/subscribe",
"params": {
"uri": "file:///project/src/main.rs"
}
}
```
**更新通知：**
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "file:///project/src/main.rs"
}
}
```
## 消息流程
```mermaid theme={null}
sequenceDiagram
participant 客户端
participant 服务端
Note over 客户端,服务端: 资源发现
客户端->>服务端: resources/list
服务端-->>客户端: 资源列表
Note over 客户端,服务端: 资源访问
客户端->>服务端: resources/read
服务端-->>客户端: 资源内容
Note over 客户端,服务端: 订阅
客户端->>服务端: resources/subscribe
服务端-->>客户端: 订阅确认
Note over 客户端,服务端: 更新
服务端--)客户端: notifications/resources/updated
客户端->>服务端: resources/read
服务端-->>客户端: 更新内容
```
## 数据类型
### 资源
资源定义包括：
* `uri`: 资源的唯一标识
* `name`: 人类可读名称
* `description`: 可选描述
* `mimeType`: 可选MIME类型
* `size`: 可选字节大小
### 资源内容
资源可以包含文本或二进制数据：
#### 文本内容
```json theme={null}
{
"uri": "file:///example.txt",
"mimeType": "text/plain",
"text": "资源内容"
}
```
#### 二进制内容
```json theme={null}
{
"uri": "file:///example.png",
"mimeType": "image/png",
"blob": "base64编码数据"
}
```
## 常见URI方案
协议定义了几个标准的URI方案。此列表并不详尽——实现始终可以自由使用额外的自定义URI方案。
### https\://
用于表示网络上的资源。
服务器**应该**仅在客户端能够自行直接从网络上获取和加载资源时才使用此方案——即，客户端不需要通过MCP服务器读取资源。
对于其他用例，服务器**应该**优先使用其他URI方案或定义自定义方案，即使服务器本身将通过互联网下载资源内容。
### file://
用于标识行为类似于文件系统的资源。但资源不需要映射到实际的物理文件系统。
MCP服务器**可以**使用[XDG MIME类型](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14)标识`file://`资源，例如`inode/directory`，表示没有标准MIME类型的非普通文件（如目录）。
### git://
Git版本控制集成。
## 错误处理
服务器**应该**为常见失败情况返回标准JSON-RPC错误：
* 资源未找到：`-32002`
* 内部错误：`-32603`
示例错误：
```json theme={null}
{
"jsonrpc": "2.0",
"id": 5,
"error": {
"code": -32002,
"message": "资源未找到",
"data": {
"uri": "file:///nonexistent.txt"
}
}
}
```
## 安全考虑
1. 服务器**必须**验证所有资源URI
2. 对敏感资源**应该**实现访问控制
3. 二进制数据**必须**正确编码
4. 操作前**应该**检查资源权限