AI Agent / 系统课时

提供 MCP 资源

提供 MCP 资源

本节把业务上下文通过 MCP Resource URI 暴露给客户端,让 Agent 能按资源标识读取数据,而不是把所有上下文硬编码进提示词。示例会实现一个按客户编号读取业务资料的资源,并说明资源与工具的职责边界。

学习目标

  • 使用 Resource URI 为上下文建立稳定标识
  • 用 MCPServer 注册动态资源模板并返回 JSON 文本
  • 判断什么时候应该使用资源,什么时候应该改用工具

资源解决什么问题

MCP 资源适合表达“可以读取的上下文”,例如配置文件、运行手册、数据库查询结果或业务实体快照。客户端先知道有哪些资源或资源模板,再按 URI 读取具体内容;URI 负责定位,真正的数据仍由服务端在读取时生成或加载。

MCP Resource URI 的解析与读取链路

资源 URI 应稳定、可解释,并与底层存储解耦。customer://1001 可以映射数据库、缓存或远程服务;客户端不需要知道真实表名和文件路径,因此后端可以在不改变资源契约的前提下调整实现。

注册一个动态资源

保存为 customer_server.py。服务用 customer://catalog/{customer_id} 声明模板。当客户端读取 customer://catalog/1001,SDK 从模板取出编号。示例数据为虚构记录。真实服务要在读取时依据认证身份检查该编号的访问权。

python
import json
import sys

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("customer-resources")

CUSTOMERS = {
    "1001": {"name": "Aster Labs", "tier": "pro", "status": "active"},
    "1002": {"name": "Northwind", "tier": "basic", "status": "paused"},
}

@mcp.resource("customer://catalog/{customer_id}", mime_type="application/json")
def customer_profile(customer_id: str) -> str:
    """按客户编号返回只读客户资料。"""
    customer = CUSTOMERS.get(customer_id)
    if customer is None:
        raise ValueError("customer not available")

    # 返回稳定的文本序列化结果,便于客户端作为上下文读取。
    return json.dumps(customer, ensure_ascii=False)

if __name__ == "__main__":
    # 保持 stdout 专用于 stdio 协议,普通诊断信息写入 stderr。
    print("MCP resource server ready: customer://catalog/{customer_id}", file=sys.stderr)
    mcp.run(transport="stdio")

预期输出

text
MCP resource server ready: customer://catalog/{customer_id}

这行状态信息写入标准错误,进程随后会等待 MCP 客户端连接。从同目录运行 python probe.py customer_server.py --resource customer://catalog/1001。客户端先调用资源模板列表,再读取该 URI。读取时,资源正文对应以下内容;不同 SDK 可能在协议层附加 URI、MIME 类型等元数据,但业务文本应保持一致。

json
{"name":"Aster Labs","tier":"pro","status":"active"}

这段 JSON 是资源内容的数据示例,不是要求客户端直接操作服务端内存。生产环境中可以把字典替换为数据库查询或文件读取,但资源函数仍应保持只读语义和清晰的错误处理。

设计 URI 与内容边界

资源 URI 不应直接泄露敏感物理位置,例如数据库连接串或服务器绝对路径。更稳妥的做法是使用业务命名空间,如 customer://1001、runbook://payments-timeout,由服务端负责把逻辑标识解析到真实数据源。

资源内容也不宜无限膨胀。若一个 URI 读取结果可能达到数十兆字节,应考虑拆成更细粒度的资源、增加分页式工具,或先暴露目录资源再按具体条目读取。这样既能减少上下文浪费,也便于权限控制和缓存。

验证资源是否可用

验证时至少覆盖三个点:客户端能识别资源或资源模板;读取合法 URI 能得到预期内容;不存在的标识会产生明确错误。对示例而言,customer://catalog/1001 应返回 Aster Labs 的资料,而 customer://catalog/9999 应失败,不能返回空对象掩盖数据缺失。

一个设计良好的 MCP 资源把“如何定位上下文”和“上下文存在哪里”分离开。Agent 只依赖稳定 URI 与返回内容,服务端则可以独立演进存储、权限和缓存策略。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

提供 MCP 资源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通