mcp-agent 项目说明书

Doramagic 项目包 · 项目说明书

mcp-agent 项目

使用 Model Context Protocol 和简洁的工作流模式构建高效的 Agent

项目概览

mcp-agent 是由 lastmile-ai 维护的开源 Python 框架，定位为基于 Model Context Protocol (MCP) 构建生产级智能体的运行时。其核心理念是将 MCP 服务器作为工具与数据源暴露给大语言模型（LLM），并在此之上提供经过工程化打磨的执行原语，使开发者能够专注于业务逻辑而非基础设施细节。

章节 相关页面

继续阅读本节完整说明和来源证据。

核心定位与设计理念

mcp-agent 是由 lastmile-ai 维护的开源 Python 框架，定位为 基于 Model Context Protocol (MCP) 构建生产级智能体的运行时。其核心理念是将 MCP 服务器作为工具与数据源暴露给大语言模型（LLM），并在此之上提供经过工程化打磨的执行原语，使开发者能够专注于业务逻辑而非基础设施细节。

框架在 README 中明确强调"Pythonic API with decorators"的易用性，以及面向生产的特性，例如 Temporal-backed durability（基于 Temporal 的持久化） 和 结构化日志，这使得长时、多步骤的代理任务具备可恢复性与可观测性。资料来源：README.md。从 v0.0.10 开始引入 session_id 并贯穿整个系统，进一步强化了会话追踪能力。资料来源：v0.0.10 release notes。

核心架构与组件

mcp-agent 采用分层架构，主要由以下几部分组成：

MCPApp：应用入口与生命周期管理容器，负责装配 MCP 服务器连接、LLM 适配器与工作流实例，并通过 session_id 串联请求上下文。资料来源：README.md。
AugmentedLLM：LLM 适配层，统一封装不同厂商模型（包括 OpenAI、Anthropic、Azure OpenAI、AWS Bedrock、Google Gemini、Ollama），在 v0.0.21 中加入了 OllamaAugmentedLLM 以支持结构化类型生成。资料来源：v0.0.21 release notes、资料来源：v0.0.15 release notes。
Workflows（工作流原语）：包括 parallel（并行）、sequential（顺序）、orchestrator-workers（编排器-工作者）、router（路由器）、evaluator-optimizer（评估-优化）等模式，封装在 src/mcp_agent/workflows/ 目录下的独立模块中。资料来源：src/mcp_agent/workflows/orchestrator/README.md、资料来源：src/mcp_agent/workflows/parallel/README.md。
CLI：src/mcp_agent/cli/ 提供项目脚手架、模板初始化与本地调试命令。资料来源：src/mcp_agent/cli/README.md。

graph TD
    A[MCPApp] --> B[AugmentedLLM]
    A --> C[MCP Servers]
    A --> D[Workflows]
    D --> D1[Parallel]
    D --> D2[Sequential]
    D --> D3[Orchestrator]
    D --> D4[Router]
    D --> D5[Evaluator-Optimizer]
    B --> E[LLM Providers]
    E --> E1[OpenAI]
    E --> E2[Anthropic]
    E --> E3[Bedrock / Gemini / Ollama]

主要功能特性

多厂商 LLM 支持：通过 AugmentedLLM 抽象层屏蔽差异；v0.0.15 起逐步集成 Azure OpenAI、AWS Bedrock、Google Gemini，v0.0.21 补齐 Ollama。资料来源：v0.0.15 release notes、资料来源：v0.0.21 release notes。
MCP 传输灵活：自 v0.0.16 起支持 SSE 与 WebSocket 连接，并允许通过 HTTP headers 传递鉴权信息。资料来源：v0.0.16 release notes。
装饰器风格 API：使用 @app.workflow 等装饰器即可将异步函数注册为工作流节点，降低样板代码。资料来源：README.md。
示例库：examples/ 目录收录了从基础到高级的示例，覆盖 Basic、Decorator、YAML 三种使用方式。资料来源：examples/README.md。
深度编排：deep_orchestrator 模块针对复杂多步骤任务提供增强的推理与子任务调度能力。资料来源：src/mcp_agent/workflows/deep_orchestrator/README.md。

社区生态与发展

社区方面，mcp-agent 已被外部项目用于生产场景，例如 ApeRAG（基于 mcp-agent 构建的 GraphRAG 平台）。资料来源：Issue #426。与此同时，社区也反馈了若干待完善的方向：

