mcp-agent 实战在 Agent 中把 MCP Resources 与 Prompts 原语作为一等上下文使用【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent本文以仓库中 examples/mcp/mcp_prompts_and_resources 示例为蓝本讲解如何用 mcp-agent 框架连接一个暴露Resources资源与Prompts提示模板的 MCP 服务器完成资源的发现、读取、提示模板的调用并把两者合并为一次调用后交给 LLM 生成总结。读完本文你将掌握list_resources()、list_prompts()、create_prompt()三个核心 API 的完整用法、底层调用链与可复制的运行步骤。MCP PrimitivesAgent 应用的标准积木MCPModel Context Protocol原语Primitives是 Agent 应用的标准构建块mcp-agent 将其中的tools工具、resources资源、prompts提示模板、roots根路径、elicitation引导式输入均纳入了完整支持。本示例聚焦其中最重要的两类Resources资源由 MCP 服务器暴露的结构化数据——文件、文档、数据集、状态接口等通过 URI 进行访问。它回答的是“Agent 能读取到什么”Prompts提示模板可从服务器列出并调用的标准化提示模板支持参数化既可作为上下文注入也可直接调用。它回答的是“Agent 能复用什么样的指令”。官方文档 docs/concepts/mcp-primitives.mdx 给出了完整的原语清单与传输方式说明本示例则同时演示了资源与提示模板两类原语在真实 Agent 中的端到端用法。示例全景服务器与客户端各司其职该示例由两个核心文件组成均在 examples/mcp/mcp_prompts_and_resources 目录下文件角色职责demo_server.pyMCP 服务器基于 FastMCP暴露若干静态资源、一个动态模板资源和一个echo提示模板main.pyAgent 客户端连接服务器、列出资源与提示、单次调用同时获取两者、交给 OpenAI 生成总结mcp_agent.config.yaml配置文件声明demo_server的启动命令与 OpenAI 模型参数mcp_agent.secrets.yaml.example密钥模板存放 OpenAI / Anthropic API Key 等敏感信息requirements.txt依赖清单以file://../../../方式链接到仓库根目录的 mcp-agent 本体整体架构如下┌───────────────────────┐ │ demo_server │ │ MCP Server │ │ (resources, prompts) │ └───────────┬───────────┘ │ stdio 连接 ▼ ┌───────────────────────┐ │ Agent (Python) │ │ LLM (OpenAI) │ └───────────┬───────────┘ │ ▼ [User / Developer]一、服务器端用 FastMCP 装饰器暴露资源与提示先来看 demo_server.py。它通过mcp.server.fastmcp.FastMCP创建服务器并使用mcp.resource与mcp.prompt两个装饰器完成原语的声明静态资源文档与用户数据mcp.resource(demo://docs/readme) def get_readme(): Provide the README file content. meta STATIC_RESOURCES[demo://docs/readme] return meta[content] mcp.resource(demo://data/users) def get_users(): Provide user data. meta STATIC_RESOURCES[demo://data/users] return meta[content]对应的资源元数据存放在模块级字典STATIC_RESOURCES中包含name、description、content_type、content四个字段demo://docs/readmeMarkdown 格式的示例 READMEcontent_type: text/markdowndemo://data/usersJSON 格式的用户数据content_type: application/json内容为 Alice、Bob、Charlie 三条用户记录。装饰器的 URI 即资源在 MCP 协议层面对外暴露的地址Agent 客户端正是通过该 URI 定位并读取资源的。动态模板资源一次定义多城市复用除了静态资源示例还演示了带路径参数的动态模板资源mcp.resource(demo://{city}/weather) def get_weather(city: str) - str: Provide a simple weather report for a given city. return fIt is sunny in {city} today!这里 URI 中的{city}是模板占位符函数参数city: str会由 FastMCP 自动填充。也就是说任意函数都可以暴露为资源——静态的或动态的。这类模板资源在真实场景中非常适合对接“按参数查询”的数据源例如按股票代码查行情、按用户 ID 查档案。提示模板参数化的 echomcp.prompt() def echo(message: str) - str: Echo the provided message. This is a simple prompt that echoes back the input message. return fPrompt: {message}echo是一个最简提示模板接收message参数并返回带Prompt:前缀的文本。它演示了提示模板的通用形态——函数签名即参数声明返回值即模板渲染结果。说明原 README 中提到示例还包含demo://config/settings与demo://status/health两个资源实际仓库中的 demo_server.py 以 readme、users、weather 三个资源为准本文以真实源码为准进行讲解。二、客户端三步走完成原语消费main.py 是消费端主程序完整流程为初始化应用 → 创建 Agent → 列出原语 → 单次调用取回资源与提示 → 交给 LLM 总结。1. 初始化 MCPApp 并创建 Agentfrom mcp_agent.app import MCPApp from mcp_agent.config import Settings, LoggerSettings, MCPSettings, MCPServerSettings, OpenAISettings from mcp_agent.agents.agent import Agent app MCPApp(namemcp_basic_agent) async def example_usage(): async with app.run() as agent_app: agent Agent( nameagent, instructionDemo agent for MCP resource and prompt primitives, server_names[demo_server], )配置有两条路径编程式注入在Settings(...)中直接声明如 main.py 中通过execution_engineasyncio、MCPSettings(servers{demo_server: ...})、OpenAISettings(default_modelgpt-4o-mini)完成或配置文件加载从mcp_agent.config.yaml/mcp_agent.secrets.yaml读取。server_names[demo_server]把 Agent 与配置文件里声明的 MCP 服务器绑定。2. 列出资源与提示# List all resources from demo_server server resources await agent.list_resources(demo_server) logger.info(Resources available from demo_server:, dataresources.model_dump()) # List all prompts from demo_server server prompts await agent.list_prompts(demo_server) logger.info(Prompts available from demo_server:, dataprompts.model_dump())list_resources()与list_prompts()返回标准的 MCP 结果对象ListResourcesResult/ListPromptsResult可用model_dump()序列化为 JSON 便于日志输出与调试。当传入server_name时结果限定在该服务器范围内。3. 单次调用同时取回资源与提示combined_messages await agent.create_prompt( prompt_nameecho, arguments{message: My name is John Doe.}, resource_urisdemo://docs/readme, server_names[demo_server], )create_prompt()是示例的核心亮点一次调用同时完成“调用提示模板”与“读取资源”返回一个list[PromptMessage]。参数语义如下参数类型含义prompt_namestr \| None要调用的提示模板名称argumentsdict[str, str] \| None提示模板参数仅与prompt_name搭配使用resource_urislist \| str \| AnyUrl \| None要读取的资源 URI可传单个 URI 或 URI 列表server_nameslist[str] \| None跨服务器搜索的范围为None时搜索 Agent 可访问的全部服务器4. 把内容交给 LLM 生成总结llm await agent.attach_llm(OpenAIAugmentedLLM) res await llm.generate_str( [ Summarise what are my prompts and resources?, *combined_messages, ] ) logger.info(fSummary: {res})通过attach_llm(OpenAIAugmentedLLM)挂载增强型 LLM把create_prompt()返回的消息列表展开拼接在指令之后作为上下文LLM 即可基于真实的资源与提示内容生成总结——这正是“把 MCP 原语作为一等上下文”的核心用法。三、运行示例从克隆到出结果环境准备与启动在仓库根目录下进入示例目录cd examples/mcp/mcp_prompts_and_resources uv run main.pyuv run会根据 requirements.txt 自动解析依赖。注意该文件通过mcp-agent file://../../../链接到仓库根目录的本地 mcp-agent 项目因此在本地仓库克隆目录内运行即可直接复用当前源码无需单独安装发布版。运行前请把 mcp_agent.secrets.yaml.example 复制为mcp_agent.secrets.yaml并填入真实的openai.api_key该文件应加入.gitignore。示例使用的模型为gpt-4o-mini见 mcp_agent.config.yaml。预期输出正常运行时日志会依次展示Agent 连接到demo_server列出可用资源README、用户数据等与提示模板echo单次调用同时取回 README 资源与echo提示内容LLM 基于上述内容输出总结脚本最终打印Total run time: x.xx s。四、配置详解mcp_agent.config.yamlexamples/mcp/mcp_prompts_and_resources/mcp_agent.config.yaml 展示了服务端声明方式$schema: ../../../schema/mcp-agent.config.schema.json execution_engine: asyncio logger: transports: [console, file] level: debug progress_display: true mcp: servers: demo_server: command: uv args: [run, demo_server.py] description: Demo MCP server for resources and prompts openai: default_model: gpt-4o-mini要点解读$schema指向仓库根目录的 schema/mcp-agent.config.schema.json编辑器可据此获得配置补全与校验mcp.servers.demo_server声明 MCP 服务器commandargs以子进程方式启动默认 stdio 传输。注意 main.py 编程式配置里用的是uvx run demo_server.py而 YAML 里用的是uv run demo_server.py两者都是合法的启动方式选择其一保持一致即可openai.default_modelLLM 默认模型注释中还保留了o3-mini作为备选说明API Key 分离密钥统一放mcp_agent.secrets.yaml避免入库泄露。框架官方文档 docs/concepts/mcp-primitives.mdx 还展示了transport字段支持stdio默认、sse、websocket、streamable_http四种传输方式本示例默认使用 stdio 本地子进程模式无需网络端口。五、源码纵深这些 API 在 mcp-agent 内部如何工作结合 src/mcp_agent/agents/agent.py 的源码可以看清三个核心方法的底层机制create_prompt()的组合语义agent.py#L775-L866 定义了create_prompt()的关键行为参数二选一约束prompt_name与resource_uris至少提供其一否则抛出ValueError(Must specify at least one of prompt_name or resource_uris)合并顺序同时提供时提示模板消息在前、资源消息在后messages.extend的顺序多服务器容错server_names为空时默认搜索self.server_names下全部服务器单个服务器读取失败会被try/except捕获并继续尝试下一个服务器全部失败才抛出ValueError资源消息包装read_resource()返回的每个content都会被包装成roleuser的PromptMessage其内容类型为EmbeddedResource(typeresource, resourcecontent)——这正是 MCP 协议中内嵌资源的标准消息形态保证 LLM 能将其识别为结构化资源而非纯文本。列取原语的执行链路list_resources()与list_prompts()agent.py#L724-L747、agent.py#L868均遵循相同的模式先检查self.initialized并按需初始化随后在 trace span 中通过context.executor执行list_resources_task/list_prompts_task任务。这意味着这些调用天然融入框架的 tracing 体系——list_prompts在启用追踪时还会把提示名、描述、参数声明写入 span 属性便于可观测性排查。多服务器聚合与命名空间真正执行协议请求的是 src/mcp_agent/mcp/mcp_aggregator.py。以 mcp_aggregator.py#L958-L1009 的list_prompts为例当server_name传入时从_server_to_prompt_map取该服务器的提示列表不传时则合并_namespaced_prompt_map中全部服务器的结果且资源/提示会被按服务器名做点号命名空间重命名如server.prompt_name。因此在一个 Agent 挂载多个 MCP 服务器时跨服务器的同名资源或提示也能被唯一区分。一致性检验结合测试目录可以发现框架为 MCP 聚合器维护了专门的并发与生命周期测试见 tests/mcp/test_mcp_aggregator.py、tests/mcp/test_connection_manager_concurrency.py说明list_resources/read_resource/list_prompts这类聚合读取在多服务器、多连接场景下是被框架核心保障的稳定路径。六、扩展把自有数据快速变成 MCP 原语扩展该示例只需在 demo_server.py 中追加装饰器函数即可任意函数都可以暴露为静态或动态资源也可以暴露为提示模板# 新增一个静态资源 mcp.resource(demo://config/settings) def get_settings(): Provide configuration settings. return {theme: dark, language: zh-CN} # 新增一个提示模板 mcp.prompt() def reviewer(scope: str) - str: 生成代码评审提示 return fYou are a senior reviewer. Focus on: {scope}对于生产级服务器mcp.run()之前还可以注册鉴权、采样处理器等能力更多服务器形态SSE、WebSocket、Streamable HTTP、Agent 作为 MCP 服务器等可参考 docs/mcp/overview.mdx 与 examples/mcp 下的其他子目录。小结通过本示例可以确认mcp-agent 把 MCP 的 Resources 与 Prompts 上升为 Agent 的“一等上下文”服务器端用mcp.resource与mcp.prompt装饰器即可声明资源与提示模板支持静态、动态模板与参数化三种形态客户端用list_resources()/list_prompts()发现原语用create_prompt()在一次调用中完成“提示 资源”的组合取回直接拼入 LLM 消息序列底层实现agent.py 与 mcp_aggregator.py提供了多服务器聚合、点号命名空间、容错搜索与 tracing 支持确保原语消费在真实多服务器场景下依然可靠。这套“发现 → 组合取回 → 注入上下文”的模式是构建需要文档、配置、实时数据等结构化上下文参与推理的 Agent 应用如 RAG 增强、数据简报、运维诊断的直接样板。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考