Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
用户交互模型

MCP 中的资源设计为 应用驱动 的，由宿主应用程序根据其需求决定如何整合上下文。 例如，应用程序可以：
  • 通过 UI 元素（如树形视图或列表视图）暴露资源以供显式选择
  • 允许用户搜索和过滤可用资源
  • 基于启发式方法或 AI 模型的选择实现自动上下文包含
资源上下文选择器示例 然而，实现可以通过任何适合其需求的界面模式暴露资源—协议本身并不强制任何特定的用户交互模型。

​
能力

支持资源的服务器 必须 声明 resources 能力： 
{
  "capabilities": {
    "resources": {
      "listChanged": true
    }
  }
}
此能力支持一个可选特性：
  • listChanged：服务器在可用资源列表发生变化时是否会发送通知。
listChanged 是可选的—服务器可以省略它： 
{
  "capabilities": {
    "resources": {}
  }
}
声明了 resources 能力的服务器 必须 对 resources/list 请求返回当前对请求客户端可用的资源集合。该集合 可以 为空，并且 可以 随时间变化（参见 列表变更通知），但 不得 因连接而异，也不得因为连接上的其他请求而副作用式地变化。该集合 可以 根据请求中提供的授权而变化——例如，仅返回调用方已获授权范围所允许的资源——因为凭据是每个请求的输入，而不是连接状态。

​
协议消息

​
列出资源

要发现可用资源，客户端发送 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",
        "title": "Rust 软件应用程序主文件",
        "description": "主要应用程序入口点",
        "mimeType": "text/x-rust",
        "icons": [
          {
            "src": "https://example.com/rust-file-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ],
    "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}"
      }
    ]
  }
}
服务器 可以 在单个 resources/read 请求的响应中返回多个资源内容。例如，当读取目录资源时，服务器可以返回多个文件的内容。 服务器 也可以 对 resources/read 返回一个 InputRequiredResult，以表明在读取资源之前需要额外输入。这遵循 多轮往返请求 机制。在重试请求时，客户端会在请求参数中包含 inputResponses，以及（如果服务器提供了）requestState。 或者，如果 uri 的 scheme 是 https://，客户端可以直接从 Web 获取该资源。有关更多信息，请参见 常见 URI 方案部分。

​
资源模板

资源模板允许服务器使用 URI 模板 暴露参数化资源。参数可以通过 补全 API 自动补全。此操作支持 分页。 请求： 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}
响应： 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 项目文件",
        "description": "访问项目目录中的文件",
        "mimeType": "application/octet-stream",
        "icons": [
          {
            "src": "https://example.com/folder-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

​
列表变更通知

当可用资源列表变更时，声明了 listChanged 能力的服务器 应该 发送通知： 
{
  "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 关联以及取消）请参见 Subscriptions。

​
消息流

​
数据类型

​
资源

资源定义包括：
  • uri：资源的唯一标识符
  • name：资源的名称。
  • title：可选的资源人类可读名称，用于显示目的。
  • description：可选的描述
  • icons：可选的图标数组，用于在用户界面中显示
  • mimeType：可选的 MIME 类型
  • size：可选的大小（字节）

​
资源内容

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

​
文本内容

{
  "uri": "file:///example.txt",
  "mimeType": "text/plain",
  "text": "资源内容"
}

​
二进制内容

{
  "uri": "file:///example.png",
  "mimeType": "image/png",
  "blob": "base64 编码的数据"
}

​
注解

资源、资源模板和内容块支持可选的注解，这些注解向客户端提供关于如何使用或显示资源的提示：
  • 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": "项目文档",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}
客户端可以使用这些注解来：
  • 根据目标受众过滤资源
  • 优先确定哪些资源包含在上下文中
  • 显示修改时间或按最近程度排序

​
常见 URI 方案

协议定义了几种标准 URI 方案。此列表并非详尽无遗—实现始终可以自由使用额外的自定义 URI 方案。

​
https://

用于表示网络上可用的资源。 服务器 应该 仅在客户端能够自行从网络获取和加载资源时使用此方案—即，它不需要通过 MCP 服务器读取资源。 对于其他用例，服务器 应该 优先使用另一种 URI 方案，或定义自定义方案，即使服务器本身将通过互联网下载资源内容。

​
file://

用于标识行为类似文件系统的资源。但是，资源不需要映射到实际的物理文件系统。 MCP 服务器 可以 使用 XDG MIME type 标识 file:// 资源，例如 inode/directory，以表示没有标准 MIME 类型的非普通文件（如目录）。

​
git://

Git 版本控制集成。

​
自定义 URI 方案

自定义 URI 方案 必须 符合 RFC3986，同时考虑上述指导。

​
错误处理

服务器 应 为常见失败情况返回标准 JSON-RPC 错误：
  • 资源未找到：-32602（无效参数）
  • 内部错误：-32603
为向后兼容，客户端 也应 接受 -32002 作为资源未找到错误，因为较早的协议版本使用了此代码。 服务器 不得 为不存在的资源返回空的 contents 数组。空数组具有歧义——它可能表示资源存在但没有内容，也可能表示资源根本不存在。 错误示例： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32602,
    "message": "资源未找到",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

​
安全考虑

  1. 服务器 必须 验证所有资源 URI
  2. 对于敏感资源 应 实施访问控制
  3. 二进制数据 必须 被正确编码
  4. 操作前 应 检查资源权限
  5. 服务器 必须 清理文件路径以防止目录遍历攻击 当提供 file:// 资源时