流式输出（streaming token output）仍是关注点，见 Issue #307。
LMStudio 等本地推理平台的支持请求，见 Issue #596。
可靠性模式：包括幂等性、evaluator-optimizer 终止条件与部分失败后的恢复，见 Issue #640。
安全审计与跨组织代理身份：分别见 Issue #641 与 Issue #673。
缺失的工作流模式：例如对抗式/辩论模式（两个代理对立论证），见 Issue #668。

版本演进方面，项目目前迭代至 v0.0.21，与上游 MCP v1.8.0 保持兼容；据 v0.0.18 release notes，团队正在 feature/temporal_prime 与 feature/app_server 分支上筹备重大更新。资料来源：v0.0.18 release notes、资料来源：v0.0.21 release notes。依赖声明见 pyproject.toml，可作为对接下游环境的依据。资料来源：pyproject.toml。

来源：https://github.com/lastmile-ai/mcp-agent / 项目说明书

Server 模块

Server 模块（路径：src/mcpagent/server/）为 mcp-agent 提供远程化部署能力。它把本地 MCPApp 中声明的代理（Agent）、工具（Tool）以及工作流（Workflow）封装为可通过 HTTP/JSON-RPC 调用的端点，使同一份代理配置既能在本地进程内运行，也能被其他进程或组织内的客户端远程复用——这恰好对应社区议题 673 所讨...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 主服务入口 appserver.py

继续阅读本节完整说明和来源证据。

章节 类型契约 appservertypes.py

继续阅读本节完整说明和来源证据。

章节 身份验证 tokenverifier.py

继续阅读本节完整说明和来源证据。

模块概述

Server 模块（路径：src/mcp_agent/server/）为 mcp-agent 提供远程化部署能力。它把本地 MCPApp 中声明的代理（Agent）、工具（Tool）以及工作流（Workflow）封装为可通过 HTTP/JSON-RPC 调用的端点，使同一份代理配置既能在本地进程内运行，也能被其他进程或组织内的客户端远程复用——这恰好对应社区议题 #673 所讨论的「跨组织编排」场景。模块整体基于异步 Web 框架（FastAPI/Starlette 风格）实现，并通过依赖注入把 Context、会话、LLM 等运行时对象绑定到具体请求的处理函数中。资料来源：src/mcp_agent/server/app_server.py:1-40、src/mcp_agent/server/__init__.py:1-20。

核心组件

主服务入口 app_server.py

app_server.py 是模块入口，定义路由表、请求处理流水线以及 create_app() 工厂函数。它在启动阶段把 TokenVerifier、序列化器与异常处理器以中间件或依赖项的形式挂入应用，使得每一次入站请求在进入业务逻辑前都先经过身份校验——这与社区 #641 安全审计议题所关注的「纵深防御」诉求一致。资料来源：src/mcp_agent/server/app_server.py:50-130、src/mcp_agent/server/token_verifier.py:20-70。

类型契约 app_server_types.py

该文件集中存放对外暴露的 Pydantic 模型：包括请求体（携带代理名、输入消息、参数覆盖）、响应体（包含执行结果、token 用量、错误结构）以及会话元数据。所有外部可见字段、必填约束与默认值都由此处单一来源（single source of truth）决定，从而保证 OpenAPI/JSON Schema 与运行时校验保持一致；任何修改都会直接成为对外契约变更。资料来源：src/mcp_agent/server/app_server_types.py:1-90。

身份验证 token_verifier.py

token_verifier.py 实现 TokenVerifier 接口，把签名校验、过期检查、scope 解析等步骤封装为统一函数供 app_server 调用。它是社区 #693「调用前信任校验」能力的事实落地点——上层可以在路由层注入「先校验 token → 再校验服务器健康/可信度」的两段式钩子，使不可靠的远端 MCP 服务器在多步工作流中被尽早拦截。资料来源：src/mcp_agent/server/token_verifier.py:30-100。

工具适配 tool_adapter.py

tool_adapter.py 负责把本地 MCP 工具对象转换为可在远端调用上下文中序列化的形式：入参 JSON 化、出参反序列化、错误包装以及为后续流式响应预留的分片策略。通过该适配层，远端客户端能够透明地复用所有通过 MCPApp 注册的工具，而无需关心内部实现。资料来源：src/mcp_agent/server/tool_adapter.py:15-80。

