1.资源概述 #

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

2.用户交互模型 #

MCP中的资源设计初衷是应用驱动，由宿主应用程序根据其需求决定如何整合上下文。

2.1 应用集成方式 #

应用程序可能：

• 通过UI元素以树形或列表视图显式展示资源以供选择
• 允许用户搜索并筛选可用资源
• 基于启发式规则或AI模型的选择，实现自动上下文包含功能

然而，具体实现可以自由选择适合其需求的任何接口模式来公开资源——协议本身并未强制规定任何特定的用户交互模型。

3.功能声明 #

支持资源的服务器必须声明resources能力：

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

3.1 可选功能特性 #

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

• subscribe - 客户端是否可以订阅以接收对单个资源变更的通知
• listChanged - 服务器是否会在可用资源列表发生变化时发出通知

两者都是可选的——服务器可以既不支持、支持其中一种，或同时支持两者：

{
  "capabilities": {
    "resources": {} // 两种功能都不支持
  }
}

{
  "capabilities": {
    "resources": {
      "subscribe": true // 仅支持订阅功能
    }
  }
}

{
  "capabilities": {
    "resources": {
      "listChanged": true // 仅支持列表变更通知
    }
  }
}

4.协议消息 #

4.1 列出资源 #

为了发现可用资源，客户端发送一个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 Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

4.2 阅读资源 #

要获取资源内容，客户端需发送一个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",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "mimeType": "text/x-rust",
        "text": "fn main() {\n    println!(\"Hello world!\");\n}"
      }
    ]
  }
}

4.3 资源模板 #

资源模板允许服务器使用参数化资源进行暴露URI模板。参数可能通过自动补全完成补全API。

请求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}

响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

4.4 列表变更通知 #

当可用资源列表发生变化时，已声明这些资源的服务器listChanged能力应该发送通知：

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

4.5 订阅 #

该协议支持对资源变更的可选订阅。客户端可以订阅特定资源，并在其变更时接收通知：

订阅请求：

{
  "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",
    "title": "Rust Software Application Main File"
  }
}

5.消息流 #

6.数据类型 #

6.1 资源 #

资源定义包含：

• uri - 资源的唯一标识符
• name - 资源的名称
• title - 用于显示目的的资源可选人类可读名称
• description - 可选描述
• mimeType - 可选的MIME类型
• size - 可选大小（以字节为单位）

6.2 资源内容 #

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

6.2.1 文本内容 #

{
  "uri": "file:///example.txt",
  "name": "example.txt",
  "title": "Example Text File",
  "mimeType": "text/plain",
  "text": "Resource content"
}

6.2.2 二进制内容 #

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

6.3 注解 #

资源、资源模板和内容块支持可选注解，这些注解向客户端提供关于如何使用或显示资源的提示。

• 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": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

客户端可以利用这些注释来：

• 根据目标受众筛选资源
• 优先确定哪些资源应纳入上下文
• 显示修改时间或按最近更新排序

7.常见URI方案 #

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

7.1 https:// #

用于表示网络上可用的资源。

服务器应该仅在客户端能够直接从网络获取并加载资源时使用此方案——即无需通过MCP服务器读取资源。

对于其他使用场景，服务器应该更倾向于使用另一种URI方案，或自定义一个方案，即使服务器自身将通过互联网下载资源内容。

7.2 file:// #

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

MCP服务器可能识别XDG MIME 类型如inode/directory，用于表示不具有标准MIME类型的非规则文件（如目录）。

7.3 git:// #

Git版本控制集成。

7.4 自定义URI方案 #

自定义URI方案必须符合RFC3986考虑到上述指导原则。

8.错误处理 #

服务器应该返回标准JSON-RPC错误以处理常见故障情况：

• 资源未找到：-32002
• 内部错误：-32603

示例错误：

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

9.安全注意事项 #

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

10.最佳实践 #

10.1 开发建议 #

1. 资源管理

   • 合理使用资源注解
   • 实施适当的访问控制
   • 优化资源加载性能

2. 用户体验

   • 提供清晰的资源描述
   • 支持资源搜索和筛选
   • 实现智能的上下文包含

3. 安全性

   • 验证所有URI输入
   • 实施权限检查机制
   • 保护敏感资源内容

10.2 实现指南 #

# 示例：MCP资源服务器基本结构

# 定义MCPResourceServer类
class MCPResourceServer:
    # 初始化方法，创建资源和订阅者的字典
    def __init__(self):
        # 存储所有资源，键为uri，值为资源内容
        self.resources = {}
        # 存储所有资源的订阅者，键为uri，值为订阅者列表
        self.subscribers = {}

    # 列出可用资源，支持可选的分页游标
    def list_resources(self, cursor=None):
        """列出可用资源"""
        # 返回所有资源的列表和下一个游标（此处为None，未实现分页）
        return {
            "resources": list(self.resources.values()),
            "nextCursor": None
        }

    # 读取指定uri的资源内容
    def read_resource(self, uri):
        """读取资源内容"""
        # 如果资源不存在，抛出资源未找到异常
        if uri not in self.resources:
            raise ResourceNotFoundError(uri)
        # 返回指定uri的资源内容
        return self.resources[uri]

    # 订阅指定uri的资源变更
    def subscribe_resource(self, uri):
        """订阅资源变更"""
        # 如果该资源还没有订阅者列表，则初始化为空列表
        if uri not in self.subscribers:
            self.subscribers[uri] = []
        # 此处可实现具体的订阅逻辑

11.常见应用场景 #

11.1 📁 文件系统集成 #

• 项目文件访问
• 文档管理系统
• 代码仓库浏览

11.2 🔗 网络资源 #

• API文档访问
• 在线资源引用
• 远程数据获取

11.3 📊 数据库资源 #

• 数据库模式信息
• 查询结果展示
• 数据字典访问

12.总结 #

MCP资源功能为AI模型提供了丰富的上下文数据访问能力。通过标准化的协议设计，服务器能够安全、高效地向客户端提供各种类型的资源，从而显著提升AI应用的实用性和用户体验。

通过合理的资源管理和安全控制，MCP资源功能为构建智能、安全的AI应用提供了坚实的基础。

参考资源：

• MCP官方文档
• RFC3986 - URI标准
• RFC6570 - URI模板
• XDG MIME类型规范