协议版本: 2024-11-05
Model Context Protocol (MCP) 提供了一种标准化方式，让服务器能够向客户端暴露资源。资源允许服务器共享为语言模型提供上下文的数据，例如文件、数据库模式或应用特定信息。每个资源都通过一个 URI 被唯一标识。

​
用户交互模型

Resources in MCP are designed to be 应用驱动, with host applications determining how to incorporate context based on their needs. 例如，应用程序可以：
  • 通过UI元素以树状或列表视图展示资源，以便进行明确选择
  • 允许用户搜索和筛选可用资源
  • 基于启发式方法或AI模型的选择，实现自动上下文包含
Example of resource context picker 然而，实现方案可以根据自己的需求通过任意接口模式暴露资源——协议本身并不强制规定任何特定的用户交互模式。

​
能力

Servers that support resources 必须 declare the resources capability: 
{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}
该功能支持两个可选特性：
  • subscribe: 客户端是否可以订阅以接收对个别资源的变更通知。
  • listChanged: 当可用资源列表发生变化时，服务器是否会发出通知。
Both subscribe and listChanged are optional—servers can support neither, either, or both: 
{
  "capabilities": {
    "resources": {} // Neither feature supported
  }
}

{
  "capabilities": {
    "resources": {
      "subscribe": true // Only subscriptions supported
    }
  }
}

{
  "capabilities": {
    "resources": {
      "listChanged": true // Only list change notifications supported
    }
  }
}

​
协议消息

​
列出资源

要发现可用资源，客户端发送一个 resources/list 请求。这个操作 支持 pagination。 请求： 
{
  "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": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

​
读取资源

To retrieve resource contents, clients send a resources/read request: 请求： 
{
  "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模板公开参数化资源。参数可以通过 the completion API自动完成。 请求： 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}
响应： 响应： 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

​
列表变更通知

When the list of available resources changes, servers that declared the listChanged capability 应当 send a notification: 
{
  "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"
  }
}

​
消息流

​
数据类型

​
资源

资源定义包括：
  • uri: 资源的唯一标识符
  • name: 用户友好的名称
  • description: 可选说明
  • mimeType: 可选的 MIME 类型

​
资源内容

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

​
文本内容

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

​
二进制内容

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

​
通用URI方案

该协议定义了若干标准URI方案。此列表并非完整无遗——实现时始终可以自由使用额外的自定义URI方案。

​
https://

用于表示网络上可用的资源. Servers 应当 仅在客户端能够自行从网络获取并加载资源时使用此方案——即不需要通过MCP服务器读取资源。 For other use cases, servers 应当 prefer to use another URI scheme, or define a custom one, even if the server will itself be downloading resource contents over the internet.

​
文件://

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

​
git://

Git版本控制集成。

​
错误处理

Servers 应当 return standard JSON-RPC errors for common failure cases:
  • 资源未找到：-32002
  • 内部错误: -32603
示例错误： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

​
安全注意事项

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