请求生命周期

下面以「客户端调用远端 Agent」为例，展示一次请求在 Server 模块内的流转：

sequenceDiagram
    participant C as 客户端
    participant V as TokenVerifier
    participant R as Router
    participant D as 依赖注入
    participant A as Agent

    C->>V: 携带 Bearer Token
    V-->>C: 校验通过/拒绝
    C->>R: POST 请求(代理名 + 输入)
    R->>D: 解析 Context/LLM/Session
    D->>A: 实例化并执行 generate()
    A-->>C: 返回 AgentRunResponse

资料来源：src/mcp_agent/server/app_server.py:130-200、src/mcp_agent/server/app_server_types.py:40-110。

与社区议题的关联

跨组织身份（#673）：当 Orchestrator 跨边界调用远端 Agent 时，远端 Server 必须经 token_verifier 校验调用方身份；app_server_types 中用于承载代理身份信息的字段是该能力的数据载体。
服务可信度（#693）：app_server 在路由层支持注入预调用校验钩子，与 token_verifier 形成「认证 + 信任」纵深防御。
流式输出（#307）：tool_adapter 已为流式响应预留分片接口，是社区所关心的 streaming token 路线的承接点。
安全审计（#641）：模块把鉴权、依赖解析、异常包装显式分层，便于第三方审计者快速定位边界。

使用要点

通过 create_app(config=...) 启动服务，应用读取 mcp_agent.config.yaml 中的 server 段以决定监听端口与启用的中间件。资料来源：src/mcp_agent/server/app_server.py:60-90。
自定义鉴权：实现 TokenVerifier 子类并在工厂中替换默认注入即可生效。资料来源：src/mcp_agent/server/token_verifier.py:80-120。
扩展工具：在 tool_adapter.py 中注册新的序列化器，新工具即被自动暴露给远端。资料来源：src/mcp_agent/server/tool_adapter.py:60-100。

资料来源：src/mcp_agent/server/app_server.py:130-200、src/mcp_agent/server/app_server_types.py:40-110。

App 模块

App 模块是 mcp-agent 命令行工具（CLI）中针对云端部署应用的子命令集合，位于 src/mcpagent/cli/cloud/commands/app/ 目录下。该模块负责对部署在 mcp-agent 云平台上的应用（App）进行生命周期管理，包括查询运行状态、删除应用以及管理工作流配置等操作。App 模块作为云命令树的一级分组，将其下各子命令以 Click ...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 delete 子命令

继续阅读本节完整说明和来源证据。

章节 status 子命令

继续阅读本节完整说明和来源证据。

章节 workflows 子命令

继续阅读本节完整说明和来源证据。

概述

App 模块是 mcp-agent 命令行工具（CLI）中针对云端部署应用的子命令集合，位于 src/mcp_agent/cli/cloud/commands/app/ 目录下。该模块负责对部署在 mcp-agent 云平台上的应用（App）进行生命周期管理，包括查询运行状态、删除应用以及管理工作流配置等操作。App 模块作为云命令树的一级分组，将其下各子命令以 Click 命令的形式暴露给用户，使用户能够通过 mcp-agent cloud app <subcommand> 的形式对远端应用进行控制资料来源：src/mcp_agent/cli/cloud/commands/app/__init__.py:1-50。

App 模块的核心定位是"远端应用管理平面"，它并不直接实现智能体或 MCP 服务器的运行逻辑，而是封装了与 mcp-agent 云服务后端交互的细节，将 HTTP 请求、鉴权、错误处理等通用能力收敛到子命令内部，对外暴露简洁的命令行接口。

模块结构与子命令

App 模块采用"包级聚合 + 子包分发"的结构。app/__init__.py 作为入口文件，使用 Click 框架组织命令组，并在其中声明并注册各子命令资料来源：src/mcp_agent/cli/cloud/commands/app/__init__.py:1-80。每一个子命令对应一个独立的子目录，子目录内包含 __init__.py 与 main.py 两个文件，前者负责将命令函数注册到 Click 组中，后者则承载命令的具体实现逻辑。

目前已实现的子命令包括：

子命令	路径	主要职责
`delete`	`app/delete/`	删除指定的云端应用及其关联资源
`status`	`app/status/`	查询应用运行状态、健康度等元信息
`workflows`	`app/workflows/`	列出或配置与应用关联的工作流

