mcp-agent
用 MCP 和可组合工作流构建 Python 智能体应用。
按维度查看评分与理由
证据显示：框架支持通过server_names限制工具访问，提供human_input_callback机制，配置中明确分离secrets文件，依赖列表包含安全相关库（如opentelemetry），SECURITY.md提供漏洞报告渠道，但未发现自动回滚机制，发布者身份未验证。扣分原因：缺少对权限最小化的明确文档，用户确认机制仅作为可选回调，数据流透明度不足，敏感数据处理细节有限，依赖安全未提供漏洞扫描证据，外部影响未明确说明，回滚机制缺失，来源归属仅依赖作者信息。
证据显示：代码库包含测试文件（如test_agent.py）和CI工作流（checks.yml），依赖版本固定，但失败消息处理未充分展示。扣分原因：自一致性有测试支持但未全面覆盖，依赖可用性有版本锁定但未验证，失败消息仅部分体现。
证据显示：README提供多种使用场景（如MCP server、Temporal、Cloud），明确列出支持的模式和功能，配置灵活，但未明确边界。扣分原因：受众和场景描述充分，能力边界有说明但不够详细，触发精度有示例但未系统化，环境适配有配置示例但未全面。
证据显示：README结构清晰，安装说明详细，命名稳定（如mcp-agent），提供示例和FAQ，许可证为Apache-2.0，版本号在pyproject.toml中，有SECURITY.md和贡献指南。扣分原因：已知限制未明确列出，版本变更日志未提供，维护责任有作者信息但未明确。
证据显示：输出格式有示例（如generate_str），提供多种工作流模式，成本效益有说明（如生产就绪）。扣分原因：输出可用性有示例但未全面，边际价值有说明但未量化，成本效益有描述但未提供具体数据。
证据显示：README中的声明有文档链接，但未提供独立验证。扣分原因：声明可追溯性有限，跨来源验证不足，事实与推断分离不明确。
- 发布者身份未验证，需谨慎评估供应链风险。
- 未发现自动回滚机制，生产环境需自行实现。
- 依赖安全未提供漏洞扫描证据，建议使用前进行安全审计。
- 已知限制未明确列出，可能影响部署决策。
这个 Agent 能做什么，适合哪些场景？
mcp-agent 是一个 Python 框架，用于通过 Model Context Protocol（MCP）构建智能体和工作流。其核心运行时 MCPApp 负责加载配置、初始化日志与执行引擎，并管理 MCP 服务器连接的生命周期。Agent 将指令与可调用的 MCP 服务器组合，Augmented LLM 为模型调用补充工具、记忆和结构化输出能力。项目提供并行、路由、编排器-工作者、评估器-优化器和 Swarm 等可组合工作流模式，并可在 asyncio 与 Temporal 执行引擎间切换。应用既可作为独立 Python 程序运行，也能通过 create_mcp_server_for_app 暴露为标准 MCP 服务器；README 还记录了 Cloud 部署路径。
开发者创建 MCPApp，在 mcp_agent.config.yaml 中声明如 fetch、filesystem 的 MCP 服务器，然后定义带有 server_names 的 Agent。进入 async with app.run() 和 async with agent 上下文后，Agent 会初始化服务器连接；调用 agent.attach_llm(OpenAIAugmentedLLM) 可获得 generate、generate_str 和 generate_structured，用模型调用已连接服务器提供的工具。create_parallel_llm、create_router_llm、create_orchestrator 和 create_evaluator_optimizer_llm 等工厂函数可组装更高层流程。将 execution_engine 设为 temporal 后，可配合 create_temporal_worker_for_app 运行持久化工作流；用 create_mcp_server_for_app 则可把 app 的 @app.tool 和工作流输出给 MCP 客户端。
- Python 后端团队需要让一个研究助手通过 filesystem 和 fetch MCP 服务器读取本地文件、抓取网页并生成摘要时。
- 需要按意图把请求分配给不同 AgentSpec、MCP 服务器或函数的应用团队。
- 要把多个专家子任务并行执行、再聚合成一份报告的分析工作流开发者。
- 需要暂停流程等待人工批准或补充信息，并在 Temporal 中恢复执行的业务自动化团队。
- 希望把现有 Python 工具或工作流作为标准 MCP 服务器提供给 Claude Desktop、Cursor 或自定义 MCP 客户端的开发者。
这个 Agent 有哪些优点和局限？
- MCPApp 和 Agent 直接处理 MCP 服务器连接生命周期，应用代码无需自行创建和维护这些连接。
- 同一套工作流注解可用于 asyncio 与 Temporal；切换到 Temporal 后可获得暂停、恢复、重试和持久化历史能力。
- 提供明确的可组合模式工厂，包括并行 Map-Reduce、路由、意图分类、编排器-工作者、评估器-优化器与 Swarm。
- 可将 MCPApp 通过 create_mcp_server_for_app 作为标准 MCP 服务器暴露，便于接入支持 MCP 的客户端。
- 示例以异步 Python、uv 和 YAML 配置为中心；采用其他语言或同步执行模型需要自行集成。
- OpenAI 最小示例依赖 OPENAI_API_KEY 或 secrets 文件；不同模型提供商还需安装对应可选依赖并调整配置。
- Temporal 持久化执行需要将 execution_engine 设为 temporal，并运行额外的 Temporal worker。
- Cloud 部署在 README 中标为 Beta，且其定价、配额与托管运行环境细节未在提供材料中说明。
如何安装或部署这个 Agent？
先安装 Python 与 uv。创建项目后执行：
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"也可使用：
pip install mcp-agentOpenAI 示例需要在 mcp_agent.secrets.yaml 中配置 API 密钥，或设置 OPENAI_API_KEY。若使用其他模型提供商，README 列出可选额外依赖："mcp-agent[openai, anthropic, google, azure, bedrock]"。
如何使用这个 Agent？
创建 main.py，使用 MCPApp、Agent 和 OpenAIAugmentedLLM；在 Agent 中设置 server_names=["fetch", "filesystem"]。在 mcp_agent.config.yaml 中为这两个服务器配置命令及参数，例如 fetch 使用 uvx mcp-server-fetch，filesystem 使用 npx -y @modelcontextprotocol/server-filesystem 和允许访问的目录。随后运行：
uv run main.py最小调用流程是在 async with app.run() 内创建 Agent，在 async with agent 内执行 llm = await agent.attach_llm(OpenAIAugmentedLLM)，再调用 await llm.generate_str("Summarize README.md in two sentences.")。如需生成项目骨架，可使用 uvx mcp-agent init --template basic --dir my-first-agent。
这个 Agent 与同类方案有什么区别？
与仅作为 MCP 主机的 Claude Desktop 或 Cursor 相比，mcp-agent 也可以作为独立 Python 应用运行，并通过 create_mcp_server_for_app 将自身工具和工作流反向暴露给这些 MCP 客户端。