Defining resources

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

一、核心概念：文档提及 (Document Mention)

• 目标： 允许用户在消息中使用 @ 符号提及文档，系统自动获取文档内容并将其插入到发送给 Claude 的提示 (Prompt) 中。
• 功能分解：
• 自动补全 (Autocomplete)： 用户输入 @ 时，系统自动显示所有可用文档的列表。
• 内容注入： 用户提交包含提及的消息时，MCP 服务器自动获取指定文档的内容，作为上下文（Context）提前提供给 Claude。
• 优势： 不依赖 Claude 自身工具去查找文件内容，而是预先将所需上下文注入提示。

二、MCP 资源 (Resources) 的作用

• 定义： 资源是 MCP 服务器暴露给客户端（Client）的数据接口。
• 设计原则： 通常为每个独立的读取操作定义一个资源。
• 实现流程：
• 客户端（Client）通过 MCP 客户端发起资源请求。
• 请求中包含资源的 URI（统一资源标识符）。
• MCP 服务器根据 URI 运行预定义的函数，并返回结果。
• 服务器将结果封装在资源结果消息中返回给客户端。

三、资源类型区分

• 直接资源 (Direct Resource / Static Resource)：
• URI 是固定的、静态的。
• 示例：docs://documents
• 模板化资源 (Templated Resource)：
• URI 包含一个或多个参数（通配符）。
• 示例：docs://documents/{doc_id}
• 工作机制： 当请求到达时，MCP SDK 会自动解析 URI 中的参数，并将其作为关键字参数 (Keyword Argument) 传递给服务器的函数。

四、资源实现示例

• 资源一：获取所有文档 ID (List Docs)
• 类型：直接资源 (Direct Resource)。
• URI：docs://documents。
• MIME 类型：application/json (表示返回结构化 JSON 数据)。
• 返回内容：文档 ID 的列表（List of Strings）。
• 资源二：获取单个文档内容 (Fetch Doc)
• 类型：模板化资源 (Templated Resource)。
• URI：docs://documents/{doc_id}。
• MIME 类型：text/plain (表示返回纯文本内容)。
• 返回内容：指定文档的文本内容（String）。

五、关键概念总结

• URI (统一资源标识符)： 资源的地址，定义在资源配置中。
• MIME 类型： 告知客户端返回数据的格式（例如 application/json 或 text/plain）。
• 参数传递： 在模板化资源中，URI 中的通配符（如 {doc_id}）会被自动解析并作为函数参数传入。

Takeaways

• MCP资源是MCP服务器暴露给客户端的数据接口，客户端通过URI发起请求，服务器执行预定义函数并返回结果。
• 资源分为直接资源（URI固定）和模板化资源（URI包含参数）；模板化资源会解析URI中的通配符（如{doc_id}），并将其作为关键字参数传递给服务器函数。
• 文档提及功能利用MCP资源机制，系统自动获取指定文档的内容，并将其作为上下文提前注入到发送给Claude的提示中。
• URI是资源的地址，MIME类型用于告知客户端返回数据的格式（例如application/json或text/plain）。