App 模块通过 Click 的命令组机制实现可扩展性，新功能只需新增一个子包并在 app/__init__.py 中注册即可加入命令树。

delete 子命令

delete 子命令用于永久删除一个云端应用。该命令通过调用云后端的删除接口完成清理工作。命令入口在 app/delete/__init__.py 中以 Click 装饰器声明，其内部逻辑（如鉴权、参数解析、确认提示、删除请求）均委托给 app/delete/main.py 中的函数资料来源：src/mcp_agent/cli/cloud/commands/app/delete/__init__.py:1-40 资料来源：src/mcp_agent/cli/cloud/commands/app/delete/main.py:1-120。

status 子命令

status 子命令负责拉取并展示指定应用的当前运行状态，包括部署阶段、运行健康度、最近活动时间等关键指标。该子命令在交互场景中常被用来确认应用是否就绪或排查异常原因资料来源：src/mcp_agent/cli/cloud/commands/app/status/__init__.py:1-40 资料来源：src/mcp_agent/cli/cloud/commands/app/status/main.py:1-150。status 命令通常只读，不会对远端状态产生副作用，因此可以安全地反复调用。

workflows 子命令

workflows 子命令用于查看或管理与某个应用绑定的工作流定义，是连接"应用"与"工作流原语（parallel / sequential / orchestrator-workers 等）"的桥梁资料来源：src/mcp_agent/cli/cloud/commands/app/workflows/__init__.py:1-40。社区曾讨论过 mcp-agent 中缺失 adversarial/debate 等工作流模式（详见 issue #668），workflows 子命令未来有望承载更多模式的可视化与下发能力。

命令注册与执行流程

下面以 mcp-agent cloud app status <app_id> 为例，描述 App 模块从 CLI 入口到云后端的调用流程：

flowchart LR
    A[用户输入 CLI] --> B[Click 解析命令树]
    B --> C[app/__init__.py 命令组]
    C --> D[status/__init__.py 注册函数]
    D --> E[status/main.py 业务实现]
    E --> F[构造 HTTP 请求]
    F --> G[调用云后端 API]
    G --> H[解析响应并格式化输出]
    H --> I[回显至终端]

App 模块不直接处理底层网络与鉴权细节，而是将这部分能力下沉到共享的客户端工具中，从而使每个子命令的实现保持轻量、可读资料来源：src/mcp_agent/cli/cloud/commands/app/__init__.py:1-80。

设计要点与扩展方式

App 模块在设计上遵循了几个明确的原则：

关注点分离：每个子命令对应一个独立子包，命令声明（__init__.py）与具体逻辑（main.py）解耦，便于单测与维护。
可发现性：所有子命令都挂载在 app 这一 Click 组下，用户可通过 mcp-agent cloud app --help 一次性发现全部可用操作。
远端无状态假设：命令实现假设云端是事实来源（source of truth），本地 CLI 仅作为查询与控制平面，避免在本地持久化应用状态导致不一致。

社区中关于跨组织编排中代理身份验证（issue #673）与 MCP 服务器信任验证（issue #693）的讨论，未来也可能通过新增 app trust、app identity 等子命令在 App 模块中落地，使其在保证远端控制能力的同时，提供更细粒度的安全语义。

小结

App 模块是 mcp-agent 云端 CLI 的核心组成之一，承担"应用生命周期管理平面"的角色。它通过 delete、status、workflows 等子命令为开发者提供查询、清理与配置远端应用的能力，并借助 Click 命令组模式保持良好的扩展性。对于希望将本地工作流发布到 mcp-agent 云平台的团队而言，理解 App 模块是构建可运维部署流程的第一步。

来源：https://github.com/lastmile-ai/mcp-agent / 项目说明书

Agents 模块

mcpagent/agents/ 子包是 mcp-agent 框架中用于承载"代理（Agent）"抽象的核心模块。它的职责是把一个 LLM（经由 AugmentedLLM）与一组 MCP 服务器工具组合起来，对外暴露统一的 generate / generatestr 接口，让上层工作流（Parallel、Sequential、Orchestrator-Workers、Ro...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 AgentSpec（声明式代理规格）

继续阅读本节完整说明和来源证据。

章节 Agent（运行时代理）

继续阅读本节完整说明和来源证据。

章节 类型与工厂

继续阅读本节完整说明和来源证据。

概述

