加载中
加载中

MCP 服务器中的资源允许您向客户端公开数据,类似于典型 HTTP 服务器中的 GET 请求处理程序。它们非常适合需要获取信息而非执行操作的场景。

通过示例理解资源

假设您想构建一个文档提及功能,用户可以输入 @document_name 来引用文件。这需要两个操作:

  • 获取所有可用文档的列表(用于自动补全)
  • 获取特定文档的内容(当被提及时)

在聊天提示中输入"@"会打开一个文档列表,例如 deposition.md 和 spec.md,每个都标记为"Resource"。

当用户输入 @ 时,您需要显示可用的文档。当他们提交带有提及的消息时,您会自动将该文档的内容注入发送给 Claude 的提示中。

输入 at 符号会列出诸如 design.md 之类的文档,每个都标记为"Resource",而提及会注入 report.pdf 的内容。

资源的工作原理

资源遵循请求-响应模式。您的客户端发送带有 URI 的 ReadResourceRequest,MCP 服务器以数据作为响应。URI 的作用就像是您要访问的资源的地址。

一个 MCP 服务器包含两个资源定义(list_docs 和 fetch_doc)的示意图,如下方代码所示。

资源的类型

资源有两种类型:

直接资源的装饰器代码,其 URI 中没有参数;以及带有 doc_id 的模板化资源,描述见下文。

  • 直接资源: 不会变化的静态 URI,例如 docs://documents
  • 模板化资源: 带有参数的 URI,例如 docs://documents/{doc_id}

对于模板化资源,Python SDK 会自动从 URI 中解析参数,并将其作为关键字参数传递给您的函数。

实现资源

资源使用 @mcp.resource() 装饰器定义。以下是创建这两种类型的方法:

直接资源(列出文档)

python
@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

模板化资源(获取文档)

python
@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

MIME 类型

资源可以返回任何类型的数据——字符串、JSON、二进制等。mime_type 参数为客户端提供关于您所返回数据类型的提示:

  • application/json - 结构化 JSON 数据
  • text/plain - 纯文本内容
  • 任何其他适用于不同数据格式的有效 MIME 类型

MCP Python SDK 会自动序列化您的返回值。您无需手动将其转换为 JSON 字符串。

测试资源

您可以使用 MCP Inspector 测试您的资源。通过以下命令运行您的服务器:

bash
uv run mcp dev mcp_server.py

然后在浏览器中连接到 Inspector。您将看到:

MCP Inspector 的 Resources 选项卡,在 Resources 下列出了 docs://documents,而 Resource Templates 下没有任何内容。

  • Resources: 列出您的直接/静态资源
  • Resource Templates: 显示接受参数的模板化资源

点击任意资源以测试它,并查看您的客户端将收到的确切响应结构。

MCP Inspector 的 Resources 选项卡:读取 docs://documents 返回一个包含文件名(如 deposition.md 和 plan.md)的 JSON 列表。

要点

  • 资源用于公开数据,工具用于执行操作
  • 对静态数据使用直接资源,对参数化查询使用模板化资源
  • MIME 类型帮助客户端理解响应格式
  • SDK 会自动处理序列化
  • 模板化 URI 中的参数名称会成为函数参数

资源提供了一种简洁的方式,使数据能够提供给 MCP 客户端使用,从而实现文档提及、文件浏览等功能,或任何需要从服务器获取信息的场景。