加载中
加载中

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

理解资源

可以将资源视为只读端点,它可以返回任何类型的数据——字符串、JSON、二进制文件等。您需要设置一个 'mime_type',以便向客户端提示您返回的数据类型。

展示持有两个资源的 MCP 服务器示意图:直接的 list_docs 和带模板的 fetch_doc,如下方代码所示。

资源通过 URI(本质上是地址)来公开数据。当客户端需要数据时,它会发送一个带有特定 URI 的 ReadResourceRequest,您的服务器会以请求的信息作为响应。

两种资源类型

您可以创建两种主要类型的资源:

  • 直接资源(Direct Resources) - 具有不包含任何参数的静态 URI(如 docs://documents)
  • 模板化资源(Templated Resources) - 在其 URI 中包含参数(如 docs://documents/{doc_id})

直接资源(无 URI 参数)与模板化资源(其 URI 参数由 Python SDK 传递给您的函数)对比图。

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

实现资源

使用 @mcp.resource() 装饰器可以轻松创建资源。以下是这两种类型的实现方式:

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

@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]

MCP Python SDK 会自动序列化您返回的任何内容。您无需手动将数据转换为 JSON 字符串——只需返回相应的 Python 数据结构即可。

测试您的资源

您可以使用 MCP Inspector 工具来测试资源。通过 uv run mcp dev mcp_server.py 启动您的服务器,然后进入网页界面。

MCP Inspector 的 Resources 标签页:docs://documents 资源、fetch_doc 模板,以及列出六个文档的 JSON 响应。

检查器会将直接资源与模板化资源分开显示。直接资源会出现在主要的"Resources"部分,而模板化资源则会显示在"Resource Templates"下。您可以点击任意资源进行测试,查看服务器返回的确切响应结构。

实际应用场景

资源非常适合以下场景:

  • 提供自动补全数据(如文档列表)
  • 获取文件内容或数据库记录
  • 公开配置数据
  • 提供客户端所需的任何只读信息

资源的关键优势在于,它允许客户端主动获取数据,而无需依赖工具或复杂的交互。这使得它们非常适合诸如文档提及(document mentions)之类的功能,在这种功能中,您希望根据用户的引用自动将内容注入到提示中。