Defining resources

MCP 服务器资源 (Resources) 学习笔记

🎯 核心概念与应用场景

• 资源 (Resources) 定义: 资源是 MCP 服务器暴露给客户端的数据接口。
• 主要功能: 实现用户在消息中提及（Mention）文档的功能。
• 自动补全 (Autocomplete): 当用户输入 @ 符号时，服务器自动提供可用文档列表。
• 内容获取: 当用户提交包含提及的完整消息时，服务器自动获取指定文档的内容，并将其插入到发送给 Claude 的提示词 (Prompt) 中。
• 设计原则: 通常为每个独立的读取操作定义一个资源。

⚙️ 资源工作流程

• 客户端请求: 客户端通过 MCP 客户端向 MCP 服务器发送“读取资源请求 (Read Resource Request)”。
• URI 包含地址: 请求中必须包含资源的 URI（统一资源标识符）。
• 服务器执行: MCP 服务器根据 URI 运行预先定义的函数。
• 返回结果: 服务器将结果封装在“读取资源结果 (Read Resource Result)”消息中返回给客户端。

🧱 资源类型

• 直接资源 (Direct/Static Resource):
• URI 是固定的、静态的（例如：docs://documents）。
• 用于执行固定操作，如返回所有文档列表。
• 模板资源 (Templated Resource):
• URI 包含一个或多个参数/通配符（例如：docs://documents/{doc_id}）。
• 自动解析: Python MCP SDK 会自动解析 URI 中的参数，并将其作为关键字参数 (Keyword Argument) 传递给对应的函数。
• 用途: 用于需要根据特定输入（如文档 ID）进行定制化查询的操作。

🛠️ 关键实现细节

• MIME 类型 (MIME Type): 开发者需要定义返回数据的类型（如 application/json 或 text/plain），这为客户端提供了数据格式的提示。
• 列表资源示例 (List Docs):
• URI: docs://documents
• MIME Type: application/json
• 功能: 返回文档字典的所有键（Keys），用于自动补全。
• 内容获取资源示例 (Fetch Doc):
• URI: docs://documents/{doc_id}
• MIME Type: text/plain
• 功能: 接收 doc_id 作为关键字参数，返回该文档的实际内容。
• 错误处理: 在模板资源函数中，应检查请求的 ID 是否存在，如果不存在，应抛出错误 (raise ValueError)。

Takeaways

• 资源是MCP服务器暴露给客户端的数据接口，主要功能是实现用户在消息中的文档提及（Mention），包括自动补全和内容获取。
• 资源分为直接资源（URI固定，执行固定操作）和模板资源（URI包含参数/通配符）。
• 模板资源允许URI包含参数（如{doc_id}），Python MCP SDK 会自动解析这些参数并将其作为关键字参数传递给对应的函数。
• 资源的工作流程是：客户端发送包含URI的“读取资源请求”→ MCP服务器执行预定义函数→ 服务器返回“读取资源结果”。