MCP 资源系统 (Resources)

Resources 是 MCP 服务器提供的一类被动数据源，允许 AI 模型以标准化的方式请求外部数据内容。

1. 资源的核心价值

与主动动作（Tools）不同，资源主要作为**背景知识（Context）**存在。它们的标识形式是通用的 URI (Uniform Resource Identifier)。

常见的资源类型：

• 文件内容：项目源代码、文档。
• 动态日志：正在生成的服务日志流。
• 数据库查询结果：特定的记录集。
• 系统信息：环境变量、运行中进程。

---

2. 资源定义规范

资源的元信息包括 URI、资源名称、描述以及 MIME 类型（告知宿主如何渲染这些数据）。

{
  "uri": "db:///project/v1/users/123",
  "name": "用户档案: 张三",
  "description": "包含用户的姓名、邮箱及订阅记录的详细 JSON 档案",
  "mimeType": "application/json"
}

MIME 类型的作用

• text/markdown: 宿主会按富文本解析，适合 LLM 阅读。
• image/png: 宿主会渲染为预览图。
• application/json: 宿主会按结构化数据处理。

---

3. 动态资源：URI Templates

当资源数量巨大或根据参数动态生成时（如搜索结果），服务器可以公开 URI 模板。

{
  "uriTemplate": "file:///github/repos/{owner}/{repo}/readme",
  "name": "GitHub 仓库 Readme",
  "description": "动态根据仓库主和仓库名获取 readme 文档",
  "mimeType": "text/markdown"
}

宿主（或模型）会根据具体的参数值（如 owner=google, repo=mcp）构建出唯一的资源 URI： file:///github/repos/google/mcp/readme

---

4. 实时更新：订阅机制 (Subscription)

MCP 支持推送通知。如果某个资源内容是频繁变动的（如生产日志），客户端可以发起订阅。

1. 订阅请求：resources/subscribe { uri: "..." }
2. 变更通知：当服务器发现内容变更，主动发送：

   {
     "jsonrpc": "2.0",
     "method": "notifications/resources/updated",
     "params": { "uri": "..." }
   }

3. 拉取新内容：收到通知后，宿主会重新执行 resources/read。

---

5. 分页查询 (Pagination)

当 resources/list 返回的结果集非常庞大时，服务器应启用分页：

// 服务器响应：
{
  "resources": [ ... 此页内容 ... ],
  "nextCursor": "page-2-token"
}

// 客户端下一次请求将携带 cursor：
{
  "method": "resources/list",
  "params": { "cursor": "page-2-token" }
}

---

6. 二进制资源处理

二进制资源（如图片、音频）的内容不使用 text 字段，而是使用 blob 字段（Base64 编码）。

{
  "contents": [{
    "uri": "file:///project/logo.png",
    "mimeType": "image/png",
    "blob": "iVBORw0KGgoAAA..." // Base64 字符串
  }]
}

小结

• ✅ URI 是唯一路径：所有交互均围绕 URI 展开。
• ✅ 资源是只读的：如需修改操作，请使用工具。
• ✅ 模板与分页提供扩展性：支持处理无限量的数据源。

练习

1. 定义一个包含 {log_level} 参数的动态搜索资源模板。
2. 实现一个模拟订阅逻辑：当计数器加 1 时，向宿主发送资源更新通知。