mcp_agent/agents/ 子包是 mcp-agent 框架中用于承载"代理（Agent）"抽象的核心模块。它的职责是把一个 LLM（经由 AugmentedLLM）与一组 MCP 服务器工具组合起来，对外暴露统一的 generate / generate_str 接口，让上层工作流（Parallel、Sequential、Orchestrator-Workers、Router 等）可以以"代理 + 工具"为最小单元进行编排。资料来源：src/mcp_agent/agents/agent.py:1-40 该模块用声明式 AgentSpec 与命令式 Agent 双形态覆盖常见使用场景，便于在配置文件中描述代理、再在代码中实例化执行。资料来源：src/mcp_agent/agents/agent_spec.py:1-30

核心组件

AgentSpec（声明式代理规格）

AgentSpec 是一个轻量级的数据类，用于描述代理的"是什么"，而不关心"怎么运行"。它集中保存代理名、注入的指令、可访问的 MCP 服务器列表，以及按需附加的 LLM 参数。资料来源：src/mcp_agent/agents/agent_spec.py:30-80 通过该 spec，用户既能在 YAML/JSON 里静态声明代理，也能直接在 Python 中以 AgentSpec(name="finder", instruction="...", server_names=["fetch", "search"]) 的方式构造，再交给 Agent 实例化。资料来源：src/mcp_agent/agents/agent_spec.py:80-120

Agent（运行时代理）

Agent 类是真正承载执行上下文的实体，封装以下要素：

对底层 MCPApp / Context 的引用，保证 logger、tracer、session_id 在整个调用链中可被复用。资料来源：src/mcp_agent/agents/agent.py:60-110
关联的 AgentSpec，在实例化时用来解析服务器连接与默认指令。资料来源：src/mcp_agent/agents/agent.py:110-160
可选的 AugmentedLLM 实例（如 OpenAIAugmentedLLM、AnthropicAugmentedLLM、OllamaAugmentedLLM、BedrockAugmentedLLM），由工厂方法按 provider 选择创建。资料来源：src/mcp_agent/agents/agent.py:160-220
工具调用循环：调用 llm.generate(...) → 解析 tool call → 通过 MCP 客户端分发到对应服务器 → 把 ToolMessage 追加回对话历史。资料来源：src/mcp_agent/agents/agent.py:220-300

agent.py 顶部以 dataclass 风格聚合属性，便于在调试时直接读取当前代理绑定的服务器、上下文窗口与多模态能力。资料来源：src/mcp_agent/agents/agent.py:40-60

类型与工厂

core/agent_types.py 定义代理可识别的 provider 枚举（如 openai、anthropic、azure、bedrock、gemini、ollama），并提供 resolve_llm_class(...) 这类映射函数，使 Agent 不必硬编码各家 SDK。资料来源：src/mcp_agent/core/agent_types.py:20-90 这层抽象是社区推动云厂商支持（#40、v0.0.15）与本地模型支持（OllamaAugmentedLLM、LMStudio 请求 #596）的关键支点。资料来源：src/mcp_agent/core/augmented_llm.py:1-40

生命周期与编排集成

flowchart LR
    A[AgentSpec] --> B[Agent.__init__]
    B --> C[加载 MCP 服务器]
    B --> D[AugmentedLLM 工厂]
    D --> E[OpenAI / Anthropic / Ollama ...]
    B --> F[agent.generate/prompt]
    F --> G{是否需要工具}
    G -- 是 --> H[调用 MCP 工具]
    H --> F
    G -- 否 --> I[返回结构化结果]

代理的生命周期由 Agent.initialize() 启动，期间会连接 server_names 中列出的 MCP 服务器，并构造首个默认 LLM；运行结束后建议显式 close() 以释放连接。资料来源：src/mcp_agent/agents/agent.py:90-110 上层 Orchestrator、Router 等高级工作流在 examples/basic/agent_orchestrator/main.py 等示例中演示了如何把多个 AgentSpec 注册到 App，并由 Orchestrator 按需委派任务。资料来源：examples/basic/agent_orchestrator/main.py:1-40

常见使用模式

基础代理：Agent(name="...", instruction="...", server_names=[...]) 后调用 await agent.generate_str(prompt)。资料来源：src/mcp_agent/agents/agent.py:240-280
多代理编排：在 MCPApp 内声明多个 AgentSpec，再交给 Parallel/Sequential/Orchestrator 模式组合。资料来源：src/mcp_agent/mcp_app.py:60-120
自定义 LLM：通过 context_aware_get_llm() 或工厂覆盖注入自定义 AugmentedLLM 子类，以适配云厂商或本地模型。资料来源：src/mcp_agent/core/augmented_llm.py:80-140

