BytesRouter

主题

MCP 文档版本 2026-07-28 更新于 2026-10-14

Resources

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

NOTE

为简洁起见，本页的请求示例省略了 _meta 请求元数据（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientInfo 和 io.modelcontextprotocol/clientCapabilities）。每个请求 MUST（必须）包含必需的 _meta 字段；参见 _meta。

用户交互模型

MCP 中的资源被设计为应用驱动的，由宿主应用根据自身需求决定如何纳入上下文。

例如，应用可以：

  • 通过 UI 元素暴露资源以供显式选择，例如树形或列表视图
  • 允许用户搜索并筛选可用资源
  • 基于启发式规则或 AI 模型的选择，实现自动上下文纳入
Example of resource context picker

然而，实现方可以自由地通过任何适合其需求的接口模式来暴露资源——协议本身并不强制规定任何特定的用户交互模型。

能力

支持资源的服务端 MUST（必须）声明 resources 能力：

json
{
  "capabilities": {
    "resources": {
      "listChanged": true,
      "subscribe": true
    }
  }
}

该能力支持两个可选特性：

  • listChanged：服务端是否会在可用资源列表发生变化时发出通知。
  • subscribe：服务端是否支持针对通过 subscriptions/listen 使用 resourceSubscriptions 过滤器请求的资源，提供资源特定的更新通知。

服务端可以单独声明其中任一特性、同时声明两者，或都不声明。

既不支持 listChanged 也不支持 subscribe 的服务端可以省略它们：

json
{
  "capabilities": {
    "resources": {}
  }
}

声明了 resources 能力的服务端 MUST（必须）响应 resources/list 请求，返回当前可供发起请求的客户端使用的资源集合。该集合 MAY（可以）为空，且 MAY（可以）随时间变化（参见 List Changed Notification），但 MUST NOT（不得）因连接而异，也不得作为连接上其他请求的副作用而变化。该集合 MAY（可以）因请求所携带的授权而不同——例如仅返回调用方被授予的 scope 所允许的资源——因为凭证是逐请求的输入，而非连接状态。

协议消息

列举资源

为发现可用资源，客户端发送 resources/list 请求。此操作支持分页和缓存。

Request:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Response:

json
{
  "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 请求。此操作支持缓存。

Request:

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

Response:

json
{
  "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（可以）还以 InputRequiredResult 响应 resources/read，以表明在读取该资源之前需要额外输入。这遵循多轮往返请求机制。重试请求时，客户端在请求参数中包含 inputResponses，以及（若服务端提供）requestState。

或者，如果 uri 的 scheme 为 https://，客户端可以直接从 Web 获取该资源。更多信息参见 Common URI Schemes 章节。

资源模板

资源模板允许服务端使用 URI 模板 暴露参数化资源。参数可以通过 补全 API 自动补全。此操作支持 分页 和 缓存。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

响应：

json
{
  "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（应该）发送通知：

json
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
}

订阅

客户端通过发送 subscriptions/listen 请求来订阅特定资源的变更通知，并在 notifications.resourceSubscriptions 中列出资源 URI。每当被监视的资源发生变化时，服务端会在生成的流上发送 notifications/resources/updated。

json
{
  "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

数据类型

资源

资源定义包含：

  • uri：资源的唯一标识符
  • name：资源的名称。
  • title：可选的、供展示用途的资源人类可读名称。
  • description：可选描述
  • icons：可选的图标数组，用于在用户界面中展示
  • mimeType：可选 MIME 类型
  • size：可选大小（以字节为单位）

资源内容

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

文本内容

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

二进制内容

json
{
  "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"）。

带注解的资源示例：

json
{
  "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 方案

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

https://

用于表示 Web 上可用的资源。

仅当客户端能够自行直接从 Web 获取并加载资源时——也就是说，它不需要通过 MCP 服务端读取该资源——服务端 SHOULD（应该）使用此方案。

对于其他用例，服务端 SHOULD（应该）优先使用另一种 URI 方案，或定义自定义方案，即使服务端自身将通过互联网下载资源内容也是如此。

file://

用于标识行为类似文件系统的资源。但是，这些资源并不需要映射到实际的物理文件系统。

MCP 服务端 MAY（可以）使用 XDG MIME type 来标识 file:// 资源，例如 inode/directory，以表示那些没有标准 MIME 类型的非普通文件（例如目录）。

git://

Git 版本控制集成。

自定义 URI Scheme

自定义 URI scheme MUST（必须）符合 RFC3986，并考虑上述指引。

错误处理

如果请求的资源不存在，服务端 MUST（必须）返回一个 JSON-RPC 错误，错误码为 -32602（Invalid Params）。对于内部错误，服务端 SHOULD（应该）返回 -32603。

为了向后兼容，客户端 SHOULD（应该）也接受 -32002 作为资源未找到错误，因为早期协议版本使用了此错误码。

对于不存在的资源，服务端 MUST NOT（不得）返回空的 contents 数组。空数组含义不明确——它可能表示资源存在但没有内容，也可能表示资源根本不存在。

错误示例：

json
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32602,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

安全注意事项

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

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可