资源
协议修订版：2025-03-26
模型上下文协议（MCP）为服务器提供了一种标准化的方式，向客户端暴露资源。资源允许服务器共享为语言模型提供上下文的数据，例如文件、数据库模式或应用程序特定信息。每个资源通过 URI 唯一标识。
用户交互模型
MCP 中的资源设计为 应用程序驱动，由宿主应用程序根据其需求决定如何融入上下文。
例如，应用程序可以：
- 通过树视图或列表视图的 UI 元素暴露资源以供明确选择
- 允许用户搜索和过滤可用资源
- 根据启发式或 AI 模型的选择实现自动上下文包含
然而，实现可以自由选择适合其需求的任何界面模式来暴露资源——协议本身不强制要求特定的用户交互模型。
能力
支持资源的服务器 必须 声明 resources 能力：
{
"capabilities": {
"resources": {
"subscribe": true,
"listChanged": true
}
}
}
该能力支持两个可选功能：
subscribe：客户端是否可以订阅以接收单个资源变更的通知。listChanged：服务器是否会在可用资源列表发生变化时发出通知。
subscribe 和 listChanged 都是可选的——服务器可以都不支持、支持其中之一或两者都支持：
{
"capabilities": {
"resources": {} // 两种功能都不支持
}
}
{
"capabilities": {
"resources": {
"subscribe": true // 仅支持订阅
}
}
}
{
"capabilities": {
"resources": {
"listChanged": true // 仅支持列表变更通知
}
}
}
协议消息
列出资源
要发现可用资源，客户端发送 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",
"description": "主要应用程序入口点",
"mimeType": "text/x-rust"
}
],
"nextCursor": "next-page-cursor"
}
}
读取资源
要检索资源内容，客户端发送 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}"
}
]
}
}
资源模板
资源模板允许服务器使用 URI 模板 暴露参数化资源。参数可以通过 补全 API 进行自动补全。
请求：
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/templates/list"
}
响应：
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resourceTemplates": [
{
"uriTemplate": "file:///{path}",
"name": "项目文件",
"description": "访问项目目录中的文件",
"mimeType": "application/octet-stream"
}
]
}
}
列表变更通知
当可用资源列表发生变化时，声明了 listChanged 能力的服务器 应该 发送通知：
{
"jsonrpc": "2.0",
"method": "notifications/resources/list_changed"
}
订阅
协议支持对资源变更的可选订阅。客户端可以订阅特定资源并在资源变更时接收通知：
订阅请求：
{
"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"
}
}
消息流程
sequenceDiagram
participant Client
participant Server
Note over Client,Server: 资源发现
Client->>Server: resources/list
Server-->>Client: 资源列表
Note over Client,Server: 资源访问
Client->>Server: resources/read
Server-->>Client: 资源内容
Note over Client,Server: 订阅
Client->>Server: resources/subscribe
Server-->>Client: 订阅确认
Note over Client,Server: 更新
Server--)Client: notifications/resources/updated
Client->>Server: resources/read
Server-->>Client: 更新后的内容
数据类型
资源
资源定义包括：
uri：资源的唯一标识符name：人类可读名称description：可选描述mimeType：可选 MIME 类型size：可选的字节大小
资源内容
资源可以包含文本或二进制数据：
文本内容
{
"uri": "file:///example.txt",
"mimeType": "text/plain",
"text": "资源内容"
}
二进制内容
{
"uri": "file:///example.png",
"mimeType": "image/png",
"blob": "base64编码的数据"
}
常用 URI 方案
协议定义了几个标准 URI 方案。此列表并非详尽无遗——实现始终可以自由使用额外的自定义 URI 方案。
https://
用于表示网络上可用的资源。
服务器 应该 仅在客户端能够直接从网络上获取和加载资源时使用此方案——即无需通过 MCP 服务器读取资源。
对于其他用例，服务器 应该 优先使用其他 URI 方案，或定义自定义方案，即使服务器本身会通过互联网下载资源内容。
file://
用于标识行为类似于文件系统的资源。然而，资源无需映射到实际的物理文件系统。
MCP 服务器 可以 使用 XDG MIME 类型（如 inode/directory）标识 file:// 资源，以表示非常规文件（如目录），这些文件通常没有标准 MIME 类型。
git://
用于 Git 版本控制集成。
错误处理
服务器 应该 为常见失败情况返回标准的 JSON-RPC 错误：
错误示例：
{
"jsonrpc": "2.0",
"id": 5,
"error": {
"code": -32002,
"message": "资源未找到",
"data": {
"uri": "file:///nonexistent.txt"
}
}
}
安全考虑
- 服务器 必须 验证所有资源 URI
- 对敏感资源 应该 实施访问控制
- 二进制数据 必须 正确编码
- 在操作前 应该 检查资源权限