局限与社区关切

尚未内置"对抗/辩论"（adversarial/debate）原语，社区 #668 建议扩展 Agents 模块以支持两两代理的相互质询。
跨组织编排场景下，缺少代理身份校验机制（#673），当前 AgentSpec 未携带 issuer/audience 等声明字段。
工具层暂无统一的"信任验证"钩子（#693），需要在上层工作流或 MCP 服务器侧补齐。

来源：https://github.com/lastmile-ai/mcp-agent / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Agent identity for cross-org orchestration workflows

可能影响升级、迁移或版本选择。

high 来源证据：Missing workflow pattern: adversarial/debate — two agents argue opposite positions

可能影响授权、密钥配置或安全边界。

high 来源证据：[Security] MCP core: SSRF across all network transports, environment leakage, and unguarded sampling

可能影响授权、密钥配置或安全边界。

high 来源证据：feat: Add persistent memory example using Dakera MCP — addresses long-term memory gap (#12)

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：lastmile-ai/mcp-agent

摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Agent identity for cross-org orchestration workflows。

1. 安全/权限坑 · 来源证据：Agent identity for cross-org orchestration workflows

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent identity for cross-org orchestration workflows
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：Missing workflow pattern: adversarial/debate — two agents argue opposite positions

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Missing workflow pattern: adversarial/debate — two agents argue opposite positions
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/668 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：[Security] MCP core: SSRF across all network transports, environment leakage, and unguarded sampling

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] MCP core: SSRF across all network transports, environment leakage, and unguarded sampling
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/721 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：feat: Add persistent memory example using Dakera MCP — addresses long-term memory gap (#12)

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: Add persistent memory example using Dakera MCP — addresses long-term memory gap (#12)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/713 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Add TheCrawler as example MCP tool — web extraction with structured errors

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add TheCrawler as example MCP tool — web extraction with structured errors
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/692 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：Resource: Clarvia AEO Scanner — measure MCP server quality for agents using mcp-agent

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Resource: Clarvia AEO Scanner — measure MCP server quality for agents using mcp-agent
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/655 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：[RFC] Cryptographic agent identity for MCP agents via WTRMRK — who is this agent?

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[RFC] Cryptographic agent identity for MCP agents via WTRMRK — who is this agent?
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/658 | 来源类型 github_issue 暴露的待验证使用条件。

8. 配置坑 · 来源证据：Feature: Add trust verification for MCP servers before orchestration

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Feature: Add trust verification for MCP servers before orchestration
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/693 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 配置坑 · 来源证据：deploy command executes arbitrary user code by importing project main.py in-process

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：deploy command executes arbitrary user code by importing project main.py in-process
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/670 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 配置坑 · 来源证据：get_capabilities_task silently returns exception objects in ServerCapabilities dict under partial server failure

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：get_capabilities_task silently returns exception objects in ServerCapabilities dict under partial server failure
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/671 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 能力坑 · 来源证据：[Question] Reliability patterns under noisy conditions

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Question] Reliability patterns under noisy conditions
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/640 | 来源类型 github_issue 暴露的待验证使用条件。

12. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/lastmile-ai/mcp-agent | README/documentation is current enough for a first validation pass.

13. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/lastmile-ai/mcp-agent | no_demo; severity=medium

15. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/lastmile-ai/mcp-agent | no_demo; severity=medium

16. 安全/权限坑 · 来源证据：Example: Using cowork-to-code-bridge with mcp-agent for local code execution

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Example: Using cowork-to-code-bridge with mcp-agent for local code execution
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/706 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：Live API key printed in plain text to terminal on deploy

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Live API key printed in plain text to terminal on deploy
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/669 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：Security Audit Offer - MCP Agent Framework

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Audit Offer - MCP Agent Framework
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/641 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：Support OAuth Dynamic Client Registration (DCR) for traditional OAuth Providers

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support OAuth Dynamic Client Registration (DCR) for traditional OAuth Providers
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/667 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

20. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | issue_or_pr_quality=unknown

21. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | release_recency=unknown

来源：Doramagic 发现、验证与编译记录