[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-lastmile-ai--mcp-agent":3,"tool-lastmile-ai--mcp-agent":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160784,2,"2026-04-19T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":78,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":105,"forks":106,"last_commit_at":107,"license":108,"difficulty_score":32,"env_os":109,"env_gpu":110,"env_ram":110,"env_deps":111,"category_tags":122,"github_topics":123,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":132,"updated_at":133,"faqs":134,"releases":164},9758,"lastmile-ai\u002Fmcp-agent","mcp-agent","Build effective agents using Model Context Protocol and simple workflow patterns","mcp-agent 是一个基于模型上下文协议（MCP）构建的轻量级框架，旨在帮助开发者轻松创建高效、可靠的 AI 智能体。它解决了传统智能体开发中连接管理复杂、架构设计繁琐以及长任务难以持久化的痛点。通过封装 MCP 服务器的生命周期管理，mcp-agent 让开发者无需关注底层连接细节，只需聚焦于业务逻辑。\n\n该工具内置了多种经过验证的智能体协作模式（如地图 - 归约、编排器等），支持以组合方式灵活搭建工作流。其独特亮点在于对“持久化”的原生支持：结合 Temporal 技术，智能体可以在执行过程中暂停、恢复甚至从故障中重建，而无需修改任何代码，从而轻松应对复杂的长时间运行任务。\n\nmcp-agent 非常适合希望快速落地 AI 应用的软件工程师和后端开发者，尤其是那些已经在使用或计划采用 MCP 生态的技术团队。无论是构建简单的问答助手，还是设计涉及多工具调用的复杂自动化流程，mcp-agent 都提供了一条简洁且稳健的实现路径，让构建高质量智能体变得像编写普通脚本一样简单。","\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c2da018782f3.png\" alt=\"Logo\" width=\"300\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n \u003Cem>Build effective agents with Model Context Protocol using simple, composable patterns.\u003C\u002Fem>\n\n\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\" target=\"_blank\">\u003Cstrong>Examples\u003C\u002Fstrong>\u003C\u002Fa>\n |\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview\" target=\"_blank\">\u003Cstrong>Building Effective Agents\u003C\u002Fstrong>\u003C\u002Fa>\n |\n \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction\" target=\"_blank\">\u003Cstrong>MCP\u003C\u002Fstrong>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-8F?style=flat&link=https%3A%2F%2Fdocs.mcp-agent.com%2F\" \u002F>\u003Ca\u002F>\n\u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-agent\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-agent?color=%2334D058&label=pypi\" \u002F>\u003C\u002Fa>\n\u003Cimg alt=\"Pepy Total Downloads\" src=\"https:\u002F\u002Fimg.shields.io\u002Fpepy\u002Fdt\u002Fmcp-agent?label=pypi%20%7C%20downloads\"\u002F>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache_2.0-blue.svg\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-%235865F2.svg?logo=discord&logoColor=white\" alt=\"discord\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F13216\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_4a68feb902da.png\" alt=\"lastmile-ai%2Fmcp-agent | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n## Overview\n\n**`mcp-agent`** is a simple, composable framework to build effective agents using [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction).\n\n> [!Note]\n> mcp-agent's vision is that _MCP is all you need to build agents, and that simple patterns are more robust than complex architectures for shipping high-quality agents_.\n\n`mcp-agent` gives you the following:\n\n1. **Full MCP support**: It _fully_ implements MCP, and handles the pesky business of managing the lifecycle of MCP server connections so you don't have to.\n2. **Effective agent patterns**: It implements every pattern described in Anthropic's [Building Effective Agents](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents) in a _composable_ way, allowing you to chain these patterns together.\n3. **Durable agents**: It works for simple agents and scales to sophisticated workflows built on [Temporal](https:\u002F\u002Ftemporal.io\u002F) so you can pause, resume, and recover without any API changes to your agent.\n\n\u003Cu>Altogether, this is the simplest and easiest way to build robust agent applications\u003C\u002Fu>.\n\nWe welcome all kinds of [contributions](\u002FCONTRIBUTING.md), feedback and your help in improving this project.\n\n\u003Ca id=\"minimal-example\">\u003C\u002Fa>\n**Minimal example**\n\n```python\nimport asyncio\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world\")\n\nasync def main():\n async with app.run():\n agent = Agent(\n name=\"finder\",\n instruction=\"Use filesystem and fetch to answer questions.\",\n server_names=[\"filesystem\", \"fetch\"],\n )\n async with agent:\n llm = await agent.attach_llm(OpenAIAugmentedLLM)\n answer = await llm.generate_str(\"Summarize README.md in two sentences.\")\n print(answer)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n# Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.\n# The [Getting Started guide](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview) walks through configuration and secrets in detail.\n\n```\n\n## At a glance\n\n\u003Ctable>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>Build an Agent\u003C\u002Fh3>\n \u003Cp>Connect LLMs to MCP servers in simple, composable patterns like map-reduce, orchestrator, evaluator-optimizer, router & more.\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview\">Quick Start ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview\">Docs ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>Create any kind of MCP Server\u003C\u002Fh3>\n \u003Cp>Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers.\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server\">MCP Agent Server ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-chatgpt-apps\">🎨 Build a ChatGPT App ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp_agent_server\">Examples ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>Full MCP Support\u003C\u002Fh3>\n \u003Cp>\u003Cb>Core:\u003C\u002Fb> Tools ✅ Resources ✅ Prompts ✅ Notifications ✅\u003Cbr\u002F>\n \u003Cb>Advanced\u003C\u002Fb>: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp\">Examples ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Fgetting-started\u002Fintro\">MCP Docs ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>Durable Execution (Temporal)\u003C\u002Fh3>\n \u003Cp>Scales to production workloads using Temporal as the agent runtime backend \u003Ci>without any API changes\u003C\u002Fi>.\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents\">Docs ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Ftemporal\">Examples ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>☁️ Deploy to Cloud\u003C\u002Fh3>\n \u003Cp>\u003Cb>Beta:\u003C\u002Fb> Deploy agents yourself, or use \u003Cb>mcp-c\u003C\u002Fb> for a managed agent runtime. All apps are deployed as MCP servers.\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0C4VY-3IVNU\">Demo ↗\u003C\u002Fa> |\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fcloud\">Cloud Quickstart ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fcloud\">Examples ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## Documentation & build with LLMs\n\nmcp-agent's complete documentation is available at **[docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com)**, including full SDK guides, CLI reference, and advanced patterns. This readme gives a high-level overview to get you started.\n\n- [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt): contains entire documentation.\n- [`llms.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms.txt): sitemap listing key pages in the docs.\n- [docs MCP server](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Minimal example](#minimal-example)\n- [Quickstart](#get-started)\n- [Why mcp-agent](#why-use-mcp-agent)\n- [Core concepts](#core-components)\n - [MCPApp](#mcpapp)\n - [Agents & AgentSpec](#agents--agentspec)\n - [Augmented LLM](#augmented-llm)\n - [Workflows & decorators](#workflows--decorators)\n - [Configuration & secrets](#configuration--secrets)\n - [MCP integration](#mcp-integration)\n- [Workflow patterns](#workflow-patterns)\n- [CLI reference](#cli-reference)\n- [Authentication](#authentication)\n- [Advanced](#advanced)\n - [Observability & controls](#observability--controls)\n - [Composing workflows](#composing-workflows)\n - [Durable execution](#durable-execution)\n - [Agent servers](#agent-servers)\n - [Signals & human input](#signals--human-input)\n - [App configuration](#app-configuration)\n - [Icons](#icons)\n - [MCP server management](#mcp-server-management)\n- [Cloud deployment](#cloud-deployment)\n- [Examples](#examples)\n- [FAQs](#faqs)\n- [Community & contributions](#contributing)\n\n## Get Started\n\n> [!TIP]\n> The CLI is available via `uvx mcp-agent`.\n> To get up and running,\n> scaffold a project with `uvx mcp-agent init` and deploy with `uvx mcp-agent deploy my-agent`.\n>\n> You can get up and running in 2 minutes by running these commands:\n>\n> ```bash\n> mkdir hello-mcp-agent && cd hello-mcp-agent\n> uvx mcp-agent init\n> uv init\n> uv add \"mcp-agent[openai]\"\n> # Add openai API key to `mcp_agent.secrets.yaml` or set `OPENAI_API_KEY`\n> uv run main.py\n> ```\n\n### Installation\n\nWe recommend using [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) to manage your Python projects (`uv init`).\n\n```bash\nuv add \"mcp-agent\"\n```\n\nAlternatively:\n\n```bash\npip install mcp-agent\n```\n\nAlso add optional packages for LLM providers (e.g. `uv add \"mcp-agent[openai, anthropic, google, azure, bedrock]\"`).\n\n### Quickstart\n\n> [!TIP]\n> The [`examples`](\u002Fexamples) directory has several example applications to get started with.\n> To run an example, clone this repo (or generate one with `uvx mcp-agent init --template basic --dir my-first-agent`)\n>\n> ```bash\n> cd examples\u002Fbasic\u002Fmcp_basic_agent # Or any other example\n> # Option A: secrets YAML\n> # cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml\n> uv run main.py\n> ```\n\nHere is a basic \"finder\" agent that uses the fetch and filesystem servers to look up a file, read a blog and write a tweet. [Example link](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F):\n\n\u003Cdetails open>\n\u003Csummary>finder_agent.py\u003C\u002Fsummary>\n\n```python\nimport asyncio\nimport os\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world_agent\")\n\nasync def example_usage():\n async with app.run() as mcp_agent_app:\n logger = mcp_agent_app.logger\n # This agent can read the filesystem or fetch URLs\n finder_agent = Agent(\n name=\"finder\",\n instruction=\"\"\"You can read local files or fetch URLs.\n Return the requested information when asked.\"\"\",\n server_names=[\"fetch\", \"filesystem\"], # MCP servers this Agent can use\n )\n\n async with finder_agent:\n # Automatically initializes the MCP servers and adds their tools for LLM use\n tools = await finder_agent.list_tools()\n logger.info(f\"Tools available:\", data=tools)\n\n # Attach an OpenAI LLM to the agent (defaults to GPT-4o)\n llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)\n\n # This will perform a file lookup and read using the filesystem server\n result = await llm.generate_str(\n message=\"Show me what's in README.md verbatim\"\n )\n logger.info(f\"README.md contents: {result}\")\n\n # Uses the fetch server to fetch the content from URL\n result = await llm.generate_str(\n message=\"Print the first two paragraphs from https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fbuilding-effective-agents\"\n )\n logger.info(f\"Blog intro: {result}\")\n\n # Multi-turn interactions by default\n result = await llm.generate_str(\"Summarize that in a 128-char tweet\")\n logger.info(f\"Tweet: {result}\")\n\nif __name__ == \"__main__\":\n asyncio.run(example_usage())\n\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>mcp_agent.config.yaml\u003C\u002Fsummary>\n\n```yaml\nexecution_engine: asyncio\nlogger:\n transports: [console] # You can use [file, console] for both\n level: debug\n path: \"logs\u002Fmcp-agent.jsonl\" # Used for file transport\n # For dynamic log filenames:\n # path_settings:\n # path_pattern: \"logs\u002Fmcp-agent-{unique_id}.jsonl\"\n # unique_id: \"timestamp\" # Or \"session_id\"\n # timestamp_format: \"%Y%m%d_%H%M%S\"\n\nmcp:\n servers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n filesystem:\n command: \"npx\"\n args:\n [\n \"-y\",\n \"@modelcontextprotocol\u002Fserver-filesystem\",\n \"\u003Cadd_your_directories>\",\n ]\n\nopenai:\n # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored\n default_model: gpt-4o\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Agent output\u003C\u002Fsummary>\n\u003Cimg width=\"2398\" alt=\"Image\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_f72a1ecf4fe7.png\" \u002F>\n\u003C\u002Fdetails>\n\n## Why use `mcp-agent`?\n\nThere are too many AI frameworks out there already. But `mcp-agent` is the only one that is purpose-built for a shared protocol - [MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction).[mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) pairs Anthropic’s Building Effective Agents patterns with a batteries-included MCP runtime so you can focus on behaviour, not boilerplate. Teams pick it because it is:\n\n- **Composable** – every pattern ships as a reusable workflow you can mix and match.\n- **MCP-native** – any MCP server (filesystem, fetch, Slack, Jira, FastMCP apps) connects without custom adapters.\n- **Production ready** – Temporal-backed durability, structured logging, token accounting, and Cloud deploys are first-class.\n- **Pythonic** – a handful of decorators and context managers wire everything together.\n\nDocs: [Welcome to mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) • [Effective patterns overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview).\n\n## Core Components\n\nEvery project revolves around a single `MCPApp` runtime that loads configuration, registers agents and MCP servers, and exposes tools\u002Fworkflows. The [Core Components guide](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview) walks through these building blocks.\n\n### MCPApp\n\nInitialises configuration, logging, tracing, and the execution engine so everything shares one context.\n\n```python\nfrom mcp_agent.app import MCPApp\n\napp = MCPApp(name=\"finder_app\")\n\nasync def main():\n async with app.run() as running_app:\n logger = running_app.logger\n logger.info(\"App ready\", data={\"servers\": list(running_app.context.server_registry.registry)})\n```\n\nDocs: [MCPApp](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp) • Example: [`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F).\n\n### Agents & AgentSpec\n\nAgents couple instructions with the MCP servers (and optional functions) they may call. `AgentSpec` definitions can be loaded from disk and turned into agents or Augmented LLMs with the factory helpers.\n\n```python\nfrom pathlib import Path\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.factory import load_agent_specs_from_file\n\nagent = Agent(\n name=\"researcher\",\n instruction=\"Research topics using web and filesystem access\",\n server_names=[\"fetch\", \"filesystem\"],\n)\n\nasync with agent:\n tools = await agent.list_tools()\n\nasync with app.run() as running_app:\n specs = load_agent_specs_from_file(\n str(Path(\"examples\u002Fbasic\u002Fagent_factory\u002Fagents.yaml\")),\n context=running_app.context,\n )\n```\n\nDocs: [Agents](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents) • [Agent factory helpers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents#agentspec-and-factory-helpers) • Examples: [`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F).\n\n### Augmented LLM\n\nAugmented LLMs wrap provider SDKs with the agent’s tools, memory, and structured output helpers. Attach one to an agent to unlock `generate`, `generate_str`, and `generate_structured`.\n\n```python\nfrom pydantic import BaseModel\nfrom mcp_agent.workflows.llm.augmented_llm import RequestParams\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\nclass Summary(BaseModel):\n title: str\n verdict: str\n\nasync with agent:\n llm = await agent.attach_llm(OpenAIAugmentedLLM)\n report = await llm.generate_str(\n message=\"Draft a 3-sentence release note from CHANGELOG.md\",\n request_params=RequestParams(maxTokens=400, temperature=0.2),\n )\n structured = await llm.generate_structured(\n message=\"Return a JSON object with `title` and `verdict` summarising the README.\",\n response_model=Summary,\n )\n```\n\nDocs: [Augmented LLMs](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Faugmented-llm) • Examples: [`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F) and the workflow projects listed in [gallery.md](gallery.md#workflow-patterns).\n\n### Workflows & decorators\n\n`MCPApp` decorators convert coroutines into durable workflows and tools. The same annotations work for both `asyncio` and Temporal execution.\n\n```python\nfrom datetime import timedelta\nfrom mcp_agent.executor.workflow import Workflow, WorkflowResult\n\n@app.workflow\nclass PublishArticle(Workflow[WorkflowResult[str]]):\n @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5))\n async def draft(self, topic: str) -> str:\n return f\"- intro to {topic}\\n- highlights\\n- next steps\"\n\n @app.workflow_run\n async def run(self, topic: str) -> WorkflowResult[str]:\n outline = await self.draft(topic)\n return WorkflowResult(value=outline)\n```\n\nDocs: [Decorator reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fdecorators) • Examples: [`examples\u002Fworkflows`](.\u002Fexamples\u002Fworkflows\u002F).\n\n### Configuration & secrets\n\nSettings load from `mcp_agent.config.yaml`, `mcp_agent.secrets.yaml`, environment variables, and optional preload strings. Keep secrets out of source control.\n\n```yaml\n# mcp_agent.config.yaml\nexecution_engine: asyncio\nmcp:\n servers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n filesystem:\n command: \"npx\"\n args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\nopenai:\n default_model: gpt-4o-mini\n\n# mcp_agent.secrets.yaml (gitignored)\nopenai:\n api_key: \"${OPENAI_API_KEY}\"\n```\n\nDocs: [Configuration reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fconfiguration) • [Specify secrets](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fspecify-secrets).\n\n### MCP integration\n\nConnect to existing MCP servers programmatically or aggregate several into one façade.\n\n```python\nfrom mcp_agent.mcp.gen_client import gen_client\n\nasync with app.run():\n async with gen_client(\"filesystem\", app.server_registry, context=app.context) as client:\n resources = await client.list_resources()\n app.logger.info(\"Filesystem resources\", data={\"uris\": [r.uri for r in resources.resources]})\n```\n\nDocs: [MCP integration overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp\u002Foverview) • Examples: [`examples\u002Fmcp`](.\u002Fexamples\u002Fmcp\u002F).\n\n## Workflow patterns\n\nKey agent patterns are implemented as an `AugmentedLLM`. Use factory helpers to wire them up or inspect the runnable projects listed in [gallery.md](gallery.md#workflow-patterns).\n\n| Pattern | Helper | Summary | Docs |\n| --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Parallel (Map-Reduce) | `create_parallel_llm(...)` | Fan-out specialists and fan-in aggregated reports.\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_8dd150045cd9.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_8dd150045cd9.png\" width=\"260\"\u002F>\u003C\u002Fa> | [Parallel](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fmap-reduce) |\n| Router | `create_router_llm(...)` \u002F `create_router_embedding(...)` | Route requests to the best agent, server, or function.\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_995455acef97.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_995455acef97.png\" width=\"260\"\u002F>\u003C\u002Fa> | [Router](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Frouter) |\n| Intent classifier | `create_intent_classifier_llm(...)` \u002F `create_intent_classifier_embedding(...)` | Bucket user input into intents before automation. | [Intent classifier](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fintent-classifier) |\n| Orchestrator-workers | `create_orchestrator(...)` | Generate plans and coordinate worker agents.\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c43549f72b57.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c43549f72b57.png\" width=\"260\"\u002F>\u003C\u002Fa> | [Planner](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fplanner) |\n| Deep research | `create_deep_orchestrator(...)` | Long-horizon research with knowledge extraction and policy checks. | [Deep research](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fdeep-research) |\n| Evaluator-optimizer | `create_evaluator_optimizer_llm(...)` | Iterate until an evaluator approves the result.\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_2f8f0231b3e6.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_2f8f0231b3e6.png\" width=\"260\"\u002F>\u003C\u002Fa> | [Evaluator-optimizer](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fevaluator-optimizer) |\n| Swarm | `create_swarm(...)` | Multi-agent handoffs compatible with OpenAI Swarm.\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_88dad66e7e03.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_88dad66e7e03.png\" width=\"220\"\u002F>\u003C\u002Fa> | [Swarm](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fswarm) |\n\n## Durable execution\n\nSwitch `execution_engine` to `temporal` for pause\u002Fresume, retries, human input, and durable history—without changing workflow code. Run a worker alongside your app to host activities.\n\n```python\nfrom mcp_agent.executor.temporal import create_temporal_worker_for_app\n\nasync with create_temporal_worker_for_app(app) as worker:\n await worker.run()\n```\n\nDocs: [Durable agents](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents) • [Temporal backend](https:\u002F\u002Fdocs.mcp-agent.com\u002Fadvanced\u002Ftemporal) • Examples: [`examples\u002Ftemporal`](.\u002Fexamples\u002Ftemporal\u002F).\n\n## Agent servers\n\nExpose an `MCPApp` as a standard MCP server so Claude Desktop, Cursor, or custom clients can call your tools and workflows.\n\n```python\nfrom mcp_agent.server import create_mcp_server_for_app\n\n@app.tool\ndef grade_story(story: str) -> str:\n return \"Report...\"\n\nif __name__ == \"__main__\":\n server = create_mcp_server_for_app(app)\n server.run_stdio()\n```\n\nDocs: [Agent servers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server) • Examples: [`examples\u002Fmcp_agent_server`](.\u002Fexamples\u002Fmcp_agent_server\u002F).\n\n## CLI reference\n\n`uvx mcp-agent` scaffolds projects, manages secrets, inspects workflows, and deploys to Cloud.\n\n```bash\nuvx mcp-agent init --template basic # Scaffold a new project\nuvx mcp-agent deploy my-agent # Deploy to mcp-agent Cloud\n```\n\nDocs: [CLI reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fcli) • [Getting started guides](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fquickstart).\n\n## Authentication\n\nLoad API keys from secrets files or use the built-in OAuth client to fetch and persist tokens for MCP servers.\n\n```yaml\n# mcp_agent.config.yaml excerpt\noauth:\n providers:\n github:\n client_id: \"${GITHUB_CLIENT_ID}\"\n client_secret: \"${GITHUB_CLIENT_SECRET}\"\n scopes: [\"repo\", \"user\"]\n```\n\nDocs: [Advanced authentication](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fauthentication) • [Server authentication](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fserver-authentication) • Examples: [`examples\u002Fbasic\u002Foauth_basic_agent`](.\u002Fexamples\u002Fbasic\u002Foauth_basic_agent\u002F).\n\n## Advanced\n\n### Observability & controls\n\nEnable structured logging and OpenTelemetry via configuration, and track token usage programmatically.\n\n```yaml\n# mcp_agent.config.yaml\nlogger:\n transports: [console]\n level: info\notel:\n enabled: true\n exporters:\n - console\n```\n\n`TokenCounter` tracks token usage for agents, workflows, and LLM nodes. Attach watchers to stream updates or trigger alerts.\n\n```python\n# Inside `async with app.run() as running_app:`\n# token_counter lives on the running app context when tracing is enabled.\ntoken_counter = running_app.context.token_counter\n\nclass TokenMonitor:\n async def on_token_update(self, node, usage):\n print(f\"[{node.name}] total={usage.total_tokens}\")\n\nmonitor = TokenMonitor()\nwatch_id = await token_counter.watch(\n callback=monitor.on_token_update,\n node_type=\"llm\",\n threshold=1_000,\n include_subtree=True,\n)\n\nawait token_counter.unwatch(watch_id)\n```\n\nDocs: [Observability](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fobservability) • Examples: [`examples\u002Ftracing`](.\u002Fexamples\u002Ftracing\u002F).\n\n### Composing workflows\n\nMix and match AgentSpecs to build higher-level workflows using the factory helpers—routers, parallel pipelines, orchestrators, and more.\n\n```python\nfrom mcp_agent.workflows.factory import create_router_llm\n\n# specs are loaded via load_agent_specs_from_file as shown above.\nasync with app.run() as running_app:\n router = await create_router_llm(\n agents=specs,\n provider=\"openai\",\n context=running_app.context,\n )\n```\n\nDocs: [Workflow composition](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fcomposition) • Examples: [`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F).\n\n### Signals & human input\n\nPause workflows for approvals or extra data. Temporal stores state durably until an operator resumes the run.\n\n```python\nfrom mcp_agent.human_input.types import HumanInputRequest\n\nresponse = await self.context.request_human_input(\n HumanInputRequest(\n prompt=\"Approve the draft?\",\n required=True,\n metadata={\"workflow_id\": self.context.workflow_id},\n )\n)\n```\n\nResume with `mcp-agent cloud workflows resume … --payload '{\"content\": \"approve\"}'`. Docs: [Deploy agents – human input](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-agents#human-in-the-loop-patterns) • Examples: [`examples\u002Fhuman_input\u002Ftemporal`](.\u002Fexamples\u002Fhuman_input\u002Ftemporal\u002F).\n\n### App configuration\n\nBuild `Settings` objects programmatically when you need dynamic config (tests, multi-tenant hosts) instead of YAML files.\n\n```python\nfrom mcp_agent.config import Settings, MCPSettings, MCPServerSettings\n\nsettings = Settings(\n execution_engine=\"asyncio\",\n mcp=MCPSettings(\n servers={\n \"fetch\": MCPServerSettings(command=\"uvx\", args=[\"mcp-server-fetch\"]),\n }\n ),\n)\napp = MCPApp(name=\"configured_app\", settings=settings)\n```\n\nDocs: [Configuring your application](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconfiguring-your-application).\n\n### Icons\n\nAdd icons to agents and tools so MCP clients that support imagery (Claude Desktop, Cursor) render richer UIs.\n\n```python\nfrom base64 import standard_b64encode\nfrom pathlib import Path\nfrom mcp_agent.icons import Icon\n\nicon_data = standard_b64encode(Path(\"my-icon.png\").read_bytes()).decode()\nicon = Icon(src=f\"data:image\u002Fpng;base64,{icon_data}\", mimeType=\"image\u002Fpng\", sizes=[\"64x64\"])\n\napp = MCPApp(name=\"my_app_with_icon\", icons=[icon])\n\n@app.tool(icons=[icon])\nasync def my_tool() -> str:\n return \"Hello with style\"\n```\n\nDocs: [`MCPApp` icons](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp#icons) • Examples: [`examples\u002Fmcp_agent_server\u002Fasyncio`](.\u002Fexamples\u002Fmcp_agent_server\u002Fasyncio\u002F).\n\n### MCP server management\n\nUse `MCPAggregator` or `gen_client` to manage MCP server connections and expose combined tool sets.\n\n```python\nfrom mcp_agent.mcp.mcp_aggregator import MCPAggregator\n\nasync with MCPAggregator.create(server_names=[\"fetch\", \"filesystem\"]) as aggregator:\n tools = await aggregator.list_tools()\n```\n\nDocs: [Connecting to MCP servers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconnecting-to-mcp-servers) • Examples: [`examples\u002Fbasic\u002Fmcp_server_aggregator`](.\u002Fexamples\u002Fbasic\u002Fmcp_server_aggregator\u002F).\n\n## Cloud deployment\n\nDeploy to mcp-agent Cloud for managed Temporal execution, secrets, and HTTPS MCP endpoints.\n\n```bash\nuvx mcp-agent login\nuvx mcp-agent deploy my-agent\nuvx mcp-agent cloud apps list\n```\n\nDocs: [Cloud overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Foverview) • [Deployment quickstart](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fdeployment-quickstart) • Examples: [`examples\u002Fcloud`](.\u002Fexamples\u002Fcloud\u002F).\n\n## Examples\n\nBrowse [gallery.md](gallery.md) for runnable examples, demo videos, and community projects grouped by concept. Every entry cites the docs page and command you need to run it locally.\n\n## FAQs\n\n### What are the core benefits of using mcp-agent?\n\nmcp-agent provides a streamlined approach to building AI agents using capabilities exposed by **MCP** (Model Context Protocol) servers.\n\nMCP is quite low-level, and this framework handles the mechanics of connecting to servers, working with LLMs, handling external signals (like human input) and supporting persistent state via durable execution. That lets you, the developer, focus on the core business logic of your AI application.\n\nCore benefits:\n\n- 🤝 **Interoperability**: ensures that any tool exposed by any number of MCP servers can seamlessly plug in to your agents.\n- ⛓️ **Composability & Customizability**: Implements well-defined workflows, but in a composable way that enables compound workflows, and allows full customization across model provider, logging, orchestrator, etc.\n- 💻 **Programmatic control flow**: Keeps things simple as developers just write code instead of thinking in graphs, nodes and edges. For branching logic, you write `if` statements. For cycles, use `while` loops.\n- 🖐️ **Human Input & Signals**: Supports pausing workflows for external signals, such as human input, which are exposed as tool calls an Agent can make.\n\n### Do you need an MCP client to use mcp-agent?\n\nNo, you can use mcp-agent anywhere, since it handles MCPClient creation for you. This allows you to leverage MCP servers outside of MCP hosts like Claude Desktop.\n\nHere's all the ways you can set up your mcp-agent application:\n\n#### MCP-Agent Server\n\nYou can expose mcp-agent applications as MCP servers themselves (see [example](.\u002Fexamples\u002Fmcp_agent_server)), allowing MCP clients to interface with sophisticated AI workflows using the standard tools API of MCP servers. This is effectively a server-of-servers.\n\n#### MCP Client or Host\n\nYou can embed mcp-agent in an MCP client directly to manage the orchestration across multiple MCP servers.\n\n#### Standalone\n\nYou can use mcp-agent applications in a standalone fashion (i.e. they aren't part of an MCP client). The [`examples`](\u002Fexamples\u002F) are all standalone applications.\n\n### How do I deploy to Cloud?\n\nRun `uvx mcp-agent deploy \u003Capp-name>` after logging in with `uvx mcp-agent login`. The CLI packages your project, provisions secrets, and exposes an MCP endpoint backed by a durable Temporal runtime. See the [Cloud quickstart](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002F\ncloud) for step-by-step screenshots and CLI output.\n\n### Where is the API reference?\n\nEvery class, decorator, and CLI command is documented on [docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com). The [API reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference) and the [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt) are designed so LLMs (or you) can ingest the whole surface area easily.\n\n### Tell me a fun fact\n\nI debated naming this project _silsila_ (سلسلہ), which means chain of events in Urdu. mcp-agent is more matter-of-fact, but there's still an easter egg in the project paying homage to silsila.\n\n## Contributing\n\nWe welcome contributions of every size—bug fixes, new examples, docs, or feature requests. Start with [CONTRIBUTING.md](.\u002FCONTRIBUTING.md), open a discussion, or drop by [Discord](https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent).\n\nmcp-agent would not be possible without the tireless efforts of the many open source contributors. Thank you!\n\n\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fgraphs\u002Fcontributors\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_db1fb3c93bff.png\" alt=\"Contributor faces\" \u002F>\n \u003C\u002Fa>\n\u003C\u002Fp>\n","\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c2da018782f3.png\" alt=\"Logo\" width=\"300\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n \u003Cem>使用简单、可组合的模式，借助模型上下文协议构建高效智能体。\u003C\u002Fem>\n\n\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\" target=\"_blank\">\u003Cstrong>示例\u003C\u002Fstrong>\u003C\u002Fa>\n |\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview\" target=\"_blank\">\u003Cstrong>构建高效智能体\u003C\u002Fstrong>\u003C\u002Fa>\n |\n \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction\" target=\"_blank\">\u003Cstrong>MCP\u003C\u002Fstrong>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-8F?style=flat&link=https%3A%2F%2Fdocs.mcp-agent.com%2F\" \u002F>\u003Ca\u002F>\n\u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-agent\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-agent?color=%2334D058&label=pypi\" \u002F>\u003C\u002Fa>\n\u003Cimg alt=\"Pepy 总下载量\" src=\"https:\u002F\u002Fimg.shields.io\u002Fpepy\u002Fdt\u002Fmcp-agent?label=pypi%20%7C%20downloads\"\u002F>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache_2.0-blue.svg\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-%235865F2.svg?logo=discord&logoColor=white\" alt=\"discord\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F13216\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_4a68feb902da.png\" alt=\"lastmile-ai%2Fmcp-agent | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n## 概述\n\n**`mcp-agent`** 是一个简单、可组合的框架，用于使用 [模型上下文协议](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction) 构建高效智能体。\n\n> [!注]\n> mcp-agent 的愿景是：_只需 MCP 就能构建智能体，而简单的模式比复杂的架构更能稳定地交付高质量的智能体_。\n\n`mcp-agent` 为您提供以下功能：\n\n1. **全面支持 MCP**：它 _完全_ 实现了 MCP，并负责管理 MCP 服务器连接的生命周期等繁琐事务，让您无需操心。\n2. **高效的智能体模式**：它以 _可组合_ 的方式实现了 Anthropic 的《构建高效智能体》中描述的所有模式，允许您将这些模式串联起来。\n3. **持久化智能体**：它既适用于简单的智能体，也能扩展到基于 [Temporal](https:\u002F\u002Ftemporal.io\u002F) 构建的复杂工作流，因此您可以在不更改智能体 API 的情况下暂停、恢复和故障恢复。\n\n\u003Cu>总而言之，这是构建健壮智能体应用最简单、最容易的方式\u003C\u002Fu>。\n\n我们欢迎各种形式的 [贡献](\u002FCONTRIBUTING.md)、反馈以及您对本项目的改进帮助。\n\n\u003Ca id=\"minimal-example\">\u003C\u002Fa>\n**最小示例**\n\n```python\nimport asyncio\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world\")\n\nasync def main():\n async with app.run():\n agent = Agent(\n name=\"finder\",\n instruction=\"使用文件系统和 fetch 来回答问题。\",\n server_names=[\"filesystem\", \"fetch\"],\n )\n async with agent:\n llm = await agent.attach_llm(OpenAIAugmentedLLM)\n answer = await llm.generate_str(\"用两句话概括 README.md。\")\n print(answer)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n# 将您的 LLM API 密钥添加到 `mcp_agent.secrets.yaml` 或在环境变量中设置。\n# 《快速入门指南》（https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview）详细介绍了配置和密钥管理。\n\n```\n\n## 一览\n\n\u003Ctable>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>构建智能体\u003C\u002Fh3>\n \u003Cp>以简单、可组合的模式（如 map-reduce、编排器、评估优化器、路由器等）将 LLM 连接到 MCP 服务器。\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview\">快速入门 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview\">文档 ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>创建任意类型的 MCP 服务器\u003C\u002Fh3>\n \u003Cp>使用与 FastMCP 兼容的 API 创建 MCP 服务器。您甚至可以将智能体暴露为 MCP 服务器。\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server\">MCP 智能体服务器 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-chatgpt-apps\">🎨 构建 ChatGPT 应用程序 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp_agent_server\">示例 ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>全面支持 MCP\u003C\u002Fh3>\n \u003Cp>\u003Cb>核心：\u003C\u002Fb>工具 ✅ 资源 ✅ 提示词 ✅ 通知 ✅\u003Cbr\u002F>\n \u003Cb>进阶：\u003C\u002Fb>OAuth ✅ 抽样 ✅ 引导式交互 ✅ 根节点 ✅\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp\">示例 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Fgetting-started\u002Fintro\">MCP 文档 ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>持久化执行（Temporal）\u003C\u002Fh3>\n \u003Cp>利用 Temporal 作为智能体运行时后端，可在不进行任何 API 更改的情况下扩展至生产级工作负载。\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents\">文档 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Ftemporal\">示例 ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd width=\"50%\" valign=\"top\">\n \u003Ch3>☁️ 部署到云端\u003C\u002Fh3>\n \u003Cp>\u003Cb>测试版：\u003C\u002Fb>您可以自行部署智能体，也可以使用 \u003Cb>mcp-c\u003C\u002Fb> 获取托管的智能体运行时服务。所有应用都会被部署为 MCP 服务器。\u003C\u002Fp>\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0C4VY-3IVNU\">演示 ↗\u003C\u002Fa> |\n \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fcloud\">云端快速入门 ↗\u003C\u002Fa> | \n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fcloud\">示例 ↗\u003C\u002Fa>\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## 文档与 LLM 构建\n\nmcp-agent 的完整文档可在 **[docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com)** 查阅，包括完整的 SDK 指南、CLI 参考以及高级模式。本自述文件提供了高层次的概览，帮助您快速上手。\n\n- [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt)：包含全部文档。\n- [`llms.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms.txt)：列出文档关键页面的站点地图。\n- [MCP 服务器文档](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp)\n\n## 目录\n\n- [概述](#overview)\n- [最小示例](#minimal-example)\n- [快速入门](#get-started)\n- [为什么使用 mcp-agent](#why-use-mcp-agent)\n- [核心概念](#core-components)\n - [MCPApp](#mcpapp)\n - [代理与 AgentSpec](#agents--agentspec)\n - [增强型 LLM](#augmented-llm)\n - [工作流与装饰器](#workflows--decorators)\n - [配置与密钥](#configuration--secrets)\n - [MCP 集成](#mcp-integration)\n- [工作流模式](#workflow-patterns)\n- [CLI 参考](#cli-reference)\n- [认证](#authentication)\n- [高级功能](#advanced)\n - [可观测性与控制](#observability--controls)\n - [组合工作流](#composing-workflows)\n - [持久化执行](#durable-execution)\n - [代理服务器](#agent-servers)\n - [信号与人工输入](#signals--human-input)\n - [应用配置](#app-configuration)\n - [图标](#icons)\n - [MCP 服务器管理](#mcp-server-management)\n- [云端部署](#cloud-deployment)\n- [示例](#examples)\n- [常见问题](#faqs)\n- [社区与贡献](#contributing)\n\n## 快速入门\n\n> [!提示]\n> CLI 可通过 `uvx mcp-agent` 使用。要快速上手，\n> 可以使用 `uvx mcp-agent init` 搭建项目，并用 `uvx mcp-agent deploy my-agent` 进行部署。\n>\n> 您只需运行以下命令，即可在两分钟内开始使用：\n>\n> ```bash\n> mkdir hello-mcp-agent && cd hello-mcp-agent\n> uvx mcp-agent init\n> uv init\n> uv add \"mcp-agent[openai]\"\n> # 将 OpenAI API 密钥添加到 `mcp_agent.secrets.yaml` 或设置 `OPENAI_API_KEY`\n> uv run main.py\n> ```\n\n### 安装\n\n我们建议使用 [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) 来管理您的 Python 项目（`uv init`）。\n\n```bash\nuv add \"mcp-agent\"\n```\n\n或者：\n\n```bash\npip install mcp-agent\n```\n\n此外，还可以根据需要安装 LLM 提供商的可选包（例如：`uv add \"mcp-agent[openai, anthropic, google, azure, bedrock]\"`）。\n\n### 快速入门\n\n> [!提示]\n> 在 [`examples`](\u002Fexamples) 目录中，有多个示例应用可供您快速上手。要运行示例，您可以克隆此仓库，或使用 `uvx mcp-agent init --template basic --dir my-first-agent` 生成一个新项目。\n>\n> ```bash\n> cd examples\u002Fbasic\u002Fmcp_basic_agent # 或其他示例目录\n> # 方法 A：使用 secrets YAML 文件\n> # cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml 并编辑内容\n> uv run main.py\n> ```\n\n以下是一个基础的“查找”代理，它利用 fetch 和文件系统服务器来查找文件、阅读博客并发布推文。[示例链接](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F)：\n\n\u003Cdetails open>\n\u003Csummary>finder_agent.py\u003C\u002Fsummary>\n\n```python\nimport asyncio\nimport os\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world_agent\")\n\nasync def example_usage():\n async with app.run() as mcp_agent_app:\n logger = mcp_agent_app.logger,\n # 此代理可以读取本地文件或抓取 URL\n finder_agent = Agent(\n name=\"finder\",\n instruction=\"\"\"你可以读取本地文件或抓取 URL。\n 当被要求时，请返回所需的信息。\"\"\",\n server_names=[\"fetch\", \"filesystem\"], # 该代理可使用的 MCP 服务器\n )\n\n async with finder_agent:\n # 自动初始化 MCP 服务器，并将它们的工具添加到 LLM 的使用列表\n tools = await finder_agent.list_tools()\n logger.info(f\"可用工具:\", data=tools)\n\n # 将 OpenAI 的 LLM 绑定到代理（默认为 GPT-4o）\n llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)\n\n # 这将通过文件系统服务器进行文件查找和读取\n result = await llm.generate_str(\n message=\"请逐字显示 README.md 中的内容\"\n )\n logger.info(f\"README.md 内容: {result}\")\n\n # 使用 fetch 服务器从 URL 获取内容\n result = await llm.generate_str(\n message=\"请打印 https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fbuilding-effective-agents 上前两段文字\"\n )\n logger.info(f\"博客简介: {result}\")\n\n # 默认支持多轮交互\n result = await llm.generate_str(\"用 128 字的推文概括上述内容\")\n logger.info(f\"推文: {result}\")\n\nif __name__ == \"__main__\":\n asyncio.run(example_usage())\n\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>mcp_agent.config.yaml\u003C\u002Fsummary>\n\n```yaml\nexecution_engine: asyncio\nlogger:\n transports: [console] # 您也可以同时使用 [file, console]\n level: debug\n path: \"logs\u002Fmcp-agent.jsonl\" # 用于文件传输\n # 对于动态日志文件名：\n # path_settings:\n # path_pattern: \"logs\u002Fmcp-agent-{unique_id}.jsonl\"\n # unique_id: \"timestamp\" # 或 \"session_id\"\n # timestamp_format: \"%Y%m%d_%H%M%S\"\n\nmcp:\n servers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n filesystem:\n command: \"npx\"\n args:\n [\n \"-y\",\n \"@modelcontextprotocol\u002Fserver-filesystem\",\n \"\u003C添加您的目录>\",\n ]\n\nopenai:\n # 密钥（API 密钥等）存储在 mcp_agent.secrets.yaml 文件中，该文件可以被忽略提交到版本库\n default_model: gpt-4o\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>代理输出\u003C\u002Fsummary>\n\u003Cimg width=\"2398\" alt=\"Image\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_f72a1ecf4fe7.png\" \u002F>\n\u003C\u002Fdetails>\n\n## 为什么选择 `mcp-agent`？\n\n目前市面上已经有许多 AI 框架。然而，`mcp-agent` 是唯一一个专为共享协议——[MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction)——构建的框架。[mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) 将 Anthropic 的 Building Effective Agents 模式与开箱即用的 MCP 运行时相结合，使您能够专注于行为逻辑，而非繁琐的样板代码。团队之所以选择它，是因为它具有以下特点：\n\n- **可组合性**：每个模式都以可重用的工作流形式提供，您可以自由组合搭配。\n- **原生支持 MCP**：任何 MCP 服务器（文件系统、fetch、Slack、Jira、FastMCP 应用）都可以无需自定义适配器直接连接。\n- **生产就绪**：内置 Temporal 支持的持久化机制、结构化日志记录、令牌计费以及云部署等功能均为一流水平。\n- **Python 式设计**：仅需少量装饰器和上下文管理器即可轻松完成所有配置与集成。\n\n文档：[欢迎使用 mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) • [有效模式概览](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview)。\n\n## 核心组件\n\n每个项目都围绕一个 `MCPApp` 运行时展开，该运行时负责加载配置、注册代理和 MCP 服务器，并暴露工具及工作流。[核心组件指南](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview)将详细介绍这些构建模块。\n\n### MCPApp\n\n初始化配置、日志记录、跟踪以及执行引擎，使所有组件共享同一个上下文。\n\n```python\nfrom mcp_agent.app import MCPApp\n\napp = MCPApp(name=\"finder_app\")\n\nasync def main():\n async with app.run() as running_app:\n logger = running_app.logger\n logger.info(\"应用已就绪\", data={\"服务器\": list(running_app.context.server_registry.registry)})\n```\n\n文档：[MCPApp](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp) • 示例：[`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F)。\n\n### Agents & AgentSpec\n\n代理将指令与其可能调用的 MCP 服务器（以及可选函数）绑定在一起。`AgentSpec` 定义可以从磁盘加载，并通过工厂辅助工具转换为代理或增强型大语言模型。\n\n```python\nfrom pathlib import Path\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.factory import load_agent_specs_from_file\n\nagent = Agent(\n name=\"研究员\",\n instruction=\"使用网络和文件系统访问功能研究主题\",\n server_names=[\"fetch\", \"filesystem\"],\n)\n\nasync with agent:\n tools = await agent.list_tools()\n\nasync with app.run() as running_app:\n specs = load_agent_specs_from_file(\n str(Path(\"examples\u002Fbasic\u002Fagent_factory\u002Fagents.yaml\")),\n context=running_app.context,\n )\n```\n\n文档：[Agents](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents) • [代理工厂辅助工具](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents#agentspec-and-factory-helpers) • 示例：[`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F)。\n\n### 增强型大语言模型\n\n增强型大语言模型将提供商 SDK 与代理的工具、记忆和结构化输出助手封装在一起。将它附加到代理上，即可解锁 `generate`、`generate_str` 和 `generate_structured` 方法。\n\n```python\nfrom pydantic import BaseModel\nfrom mcp_agent.workflows.llm.augmented_llm import RequestParams\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\nclass Summary(BaseModel):\n title: str\n verdict: str\n\nasync with agent:\n llm = await agent.attach_llm(OpenAIAugmentedLLM)\n report = await llm.generate_str(\n message=\"根据 CHANGELOG.md 草拟一段三句话的发布说明\",\n request_params=RequestParams(maxTokens=400, temperature=0.2),\n )\n structured = await llm.generate_structured(\n message=\"返回一个包含 `title` 和 `verdict` 的 JSON 对象，总结 README 文件。\",\n response_model=Summary,\n )\n```\n\n文档：[增强型大语言模型](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Faugmented-llm) • 示例：[`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F)以及 [gallery.md](gallery.md#workflow-patterns) 中列出的工作流项目。\n\n### 工作流与装饰器\n\n`MCPApp` 装饰器可以将协程转换为持久性的工作流和工具。相同的注解既适用于 `asyncio` 也适用于 Temporal 执行。\n\n```python\nfrom datetime import timedelta\nfrom mcp_agent.executor.workflow import Workflow, WorkflowResult\n\n@app.workflow\nclass PublishArticle(Workflow[WorkflowResult[str]]):\n @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5))\n async def draft(self, topic: str) -> str:\n return f\"- 关于 {topic} 的简介\\n- 重点内容\\n- 下一步\"\n\n @app.workflow_run\n async def run(self, topic: str) -> WorkflowResult[str]:\n outline = await self.draft(topic)\n return WorkflowResult(value=outline)\n```\n\n文档：[装饰器参考](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fdecorators) • 示例：[`examples\u002Fworkflows`](.\u002Fexamples\u002Fworkflows\u002F)。\n\n### 配置与密钥\n\n设置可以从 `mcp_agent.config.yaml`、`mcp_agent.secrets.yaml`、环境变量以及可选的预加载字符串中加载。请勿将密钥存储在源代码控制中。\n\n```yaml\n# mcp_agent.config.yaml\nexecution_engine: asyncio\nmcp:\n servers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n filesystem:\n command: \"npx\"\n args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\nopenai:\n default_model: gpt-4o-mini\n\n# mcp_agent.secrets.yaml（已忽略于 git）\nopenai:\n api_key: \"${OPENAI_API_KEY}\"\n```\n\n文档：[配置参考](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fconfiguration) • [指定密钥](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fspecify-secrets)。\n\n### MCP 集成\n\n可以通过编程方式连接到现有的 MCP 服务器，或将多个服务器聚合为一个统一的接口。\n\n```python\nfrom mcp_agent.mcp.gen_client import gen_client\n\nasync with app.run():\n async with gen_client(\"filesystem\", app.server_registry, context=app.context) as client:\n resources = await client.list_resources()\n app.logger.info(\"文件系统资源\", data={\"URIs\": [r.uri for r in resources.resources]})\n```\n\n文档：[MCP 集成概述](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp\u002Foverview) • 示例：[`examples\u002Fmcp`](.\u002Fexamples\u002Fmcp\u002F)。\n\n## 工作流模式\n\n关键代理模式以 `AugmentedLLM` 的形式实现。可以使用工厂辅助函数来配置这些模式，或查看 [gallery.md](gallery.md#workflow-patterns) 中列出的可运行项目。\n\n| 模式 | 辅助函数 | 简介 | 文档 |\n| --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |\n| 并行（Map-Reduce） | `create_parallel_llm(...)` | 扇出专家任务，并将结果扇入汇总。\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_8dd150045cd9.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_8dd150045cd9.png\" width=\"260\"\u002F>\u003C\u002Fa> | [并行](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fmap-reduce) |\n| 路由器 | `create_router_llm(...)` \u002F `create_router_embedding(...)` | 将请求路由到最佳的代理、服务器或函数。\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_995455acef97.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_995455acef97.png\" width=\"260\"\u002F>\u003C\u002Fa> | [路由器](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Frouter) |\n| 意图分类器 | `create_intent_classifier_llm(...)` \u002F `create_intent_classifier_embedding(...)` | 在自动化之前，将用户输入归类到不同的意图中。 | [意图分类器](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fintent-classifier) |\n| 协调者-工作者 | `create_orchestrator(...)` | 生成计划并协调工作者代理。\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c43549f72b57.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_c43549f72b57.png\" width=\"260\"\u002F>\u003C\u002Fa> | [规划者](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fplanner) |\n| 深度研究 | `create_deep_orchestrator(...)` | 长期限的研究，包含知识提取和策略检查。 | [深度研究](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fdeep-research) |\n| 评估者-优化者 | `create_evaluator_optimizer_llm(...)` | 不断迭代，直到评估者批准结果。\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_2f8f0231b3e6.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_2f8f0231b3e6.png\" width=\"260\"\u002F>\u003C\u002Fa> | [评估者-优化者](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fevaluator-optimizer) |\n| 蜂群 | `create_swarm(...)` | 多代理交接，与 OpenAI Swarm 兼容。\u003Cbr>\u003Ca href=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_88dad66e7e03.png\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_88dad66e7e03.png\" width=\"220\"\u002F>\u003C\u002Fa> | [蜂群](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fswarm) |\n\n## 持久化执行\n\n将 `execution_engine` 切换为 `temporal`，即可实现暂停\u002F恢复、重试、人工干预以及持久化历史记录等功能，而无需更改工作流代码。可以在应用旁边运行一个工作进程来托管活动。\n\n```python\nfrom mcp_agent.executor.temporal import create_temporal_worker_for_app\n\nasync with create_temporal_worker_for_app(app) as worker:\n await worker.run()\n```\n\n文档：[持久化代理](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents) • [Temporal 后端](https:\u002F\u002Fdocs.mcp-agent.com\u002Fadvanced\u002Ftemporal) • 示例：[`examples\u002Ftemporal`](.\u002Fexamples\u002Ftemporal\u002F)。\n\n## 代理服务器\n\n将 `MCPApp` 暴露为标准的 MCP 服务器，以便 Claude Desktop、Cursor 或自定义客户端可以调用您的工具和工作流。\n\n```python\nfrom mcp_agent.server import create_mcp_server_for_app\n\n@app.tool\ndef grade_story(story: str) -> str:\n return \"报告...\"\n\nif __name__ == \"__main__\":\n server = create_mcp_server_for_app(app)\n server.run_stdio()\n```\n\n文档：[代理服务器](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server) • 示例：[`examples\u002Fmcp_agent_server`](.\u002Fexamples\u002Fmcp_agent_server\u002F)。\n\n## CLI 参考\n\n`uvx mcp-agent` 可用于搭建项目、管理密钥、检查工作流以及部署到云端。\n\n```bash\nuvx mcp-agent init --template basic # 搭建新项目\nuvx mcp-agent deploy my-agent # 部署到 mcp-agent 云平台\n```\n\n文档：[CLI 参考](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fcli) • [入门指南](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fquickstart)。\n\n## 身份验证\n\n可以从密钥文件中加载 API 密钥，也可以使用内置的 OAuth 客户端获取并持久化 MCP 服务器的令牌。\n\n```yaml\n# mcp_agent.config.yaml 摘录\noauth:\n providers:\n github:\n client_id: \"${GITHUB_CLIENT_ID}\"\n client_secret: \"${GITHUB_CLIENT_SECRET}\"\n scopes: [\"repo\", \"user\"]\n```\n\n文档：[高级身份验证](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fauthentication) • [服务器身份验证](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fserver-authentication) • 示例：[`examples\u002Fbasic\u002Foauth_basic_agent`](.\u002Fexamples\u002Fbasic\u002Foauth_basic_agent\u002F)。\n\n## 高级功能\n\n### 可观测性与控制\n\n通过配置启用结构化日志记录和 OpenTelemetry，并以编程方式跟踪令牌使用情况。\n\n```yaml\n# mcp_agent.config.yaml\nlogger:\n transports: [console]\n level: info\notel:\n enabled: true\n exporters:\n - console\n```\n\n`TokenCounter` 可以跟踪代理、工作流和 LLM 节点的令牌使用情况。您可以附加监听器来实时接收更新或触发警报。\n\n```python\n# 在 `async with app.run() as running_app:` 中\n# 当启用了追踪时，token_counter 会存在于运行应用的上下文中。\ntoken_counter = running_app.context.token_counter\n\nclass TokenMonitor:\n async def on_token_update(self, node, usage):\n print(f\"[{node.name}] 总计={usage.total_tokens}\")\n\nmonitor = TokenMonitor()\nwatch_id = await token_counter.watch(\n callback=monitor.on_token_update,\n node_type=\"llm\",\n threshold=1_000,\n include_subtree=True,\n)\n\nawait token_counter.unwatch(watch_id)\n```\n\n文档：[可观测性](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fobservability) • 示例：[`examples\u002Ftracing`](.\u002Fexamples\u002Ftracing\u002F)。\n\n### 工作流编排\n\n使用工厂辅助函数（路由器、并行管道、编排器等）混合搭配 AgentSpecs，构建更高级别的工作流。\n\n```python\nfrom mcp_agent.workflows.factory import create_router_llm\n\n# 如上所示，可以通过 load_agent_specs_from_file 加载规格。\nasync with app.run() as running_app:\n router = await create_router_llm(\n agents=specs,\n provider=\"openai\",\n context=running_app.context,\n )\n```\n\n文档：[工作流编排](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fcomposition) • 示例：[`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F)。\n\n### 信号与人工输入\n\n暂停工作流以等待审批或额外数据。Temporal 会持久化存储状态，直到操作员恢复执行。\n\n```python\nfrom mcp_agent.human_input.types import HumanInputRequest\n\nresponse = await self.context.request_human_input(\n HumanInputRequest(\n prompt=\"批准草稿吗？\",\n required=True,\n metadata={\"workflow_id\": self.context.workflow_id},\n )\n)\n```\n\n可通过 `mcp-agent cloud workflows resume … --payload '{\"content\": \"approve\"}'` 恢复执行。文档：[部署代理——人工输入](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-agents#human-in-the-loop-patterns) • 示例：[`examples\u002Fhuman_input\u002Ftemporal`](.\u002Fexamples\u002Fhuman_input\u002Ftemporal\u002F)。\n\n### 应用配置\n\n当需要动态配置（如测试环境、多租户主机）而无需使用 YAML 文件时，可以以编程方式构建 `Settings` 对象。\n\n```python\nfrom mcp_agent.config import Settings, MCPSettings, MCPServerSettings\n\nsettings = Settings(\n execution_engine=\"asyncio\",\n mcp=MCPSettings(\n servers={\n \"fetch\": MCPServerSettings(command=\"uvx\", args=[\"mcp-server-fetch\"]),\n }\n ),\n)\napp = MCPApp(name=\"configured_app\", settings=settings)\n```\n\n文档：[配置您的应用](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconfiguring-your-application)。\n\n### 图标\n\n为代理和工具添加图标，以便支持图像显示的 MCP 客户端（如 Claude Desktop、Cursor）能够渲染更丰富的用户界面。\n\n```python\nfrom base64 import standard_b64encode\nfrom pathlib import Path\nfrom mcp_agent.icons import Icon\n\nicon_data = standard_b64encode(Path(\"my-icon.png\").read_bytes()).decode()\nicon = Icon(src=f\"data:image\u002Fpng;base64,{icon_data}\", mimeType=\"image\u002Fpng\", sizes=[\"64x64\"])\n\napp = MCPApp(name=\"my_app_with_icon\", icons=[icon])\n\n@app.tool(icons=[icon])\nasync def my_tool() -> str:\n return \"带着风格的问候\"\n```\n\n文档：[`MCPApp` 图标](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp#icons) • 示例：[`examples\u002Fmcp_agent_server\u002Fasyncio`](.\u002Fexamples\u002Fmcp_agent_server\u002Fasyncio\u002F)。\n\n### MCP 服务器管理\n\n使用 `MCPAggregator` 或 `gen_client` 来管理 MCP 服务器连接，并暴露组合后的工具集。\n\n```python\nfrom mcp_agent.mcp.mcp_aggregator import MCPAggregator\n\nasync with MCPAggregator.create(server_names=[\"fetch\", \"filesystem\"]) as aggregator:\n tools = await aggregator.list_tools()\n```\n\n文档：[连接到 MCP 服务器](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconnecting-to-mcp-servers) • 示例：[`examples\u002Fbasic\u002Fmcp_server_aggregator`](.\u002Fexamples\u002Fbasic\u002Fmcp_server_aggregator\u002F)。\n\n## 云部署\n\n部署到 mcp-agent 云平台，享受托管的 Temporal 执行、密钥管理和 HTTPS 的 MCP 端点服务。\n\n```bash\nuvx mcp-agent login\nuvx mcp-agent deploy my-agent\nuvx mcp-agent cloud apps list\n```\n\n文档：[云概览](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Foverview) • [部署快速入门](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fdeployment-quickstart) • 示例：[`examples\u002Fcloud`](.\u002Fexamples\u002Fcloud\u002F)。\n\n## 示例\n\n浏览 [gallery.md](gallery.md)，查看按概念分组的可运行示例、演示视频和社区项目。每个条目都注明了对应的文档页面以及在本地运行所需的命令。\n\n## 常见问题解答\n\n### 使用 mcp-agent 的核心优势是什么？\n\nmcp-agent 提供了一种简化的途径，用于利用 **MCP**（模型上下文协议）服务器公开的功能来构建 AI 代理。\n\nMCP 层次较低，而该框架负责处理与服务器连接、LLM 交互、外部信号（如人工输入）的处理，以及通过持久化执行支持持久状态等底层机制。这使开发者能够专注于 AI 应用的核心业务逻辑。\n\n核心优势：\n\n- 🤝 **互操作性**：确保任何由任意数量 MCP 服务器暴露的工具都能无缝集成到您的代理中。\n- ⛓️ **可组合性与可定制性**：实现了定义明确的工作流，同时以可组合的方式支持复合工作流，并允许在模型提供商、日志记录、编排器等方面进行完全自定义。\n- 💻 **程序化控制流**：让开发变得更简单，您只需编写代码，而无需考虑图、节点和边的概念。对于分支逻辑，直接使用 `if` 语句；对于循环，则使用 `while` 循环。\n- 🖐️ **人工输入与信号**：支持暂停工作流以等待外部信号，例如人工输入，这些信号会以工具调用的形式暴露给代理。\n\n### 使用 mcp-agent 是否需要 MCP 客户端？\n\n不需要。您可以随时随地使用 mcp-agent，因为它会为您自动创建 MCP 客户端。这使得您能够在 Claude Desktop 等 MCP 主机之外，直接利用 MCP 服务器。\n\n以下是设置 mcp-agent 应用程序的几种方式：\n\n#### MCP-Agent 服务器\n\n您可以将 mcp-agent 应用程序本身作为 MCP 服务器公开（参见 [示例](.\u002Fexamples\u002Fmcp_agent_server)），从而使 MCP 客户端能够通过 MCP 服务器的标准工具 API 与复杂的 AI 工作流进行交互。这实际上就是一个“服务器中的服务器”。\n\n#### MCP 客户端或主机\n\n您也可以直接将 mcp-agent 嵌入到 MCP 客户端中，以管理跨多个 MCP 服务器的编排工作。\n\n#### 独立运行\n\n您还可以以独立方式使用 mcp-agent 应用程序（即它们不属于任何 MCP 客户端）。[示例](\u002Fexamples\u002F)均为独立应用程序。\n\n### 如何部署到云端？\n\n登录后运行 `uvx mcp-agent deploy \u003Capp-name>`。CLI 会打包您的项目、配置密钥，并暴露一个由持久化 Temporal 运行时支持的 MCP 端点。请参阅 [云快速入门](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002F\ncloud)，获取分步截图和 CLI 输出。\n\n### API 参考文档在哪里？\n\n所有类、装饰器和 CLI 命令都在 [docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com) 上进行了文档化。[API 参考](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference)和 [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt) 文件旨在方便 LLM 或其他工具轻松地理解整个 API 表面。\n\n### 让我分享一个有趣的事实吧！\n\n我曾考虑将这个项目命名为 _silsila_（سلسلہ），在乌尔都语中意为“事件链”。最终选择了更直白的 mcp-agent，不过项目中仍有一个彩蛋，向 silsila 致敬。\n\n## 贡献\n\n我们欢迎各种形式的贡献——修复 bug、新增示例、撰写文档或提出功能需求。请从 [CONTRIBUTING.md](.\u002FCONTRIBUTING.md) 开始，发起讨论，或加入我们的 [Discord](https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent) 社区。\n\n没有众多开源贡献者的不懈努力，mcp-agent 核心不可能实现。感谢大家！\n\n\u003Cp align=\"center\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fgraphs\u002Fcontributors\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_readme_db1fb3c93bff.png\" alt=\"贡献者面孔\" \u002F>\n \u003C\u002Fa>\n\u003C\u002Fp>","# mcp-agent 快速上手指南\n\n`mcp-agent` 是一个基于 **Model Context Protocol (MCP)** 的简洁、可组合框架，旨在帮助开发者构建高效的 AI Agent。它完整实现了 MCP 协议，自动管理服务器连接生命周期，并支持从简单脚本到基于 Temporal 的生产级持久化工作流。\n\n## 环境准备\n\n在开始之前，请确保你的开发环境满足以下要求：\n\n* **操作系统**: Linux, macOS 或 Windows (WSL 推荐)\n* **Python**: 版本 3.10 或更高\n* **包管理器**: 推荐使用 [`uv`](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) (极速 Python 包管理工具)，也可使用 `pip`\n* **LLM API Key**: 准备好 OpenAI、Anthropic 或其他支持的 LLM 供应商的 API Key\n* **Node.js (可选)**: 如果需要使用基于 npm 的 MCP 服务器（如文件系统服务），请确保已安装 Node.js\n\n> **国内开发者提示**：\n> * 安装 `uv` 时若遇网络问题，可使用国内镜像或二进制文件直接下载。\n> * 使用 `pip` 安装时，建议配置清华源或阿里源加速：`pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple ...`\n\n## 安装步骤\n\n推荐使用 `uv` 来初始化和管理工作区，它能更快速地处理依赖。\n\n### 1. 初始化项目\n\n```bash\n# 创建项目目录并进入\nmkdir hello-mcp-agent && cd hello-mcp-agent\n\n# 使用 uv 初始化项目\nuv init\n\n# 添加 mcp-agent 核心库及 OpenAI 支持 (可根据需要替换为 anthropic, google 等)\nuv add \"mcp-agent[openai]\"\n```\n\n如果不使用 `uv`，也可以使用 pip 安装：\n\n```bash\npip install \"mcp-agent[openai]\"\n```\n\n### 2. 配置密钥\n\n在项目根目录下创建 `mcp_agent.secrets.yaml` 文件（该文件应加入 `.gitignore`），填入你的 LLM API Key：\n\n```yaml\nopenai:\n api_key: \"sk-your-openai-api-key-here\"\n```\n\n或者直接将密钥设置为环境变量：\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\n```\n\n## 基本使用\n\n以下是一个最小化的示例，展示如何创建一个名为 \"finder\" 的 Agent。该 Agent 能够调用 `filesystem` (文件系统) 和 `fetch` (网络获取) 这两个 MCP 服务器来回答问题。\n\n### 1. 创建配置文件 `mcp_agent.config.yaml`\n\n定义 Agent 可以使用的 MCP 服务器。这里我们配置了官方提供的 `fetch` 和 `filesystem` 服务。\n\n```yaml\nexecution_engine: asyncio\nlogger:\n transports: [console]\n level: info\n\nmcp:\n servers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n filesystem:\n command: \"npx\"\n args:\n [\n \"-y\",\n \"@modelcontextprotocol\u002Fserver-filesystem\",\n \".\" \n ]\n # 注意：将 \".\" 替换为你希望 Agent 访问的具体目录路径，例如 \"\u002FUsers\u002Fyourname\u002Fdocuments\"\n\nopenai:\n default_model: gpt-4o\n```\n\n### 2. 编写代码 `main.py`\n\n```python\nimport asyncio\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\n# 初始化应用\napp = MCPApp(name=\"hello_world\")\n\nasync def main():\n async with app.run():\n # 定义 Agent\n agent = Agent(\n name=\"finder\",\n instruction=\"Use filesystem and fetch to answer questions.\",\n server_names=[\"filesystem\", \"fetch\"],\n )\n \n async with agent:\n # 挂载 LLM (默认使用配置中的 gpt-4o)\n llm = await agent.attach_llm(OpenAIAugmentedLLM)\n \n # 执行任务：读取本地文件\n answer = await llm.generate_str(\"Summarize README.md in two sentences.\")\n print(f\"Summary: {answer}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 3. 运行 Agent\n\n确保当前目录下有 `README.md` 文件（或修改代码中的文件名），然后运行：\n\n```bash\nuv run main.py\n```\n\n**输出示例：**\nAgent 将自动启动配置的 MCP 服务器，调用工具读取文件，并返回由 LLM 生成的总结内容。\n\n---\n\n**下一步建议**：\n* 查看 `examples` 目录获取更多复杂模式（如 Map-Reduce、路由、评估器优化器等）。\n* 访问 [官方文档](https:\u002F\u002Fdocs.mcp-agent.com) 了解如何部署到云端或使用 Temporal 实现持久化执行。","某电商公司的数据工程师需要构建一个智能助手，自动分析每日销售日志并查询库存数据库，最终生成包含改进建议的日报。\n\n### 没有 mcp-agent 时\n- **连接管理繁琐**：开发者需手动编写大量代码来维持与文件系统、SQL 数据库等多个 MCP 服务器的长连接，处理断线重连逻辑极易出错。\n- **工作流僵化**：实现“先映射所有日志文件，再归约汇总数据”的复杂逻辑时，缺乏标准模式，导致代码耦合度高，难以复用或调整顺序。\n- **状态恢复困难**：若任务在处理大文件时因网络波动中断，整个进程必须从头开始，无法暂停或从断点续跑，浪费计算资源。\n- **调试成本高**：由于生命周期管理分散在业务逻辑中，排查是模型推理错误还是服务器连接故障变得异常耗时。\n\n### 使用 mcp-agent 后\n- **自动化生命周期管理**：mcp-agent 全自动处理底层 MCP 服务器的连接建立与维护，开发者只需声明所需服务（如 `filesystem`, `sql`），无需关心连接细节。\n- **组合式模式开发**：直接调用内置的 Map-Reduce 或 Orchestrator 等经过验证的模式，像搭积木一样快速构建“读取 - 分析 - 写入”的稳健工作流。\n- **原生持久化支持**：基于 Temporal 集成，任务遇到异常可自动暂停，环境恢复后无缝从断点继续执行，确保长运行任务的可靠性。\n- **清晰的责任分离**：业务逻辑专注于指令设计，底层通信由框架屏蔽，使得定位问题和迭代功能变得直观高效。\n\nmcp-agent 通过标准化连接管理与提供可组合的工作流模式，让开发者能以最低成本构建出既健壮又易于维护的生产级 AI 代理。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flastmile-ai_mcp-agent_f72a1ecf.png","lastmile-ai","lastmile ai","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Flastmile-ai_7c64b9f1.png","Building the first Cognitive Computer to empower people, teams and organizations.",null,"support@lastmileai.dev","lastmile","https:\u002F\u002Flastmileai.dev\u002F","https:\u002F\u002Fgithub.com\u002Flastmile-ai",[83,87,91,95,99,102],{"name":84,"color":85,"percentage":86},"Python","#3572A5",99.7,{"name":88,"color":89,"percentage":90},"TypeScript","#3178c6",0.2,{"name":92,"color":93,"percentage":94},"CSS","#663399",0.1,{"name":96,"color":97,"percentage":98},"Shell","#89e051",0,{"name":100,"color":101,"percentage":98},"Makefile","#427819",{"name":103,"color":104,"percentage":98},"HTML","#e34c26",8273,831,"2026-04-18T22:24:14","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":112,"python":113,"dependencies":114},"该工具是一个基于 Model Context Protocol (MCP) 的 Python 框架，主要用于构建 AI Agent，本身不涉及大型模型训练或推理的重型计算，因此无特殊 GPU 需求。推荐使用 'uv' 进行项目依赖管理。支持通过 Temporal 实现持久化执行。配置 MCP 服务器时可能需要安装 Node.js (用于 npx 命令) 或其他语言运行时。API 密钥需配置在 mcp_agent.secrets.yaml 文件或环境变量中。","3.10+",[65,115,116,117,118,119,120,121],"uv","openai","anthropic","google-generativeai","azure-identity","boto3","temporalio",[13,14,35,15],[124,125,126,127,128,129,130,131],"agents","ai","ai-agents","llms","mcp","model-context-protocol","python","llm","2026-03-27T02:49:30.150509","2026-04-20T04:08:11.089947",[135,140,145,150,155,160],{"id":136,"question_zh":137,"answer_zh":138,"source_url":139},43819,"如何在 mcp_agent.config.yaml 中为服务器配置环境变量（env）？","在 v0.0.7 版本之前，直接在 YAML 中添加 `env` 字段可能无法生效。请确保将 `mcp-agent` 升级到最新的 PyPI 包（v0.0.7 或更高版本），该版本已修复此问题。升级后，您可以在服务器配置中直接使用 `env` 键来定义环境变量，格式如下：\n\nservers:\n fetch:\n command: \"uvx\"\n args: [\"mcp-server-fetch\"]\n env:\n TOKEN: \"xxx\"","https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fissues\u002F20",{"id":141,"question_zh":142,"answer_zh":143,"source_url":144},43820,"升级 Python SDK 至 v1.8.0 后出现 \"SessionMessage object has no attribute model_dump_json\" 错误导致工作流挂起，如何解决？","这是由于 mcp-agent 与新版 python-sdk (v1.8.0) 的兼容性问题导致的。维护者已在 v0.0.21 版本中推送了修复补丁。请将 `mcp-agent` 升级到 v0.0.21 或更高版本以解决此问题。","https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fissues\u002F182",{"id":146,"question_zh":147,"answer_zh":148,"source_url":149},43821,"使用代码编程方式配置 Settings 时，为什么仍然提示找不到服务器或需要配置文件？","这是因为 Agent 的上下文（context）初始化时机问题。如果在 `async with app.run()` 代码块之外初始化 Agent，它会尝试创建一个不包含编程式设置的新上下文，从而导致找不到服务器。\n\n解决方案：务必在 `async with app.run():` 代码块内部定义和初始化您的 Agent。这样 Agent 才能正确继承 MCPApp 中定义的编程式设置和服务器注册表。\n\n示例：\nasync with app.run():\n agent = MyAgent() # 在此块内初始化","https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fissues\u002F298",{"id":151,"question_zh":152,"answer_zh":153,"source_url":154},43822,"在使用 Claude 和 Meilisearch 进行多轮对话时，Agent 偶尔会卡死或停止响应，可能的原因是什么？","这种情况通常由多线程环境下的竞争条件或超时设置引起。建议采取以下措施：\n1. 确保使用的是包含多线程修复的最新版本 mcp-agent。\n2. 检查 Web 服务器（如 Uvicorn）的 WebSocket 超时设置。如果 Agent 调用耗时较长（例如涉及重试），默认超时可能导致连接中断。建议将 Uvicorn 的超时时间增加（例如设置为 2 分钟）：`uvicorn --timeout-keep-alive 120`。","https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fissues\u002F287",{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},43823,"mcp-agent 是否支持 Streamable HTTP 传输协议？","项目正在积极集成和支持 Streamable HTTP 协议（作为 SSE 的替代方案）。用户可以通过运行特定的示例（如 `mcp-simple-streamablehttp-stateless`）来测试相关功能。如果遇到无状态服务器无法获取工具等问题，建议查看最新的 Issue 讨论或提供完整的 JSONL 日志以便调试。","https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fissues\u002F180",{"id":161,"question_zh":162,"answer_zh":163,"source_url":154},43824,"在公司防火墙后运行 Agent 时遇到通信错误或卡死，如何调试？","如果在防火墙后运行出现卡死，可能是通信超时或未处理的网络错误。调试建议：\n1. 利用 mcp_agent 提供的详细调试输出（debug output），查找进程具体在哪个步骤停止。\n2. 检查是否为 WebSocket 或 HTTP 请求的超时问题，尝试增加相关服务的超时阈值。\n3. 确认是否是多线程环境下的资源竞争问题，并更新至包含并发修复的最新版本。",[165,170,175,180,185,190,195,200,205],{"id":166,"version":167,"summary_zh":168,"released_at":169},351245,"v0.0.21","小补丁更新，使 mcp-agent 兼容最新的 MCP 包 v1.8.0\n\n## 变更\n- 将 MCP 包依赖升级至 v1.8.0，并包含相应的热修复（8de63b4）\n- 添加 `OllamaAugmentedLLM`，并确保其在需要结构化类型生成的复杂工作流中正常运行\n- 修复 basic\u002Fdecorator\u002Fyaml 中服务器的绝对路径问题 @Deathn0t (#181)\n- 移除自定义 WebSocket 和 stdio 客户端，改用 MCP 包自带的默认客户端（9d92ef0）","2025-05-09T16:54:50",{"id":171,"version":172,"summary_zh":173,"released_at":174},351246,"v0.0.18","感谢所有精彩的社区贡献！我们即将对 mcp-agent 进行一次重大更新。您可以通过 `feature\u002Ftemporal_prime` 和 `feature\u002Fapp_server` 分支关注进展。v0.0.18 包含若干 bug 修复，并新增了为 OpenAI AugmentedLLM 指定自定义 HTTP 客户端的功能（感谢 @blevz！）。\n\n## 变更\n- 添加为 OpenAI 配置 http_client 的功能 @blevz (#173)\n\n## 🐛 Bug 修复\n\n- 修复：为 AzureAugmentedLLM 添加系统提示处理 @StreetLamb (#148)\n- 修复：_reasoning 标志用于设置 API 参数 @Pythonista7 (#139)\n- 修复 MCP 浏览器代理 README 中的拼写错误 @andrew-lastmile (#175)\n- 修复 README 中的失效链接 @andrew-lastmile (#167)\n\n## 生活质量提升\n- 更新并重构 examples 目录 @andrew-lastmile (#166)\n- 重构 examples 目录 @andrew-lastmile (#144)\n- SSE 连接示例及 WebSocket 的其他修复 @saqadri (#143)\n- MCP-Agent：集成 MCP Puppeteer，实现基于控制台的浏览 @andrew-lastmile (#137)\n- 功能：更新 mcp_playwright_agent 示例 @Haniehz1 (#156)\n\n","2025-05-02T02:24:00",{"id":176,"version":177,"summary_zh":178,"released_at":179},351247,"v0.0.16","小版本更新，新增对使用 SSE 和 WebSocket 的 MCP 服务器的完善支持，支持自定义 HTTP 头，并增加了对 OpenAI o4 模型的支持。\n\n特别感谢 @pmohan6 完成了 WebSocket 支持（并附带测试），以及 @aloktiagi 在发布当天迅速添加了 o4 支持。\n\n## 变更\n- 功能：支持 WebSocket 连接，并可在 WebSocket 和 SSE 连接中传递 HTTP 头 @pmohan6 (#116)\n- 增加对 o4 推理模型的支持 @aloktiagi (#142)\n","2025-04-17T23:05:51",{"id":181,"version":182,"summary_zh":183,"released_at":184},351248,"v0.0.15","本次发布贡献者人数创历史新高！感谢所有优秀的开源贡献者，正是你们的帮助让 `mcp-agent` 不断完善。特别鸣谢 @StreetLamb，他为本次发布添加了多项关键功能，包括对 **Azure** OpenAI、AWS **Bedrock** 以及 Google **Gemini** 模型的支持！\n\n## 亮点\n- AWS Bedrock 支持 @StreetLamb (#85)\n- Google Gemini 支持 @StreetLamb (#129)\n- Azure OpenAI 支持 @StreetLamb (#90)\n- 支持 mcp v1.6.0（最新版本）\n\n## 下一步计划\n我们将在下周对 `mcp-agent` 进行一次重大升级。**如果您愿意参与贡献，以下是我们的优先事项**：\n- 为异步代理编排添加 Temporal 工作流执行器支持 (#14)\n- 分布式追踪与可观ability (#10)\n- 高级 MCP 功能（资源管理、提示词、采样策略和记忆模块）\n\n## 变更\n- 修复使用 AWS Bedrock Nova 模型时的工具调用问题 @StreetLamb (#134)\n- 添加对 Gemini 模型的支持 @StreetLamb (#129)\n- 修正：在 AzureAugmentedLLM 中正确处理消息，确保消息列表能够正常扩展 @StreetLamb (#125)\n- 更新 GitHub 到 Slack 的 Agent，并集成 GitHub MCP Server @andrew-lastmile (#122)\n- 修复 OpenAI ChatCompletion 消息内容格式问题 @askme765cs (#106)\n- 修复：传递给代理的函数现可作为工具使用 @rholinshead (#120)\n- 修复：重构 OpenAIAugmentedLLM 中助手消息的参数 @softage0 (#117)\n- 更新 mcp_basic_azure_agent 的 README.md @lucinvitae (#119)\n- 修复：将 boto3-stubs 移至开发依赖 @StreetLamb (#110)\n- 修复：在 augmented_llm_bedrock 中使用 TYPE_CHECKING 进行条件导入 @StreetLamb (#109)\n- 修复：在 AnthropicAugmentedLLM 中，当达到最大迭代次数时，改进最终响应的生成 @dragon1086 (#99)\n- 修复：更新 AnthropicAugmentedLLM 中工具结果内容的格式化 @StreetLamb (#95)\n- 更新设置获取逻辑，优先使用 `config_path` 配置及密钥 @jtanningbed (#86)\n- 在 Bedrock 设置中添加对 AWS 配置文件的支持 @StreetLamb (#102)\n- 增加一个从 GitHub 到 Slack 的 Agent 示例 @andrew-lastmile (#98)\n- 添加 Azure 支持 @StreetLamb (#90)\n- 修复示例代码 @boxbag (#92)\n- 修复在向 OpenAI 发送请求时因包含 name 参数而导致的验证错误 @boxbag (#88)\n- 添加 AWS Bedrock 支持 @StreetLamb (#85)\n- 修复重复的系统消息（提示词缓存）@recallfuture (#89)\n- 针对 mcp > 1.5.0 的热修复，以及来自 fast-agent 仓库的多项更新 @saqadri (#84)\n\n## 🐛 Bug 修复\n\n- 修复 AzureAugmentedLLM 中 generate_structured_output 函数及 from_mcp_message_param 相关问题 @StreetLamb (#131)\n- 修复：修正 BedrockAugmentedLLM 中扩展消息的逻辑 @StreetLamb (#130)","2025-04-16T23:54:58",{"id":186,"version":187,"summary_zh":188,"released_at":189},351249,"v0.0.11","小规模 QoL 更新\n\n## 变更\n- 将 instructor 版本升级至 1.7.7，以修复 https:\u002F\u002Fgithub.com\u002Finstructor-ai\u002Finstructor\u002Fissues\u002F1412\n- 修复 README 中的结构和代码块问题 @skyduy (#71)\n- 修复 README 中的 Swarm 代理示例 @sayanarijit (#70)\n- 对示例进行小幅更新\n","2025-03-25T15:14:51",{"id":191,"version":192,"summary_zh":193,"released_at":194},351250,"v0.0.10","## 变更\n- 改进工具调用中的服务器名称解析 @Henry-Jessie (#65)\n- 向 MCPApp 添加 session_id，并在系统中进行传递 @corroleaus (#63)\n\n感谢社区持续帮助构建这个项目！下一个版本将是一个重大更新。","2025-03-20T17:54:51",{"id":196,"version":197,"summary_zh":198,"released_at":199},351251,"v0.0.9","在多个示例中进行了用户体验优化、错误修复，并新增了由 @MattMorgis 实现的功能，支持同时配置多个日志记录器。感谢社区各位的精彩贡献！\n\n## 变更\n- 修复示例 `streamlit_mcp_rag_agent` 中与最新 `mcp-server-qdrant` 版本相关的问题 @venticello (#59)\n- 放宽 NumPy 的依赖约束，现要求 NumPy ≥ 2.1.3 @Nicba1010 (#52)\n- 日志更新 @MattMorgis (#49)\n- 多传输日志记录 @MattMorgis (#42)\n- 修复因实例化 `CallToolResult` 类而引发的 bug @meerkat-citronella (#48)","2025-03-15T22:35:16",{"id":201,"version":202,"summary_zh":203,"released_at":204},351252,"v0.0.8","特此将本次发布献给 @evalstate，他独自一人推动了核心框架的多项卓越更新，并创建了一系列令人惊叹的示例。感谢您！详细内容如下：\n\n## 变更\n- 为 mcp-agent 添加 MCP 根目录支持 @evalstate (#18)。更多详情请参阅 [mcp_root_test](https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp_root_test) 示例。\n- 新增 ProgressLogger，用于捕获日志事件流，将其转换为进度信息 @evalstate (#18)。\n- 增加中间进度报告功能，以更好地了解代理和工具的执行进度 @evalstate (#18)。\n- 如果配置中存在，则从配置中获取 Anthropic 的默认模型 @MattMorgis (#39)。\n- 在初始化时将上下文全局存储 @andersenthomas98 (#37)。\n- 修复 finder_agent.py 的 README 示例 @roterski (#28)。\n- 进度报告功能 @evalstate (#18)。\n\n感谢所有优秀的社区贡献者，正是你们的努力才使得本次发布成为可能。","2025-03-06T03:39:20",{"id":206,"version":207,"summary_zh":208,"released_at":209},351253,"v0.0.7","## 变更\n- 确保 OpenAI 客户端始终使用 base_url @mcolyer (#26)\n- 修复在使用 OpenAIAugmentedLLM 时出现的重复工具调用消息问题 @StreetLamb (#22)\n- 支持与 OpenAI 格式兼容的模型 @StreetLamb (#21)\n- 添加 MCP 代理服务器示例 @StreetLamb (#7)\n- 修复 streamlit_mcp_rag_agent 示例中的 NameError 错误 @StreetLamb (#9)\n- 添加 Streamlit 版本的 MCP RAG 代理示例 @StreetLamb (#4)\n- 示例：更新 marimo 笔记本的 README 文件 @akshayka (#6)\n- 示例：添加 marimo 笔记本（基础版 MCP 代理）@akshayka (#5)\n- 添加包含配置和依赖项的 Streamlit 版本 MCP 代理示例 @StreetLamb (#3)\n- 修复\u002Fsecrets 跟踪问题 @evalstate (#2)\n- 首次提交：为 mcp-agent 创建初始框架 @saqadri (#1)\n\n感谢所有优秀的社区贡献者，正是你们的努力才使得本次发布成为可能。","2025-02-19T01:09:39"]