系统概览与架构

项目定位

mcp-agent-portal 是一个统一的「代理与 MCP 控制平面」（Unified Agent & MCP Control Plane），将 AI 代理、MCP 工具、工作流、调度与同级评审整合在同一入口。其核心目标是为多代理协作提供聚合层：上层代理可以透明地发现并调用来自不同 MCP 服务器的公共工具，并基于项目本地的 .agent-portal/ 技能与代理定义执行复杂任务。资料来源：README.md:1-10

项目以 ESM 模块组织（"type": "module"），通过 npm start 启动服务，npm run build 将前端资源构建到 dist/web，开发模式则通过 npm run dev 指向 web/ 源码目录。资料来源：package.json:1-40

总体架构

整个系统采用分层结构，自下而上依次为：模型/CLI 适配层 → MCP 代理多路复用层 → 门户编排与工作流层 → 浏览器前端。下图为各组件之间的逻辑关系：

flowchart TB
  subgraph FE[浏览器前端]
    UI["Portal UI<br/>(web/dist)"]
  end
  subgraph BE[Node 后端]
    GW["local-gateway.js<br/>HTTP/WS 网关"]
    SRV["backend.js / demo-mode.js<br/>HTTP API"]
    MUX["mcp-multiplexer.js<br/>MCP 多路复用"]
    ORCH["portal-orchestrator-tools.js<br/>编排工具"]
    WB["workflow-board-tools.js<br/>看板元工具"]
    DM["orchestration-development-map.js<br/>运行态遥测"]
    AD["adapters/index.js<br/>CLI/模型适配"]
  end
  subgraph EXT[外部 MCP 与项目资产]
    MR["marketplace-registry.js<br/>MCP 注册表"]
    AP["agent-parser.js<br/>项目代理解析"]
  end
  UI --> GW --> SRV
  SRV --> MUX
  MUX --> AD
  MUX --> ORCH
  MUX --> WB
  MUX --> DM
  AP --> SRV
  MR --> MUX

• 网关层：local-gateway.js 负责端口复用、HTTP 升级（WebSocket）转发，并为静态资源注入 <base> 标签以支持子路径部署。资料来源：src/node/server/local-gateway.js:1-10
• 演示与 API 装配：demo-mode.js 在沙箱项目根 /workspace/agent-portal 下提供 /api/adapter/types、/api/cli/config、/api/flywheel/stats、/api/skills、/api/workflows、/api/groups 等接口，并对文件列举施加白名单与 96 KiB 大小限制。资料来源：src/node/server/demo-mode.js:1-30

关键子系统

代理与技能解析

agent-parser.js 解析 .agent-portal/agents/*.md 文件，识别 name/description/role/icon/color/resource_group/provider/model/models[]/skills[]/visibleAgents[] 等 frontmatter 字段，并支持两种技能组合方式：列表前置（skills: [X, Y]）与内联占位符（{{skill:Z}}）。底层 YAML 解析由 frontmatter.js 提供，支持标量、行内/多行数组、行内对象与嵌套对象。资料来源：src/node/agents/agent-parser.js:1-20、src/node/agents/frontmatter.js:1-15

MCP 多路复用与工具索引

mcp-multiplexer.js 是公共 MCP 工具的聚合入口，对外暴露一组「元工具」：discover_tools（关键字/标签/服务器名搜索）、call_tool（按名称调用）、get_portal_status（门户健康与运行态摘要），以及 create_chat/switch_chat/send_chat_message 等会话控制。资料来源：src/node/proxy/mcp-multiplexer.js:1-25

工具索引由 tool-index.js 维护：对每个子 MCP 服务器调用 tools/list 后构建摘要条目（工具对象 + 来源服务器），支持关键字、标签与服务器名检索；子服务器拓扑变化时应重建。资料来源：src/node/proxy/tool-index.ctx.md:1-10

适配器与模型发现

adapters/index.js 通过 getEffectiveModels() 按「用户配置 → CLI 发现 → 默认」三段优先级合并模型列表：claude 使用 CLAUDE_CODE_MODEL_CATALOG；opencode 注入运行时 CLI 模型；antigravity 追加 default 占位。资料来源：src/node/adapters/index.js:1-25

编排、看板与遥测

orchestration-development-map.js 输出统一的「开发地图」（schemaVersion: 1），聚合子代理、任务、工具调用与最近活动，并施加硬性上限 SUBAGENT_LIMIT / TASK_LIMIT / TOOL_EVENT_LIMIT / TOOL_BUCKET_LIMIT，避免超出代理上下文预算。资料来源：src/node/proxy/orchestration-development-map.js:1-20

workflow-board-tools.js 将工作流看板收敛到单一 workflow_board 工具，通过 action 字段路由（create_item/update_item/decompose/transition/control_board 等），支持 approvalMode: yolo|auto_edit|plan 与乐观版本号。资料来源：src/node/proxy/workflow-board-tools.js:1-25

marketplace-registry.js 维护官方/Google/社区三类 MCP 服务器清单（如 brave-search、fetch、github、slack、linear 等），并通过 getRegistryByCategory() 与 findInRegistry(name) 提供分类与按名查询。资料来源：src/node/server/marketplace-registry.js:1-30

数据流与典型交互

用户通过浏览器门户发起请求后，请求经 local-gateway 进入后端 HTTP API。门户的根会话路由到编排器，由 portal-orchestrator-tools.js 注入 promptHints 字符串与结构化建议（promptHintMap），指导子代理在合适的时机调用 discover_tools 与 call_tool。编排过程中，所有工具调用、代理切换与任务生命周期事件被聚合到 orchestration-development-map.js，形成可消费的运行态视图；最终结果通过 workflow_board.transition 等动作落库到看板。资料来源：src/node/proxy/portal-orchestrator-tools.js:1-25

备注：本检索批次未返回 index.js / backend.js / bin/mcp-agent-portal.js 的全文，上述入口职责以 package.json 中的脚本与同层文件所描述的接口为准。

mcp-agent-portal 的核心职责之一，是把多个下游 MCP（Model Context Protocol）子服务器聚合成一个统一的对外接口，并向 IDE/Agent 客户端提供经过过滤的"门户级"工具视图。这一能力由 src/node/proxy/ 目录下的若干模块协作完成，包括子进程生命周期管理、JSON-RPC 消息转发、工具索引缓存、可见性过滤与 HTTP/stdio 传输适配。本页介绍其整体架构与关键路径。

1. 总体架构与角色划分

门户（Agent Portal）运行后，会启动一个 MCPProxyManager，负责按配置拉起若干 child MCP server（通过 stdio 子进程），并对它们的 tools/list、resources/read、tools/call 等请求进行转发与聚合。资料来源：README.md:1-120

整个请求链路可以概括为四层：

flowchart LR
  A[IDE / Agent 客户端] -->|stdio 或 HTTP| B[MCPProxyManager<br/>聚合与生命周期]
  B -->|转发 JSON-RPC| C1[project-graph-mcp]
  B -->|转发 JSON-RPC| C2[agent-pool-mcp]
  B -->|转发 JSON-RPC| C3[browser-x-mcp / 其他]
  B --> D[ToolIndex<br/>缓存与搜索]
  B --> E[mcp-multiplexer<br/>Meta-Tools Gateway]
  E --> F[portal-goal / portal-orchestrator<br/>工作流与编排工具]
  E --> G[workflow-board / chat-delegate<br/>子工具分发]

• MCPProxyManager：负责启动/停止 child server，缓存 server map，提供 requestFromChild(serverName, method, params)。
• ToolIndex：通过 tools/list 周期拉取各 child 的工具表，提供 keyword/tag/server 三种检索方式。资料来源：src/node/proxy/tool-index.js:1-60
• mcp-multiplexer：作为"Smart Tool Gateway"，对外暴露门户级 meta-tools（create_chat、resume_chat、get_development_map 等），而不是把所有子工具原样泄露给客户端。资料来源：src/node/proxy/mcp-multiplexer.js:1-90

2. 子服务器管理与 JSON-RPC 转发

MCPProxyManager 维护 Map<string, ChildServer>，其中 key 是 ~/.agent-portal/agent-portal.json 中 mcpServers 的条目名，例如 project-graph、agent-pool。每个 child server 在 startAllServers() 阶段被 fork 为 stdio 子进程，并通过 requestFromChild() 进行 JSON-RPC 调用。资料来源：src/node/server/backend.js:1-30

在 requestFromChild() 中实现了：

• 单子服务器 5 秒级的内部超时（INTERNAL_TASK_STATE_TIMEOUT_MS = 5_000），用于 tools/list、tasks/state 等 meta 查询。
• withTimeout() 包装 Promise，确保卡死的 child 不会拖垮主进程。资料来源：src/node/proxy/mcp-multiplexer.js:30-50

这一层只关心"如何把消息可靠地送到下游"，不解析 method 语义，因此工具可见性、合并、过滤都在更上层完成。

3. ToolIndex：跨子服务器的工具缓存与检索

ToolIndex 是 mcp-multiplexer 与 HTTP handler 共享的只读缓存。它在 rebuild(proxyManager) 时遍历 proxyManager.servers，对每个公开 server 调用 tools/list，将 { tool, server } 写入 tools: Map<string, Entry> 与 tags: Map<string, string[]>。资料来源：src/node/proxy/tool-index.js:15-50

主要项目括：

需要强调：未通过 isPublicMcpToolServer() 检查的 server（如 agent-pool）不会进入索引，从而不会暴露在 tools/list 给客户端。资料来源：src/node/proxy/mcp-tool-visibility.js:1-50

4. Tool Multiplexer：Meta-Tools Gateway

mcp-multiplexer.js 是门户对外的"门面"。它没有把每个 child 的全部工具平铺出去，而是按优先级注册一组 portal 级工具，例如：

• create_chat / resume_chat：开启或恢复 UI 中的 Agent Chat 会话。
• get_orchestrator_status：返回活跃 agent 数量、可用标签、systemLoad、活跃 MCP client/proxy 遥测。
• get_development_map：默认返回"compact"精简开发地图；传入 detail: "full" 时返回 subagentMap、taskMap、toolMap、activityMap、promptHintMap 的完整结构，可能超出 agent 上下文预算。资料来源：src/node/proxy/mcp-multiplexer.js:1-90

当请求进入 multiplexer 时，分发顺序大致为：

1. Goal tools：isPortalGoalTool() 命中后由 handlePortalGoalTool() 处理。
2. Orchestrator tools：isPortalOrchestratorTool() 命中后由 handlePortalOrchestratorTool() 处理。
3. Delegate/Chat tools：isDelegateTool() 命中后通过 prepareDelegateTaskCall() 解析 resourceGroup、assignedAgent、parentChatId 等参数。
4. Memory tools：remember / recall 直接走 memory-store。
5. Child public tools：最终 fallback 到 proxyManager.requestFromChild()。

资料来源：src/node/proxy/mcp-multiplexer.js:1-90 与 src/node/server/web-server.js:1-120

这种"先 portal meta，再 child public"的顺序确保了内部执行服务器（如 agent-pool-mcp）始终保留给门户自身使用，外部 MCP 客户端只能调用门户已经抽象过的入口。

5. HTTP 传输与可见性约束

web-server.js 在 /mcp 上提供 MCP Streamable HTTP 端点，并把 mcpHttpHandler 接到同一套转发逻辑上。该 handler 暴露了 getTools、onToolCall、onResourcesList 三个钩子，分别对应 _collectAllTools、_routeToolCall、_aggregateResources。资料来源：src/node/server/web-server.js:1-120

可见性约束的核心来自 mcp-tool-visibility.js：

• isPublicMcpToolServer(serverName)：判断某个 child server 是否允许出现在公开 tools/list 中（例如 agent-pool 默认返回 false）。
• isInternalMcpToolName(name) / internalMcpToolBlockedResult()：即使客户端通过直接调用绕过 tools/list，某些内部工具名也会被显式拦截并返回 blocked 提示。
• splitMcpHealthStatus()：把 health status 拆分为 public 与 internal 两个层级，避免暴露内部 server 的细节。

资料来源：src/node/proxy/mcp-tool-visibility.js:1-60 与 src/node/server/web-server.js:40-120

此外，server 还支持 serverDemoMode.enabled，开启后 /mcp、/mcp/message、/anthropic/* 路径会返回 404，避免公网部署下被直接探测。资料来源：src/node/server/web-server.js:20-60

常见失败模式与注意事项

• Tool 数量膨胀：get_development_map(detail="full") 返回的内容可能超出 agent context。默认应使用 compact，仅在调试时切换为 full。
• 重建超时：TOOL_INDEX_REBUILD_TIMEOUT_MS = 10_000，若 child 在 10 秒内未返回 tools/list，整个 rebuild 会失败并被记入 failures。
• HTTP 与 stdio 不一致：HTTP 路径通过 mcpHttpHandler 复用同一份 multiplexer，但仍受 serverDemoMode、networkAuth 拦截；调试时务必确认 networkAccess.lanEnabled 与 token 配置。
• 重复启动 child：backend.js 中 proxyManager.startAllServers() 在进程级别只调用一次；当以 detached singleton 模式运行时，多个 IDE 窗口共享同一进程，不会重复 fork child server。

See Also

• 门户级 Meta-Tools：portal-goal-tools.js、portal-orchestrator-tools.js
• 工作流板：workflow-board-tools.js 与 iso/workflow-board.js
• Agent & Skill 解析：agents/frontmatter.js、agents/agent-parser.js
• 配置与市场：server/marketplace-registry.js、~/.agent-portal/agent-portal.json
• 总览：README.md

1. 系统定位与总体架构

mcp-agent-portal 是一个统一的 Agent 与 MCP 控制平面（Unified Agent & MCP Control Plane），将项目本地的 Agent、技能、工作流与外部 MCP 工具市场聚合到同一运行时。package.json 中声明入口为 bin/mcp-agent-portal.js，并通过 npm run build / npm start 完成生产构建与启动 资料来源：package.json:1-25。

运行时可视为三层：

• 适配器层（Adapters）：把 Codex、Claude、Antigravity、Pool 等不同 LLM 提供方包装为统一对话接口；
• 解析与技能层（Agents & Skills）：解析 .agent-portal/agents/*.md 中的 frontmatter 与技能引用；
• 代理与编排层（MCP Multiplexer / Orchestrator / Workflow Board）：通过 Meta-Tool 暴露给上层 Agent，集中管理子任务、工具调用、看板与开发地图 资料来源：README.md:1-30。

2. Agent 实体与技能解析

Agent 文件位于 .agent-portal/agents/*.md，由 parseMarkdownFrontmatter 拆分为 frontmatter 元数据与正文 资料来源：src/node/agents/frontmatter.js:1-20。frontmatter 解析支持标量、内联数组、多行数组、内联对象与嵌套对象等 YAML 子集 资料来源：src/node/agents/frontmatter.js:5-20。

agent-parser.js 在此基础上封装出技能组合（Skill Composition）机制：

• skills: [X, Y]：所列技能的内容会在 Agent 正文之前整体拼接；
• {{skill:Z}}：以行内占位符形式在正文出现位置就地展开 资料来源：src/node/agents/agent-parser.js:1-15。

为减少磁盘 I/O，getSkillMap 会缓存目录扫描结果，2 秒内复用同一目录 资料来源：src/node/agents/agent-parser.js:30-50。下图为 Agent 文件到最终 Prompt 的数据流：

flowchart LR
  A[".agent-portal/agents/*.md"] --> B["parseMarkdownFrontmatter"]
  B --> C{"meta + body"}
  C --> D["skills[] 预拼接"]
  C --> E["{{skill:Z}} 行内替换"]
  D --> F["最终 Agent Prompt"]
  E --> F
  F --> G["Adapter / Provider / Model"]

3. 适配器与资源组

src/node/adapters/index.js 的 loadResourceGroupPreferences 读取 resource-groups.json，抽取三类信息：

• 按 provider 汇总的 preferredModel 列表（byProvider）；
• 首个被发现的 defaultModel；
• 完整资源组（groups），包含 rotation_mode、approval_mode、policy、max_agents、timeout 等字段 资料来源：src/node/adapters/index.js:1-40。

前端利用这些元数据构建级联下拉选择：Pool → Agent（来自 .agent-portal/agents/）→ Provider → Model → ChatType。同一 Adapter 既可作为根编排器使用，也可作为子聊天的 agent_slug 进行路由 资料来源：src/node/proxy/mcp-multiplexer.js:create_chat。

4. MCP 多路复用、编排器与工作流看板

MCP Multiplexer 暴露一组 Meta-Tool：

• create_chat：在 UI 中即时创建聊天会话并返回 activityMap、subagentMap、taskMap、toolMap、latestTools、promptHintMap 等开发地图字段 资料来源：src/node/proxy/mcp-multiplexer.js:create_chat；
• discover_tools / call_tool：按 tag 或 server 过滤后调用外部 MCP 工具，Agent Pool 的内部工具不参与 call_tool 资料来源：src/node/proxy/mcp-multiplexer.js:discover_tools,call_tool；
• get_portal_status：返回已连接 MCP 服务、运行时健康度、tag 列表与 systemLoad 容量摘要；detail:"full" 时返回完整开发地图 资料来源：src/node/proxy/mcp-multiplexer.js:get_portal_status。

portal-orchestrator-tools.js 负责在编排过程中检测“最终答复模板”（如以 “I now have … evidence.” 开头或 “Here is …” 结尾的句子），并对缺少 requiredMarker 的输出触发 finalAnswerRepairHint 修复流程 资料来源：src/node/proxy/portal-orchestrator-tools.js:1-40。orchestration-development-map.js 在此基础上汇总 subagentMap、taskMap、toolMap 与 promptHints，产出 latestTools / usage / liveness 等结构化字段 资料来源：src/node/proxy/orchestration-development-map.js:1-40。

workflow-board-tools.js 通过单一 workflow_board Meta-Tool 把列管理、卡片生命周期、自动化规则和事件查询统一到一致的入参模式，参数如 approvalMode: 'yolo' | 'auto_edit' | 'plan'、expectedVersion（乐观锁）以及 entityRefs 在所有 action 之间共享 资料来源：src/node/proxy/workflow-board-tools.js:1-30。

外部 MCP 服务在 marketplace-registry.js 中按 official / google / community 等分类登记，包含 command、args 与 envHint，envHint 用于在面板中提示用户配置必要的环境变量 资料来源：src/node/server/marketplace-registry.js:1-40。demo-mode.js 在公共/演示模式下限制可暴露的源码与资源类型（白名单 src、public 等目录、.js/.mjs/.ts/.svg/.png 等扩展名），并把项目根目录锁定到 /workspace/agent-portal 资料来源：src/node/server/demo-mode.js:1-20。

See Also

• README.md
• package.json
• src/node/agents/frontmatter.js
• src/node/adapters/index.js
• src/node/proxy/mcp-multiplexer.js

概述与定位

Web Dashboard（web/index.html + web/app.js）是 mcp-agent-portal 的浏览器入口，负责在单页中渲染项目文件、代码图谱、聊天会话、技能面板、运行时状态以及可选的 XR 沉浸式面板。门户前端通过静态资源服务器与本地网关拉取 dist/web（或 web/）下的资源，再由后端 Node 进程以 MCP 多路复用器（Multiplexer）和代理管理器为面板提供实时数据与公共工具调用。

• 静态资源入口约定见 README.md：生产构建产物位于 dist/web，缺失时回退至 web/；AGENT_PORTAL_WEB_ROOT 可在容器化构建中指向自定义 UI 目录。
• 前端模块按职责拆分：web/dashboard.js 负责面板装配，web/state.js 提供共享状态，web/router-registry.js 注册前端路由，web/services/chat-ws-client.js 处理与后端的实时消息流。

静态资源、网关与代理

src/node/server/web-server.js 中的 serveStaticFile() 负责从 WEB_DIR、各 packages/ 子模块、已审核的 vendor 资源或共享 iso 助手目录中返回静态文件；当路径命中目录时自动追加 index.html，未命中时返回 403/404。无法识别的 /api/* 路径则经 proxyToBackend() 转发到名为 serverName（默认 project-graph）的子 MCP 服务进程。

src/node/server/local-gateway.js 是一段压缩的本地网关实现：

• 监听 0.0.0.0 并将端口写入运行时目录（runtime/），供子进程握手；
• 处理 HTTP 请求时若 Accept 包含 text/html 且存在前缀（prefix），会自动注入 <base href="${prefix}/"> 以便子应用使用相对路径；
• WebSocket upgrade 仅代理到非 dashboard 后端，避免占用门户自身的长连接通道。

flowchart LR
  Browser[浏览器 / VR 头显] -->|HTTP/WS| WebServer[web-server.js]
  Browser -->|prefix 路由| Gateway[local-gateway.js]
  WebServer -->|dist/web 或 web/| Static[静态 UI 资源]
  Gateway -->|/api/*| Backend[project-graph / pool MCP]
  WebServer -->|XR 诊断| LogStore[xr-diagnostics-log.js]
  WebServer -->|演示数据| Demo[demo-mode.js]
  Backend --> Multiplexer[mcp-multiplexer.js]
  Multiplexer -->|门户元工具| Browser

演示模式与公共数据安全

为支持公开演示，门户在 src/node/server/demo-mode.js 中维护了一份白名单文件系统：

• PUBLIC_ROOTS 限制可浏览的顶级目录（如 src/、web/、packages/、docs/ 等）；
• BLOCKED_SEGMENTS 显式屏蔽 .env、.git、.ssh、node_modules、secrets、tmp 等敏感段；
• MAX_FILE_BYTES = 96 * 1024 限制单文件大小；
• PUBLIC_SOURCE_EXTENSIONS 与 PUBLIC_ASSET_EXTENSIONS 分别控制源码（.js/.ts/...）与图片资源（.svg/.png/...）的可读性。

演示用的项目树（DEMO_OPEN_LIBRARY_TREE / DEMO_AGENT_PORTAL_TREE）和 demoPortalFileContent()、demoWorkflowList() 共同构成"安全沙箱"下的只读视图，确保公开部署不会泄露私有仓库或机密配置。资料来源：src/node/server/demo-mode.js。

门户侧的 MCP 元工具

前端面板通过 src/node/proxy/mcp-multiplexer.js 暴露的元工具与后端对话，核心条目包括：

• get_portal_status：返回已连接公共 MCP 服务、工具总数、discover_tools 可用标签、系统负载、活跃客户端/代理遥测以及开发图（detail="compact"|"full"）；
• create_chat：在门户 UI 中创建新会话（可指定 adapter、agent/agent_slug、parentChatId），返回结构化聊天元数据与 promptHintMap；
• discover_tools：按关键字、标签或服务器名检索已注册工具；
• call_tool：调用 discover_tools 选中的公共工具；Agent Pool 内部工具不通过此入口调用。

这些元工具的 inputSchema 描述了严格的参数约束，是前端面板（聊天、运行时、工具浏览）在协议层保持一致的关键。资料来源：src/node/proxy/mcp-multiplexer.js。

XR 诊断与可视化面板

src/node/server/xr-diagnostics-log.js 把 WebXR 会话的健康快照写入诊断日志，供面板实时显示：

• htmlCanvasAvailability / htmlCanvasRecommendation 反映 HTML-in-Canvas 纹理上传能力；
• sceneQualityStatus、sceneQualityLowPanels 记录场景质量降级状态；
• readiness / visualReadiness / interactionReadiness 三态汇总沉浸式会话的总体就绪度；
• textureMode / textureStage / textureResolverStage 严格模式的纹理解析状态；
• deepGraphNodes / deepGraphEdges 暴露图谱渲染规模。

依据 README.md，生产环境应通过 npm run xr:production-smoke 校验 https://playground.rnd-pro.com/demos/agent-portal-vr/#spatial?project=agent-portal&target=graph&texture=strict 处于 production-spatial-ready 状态，并在 Panels live: 4/4、XR texture mode: strict 下进入 immersive-ar 探针会话；严格模式下若 HTML-in-Canvas 不可用，前端必须隐藏未贴图的面板并显示 XR texture gate: blocked:html-in-canvas-unsupported，以避免向用户呈现空面板或材质回退面板。

常用配置

常见失败模式

1. 未构建直接启动：npm start 找不到 dist/web 时会回退到 web/，如 web/ 也不存在则 serveStaticFile() 返回 404，应先执行 npm run build。
2. 演示数据被截断：MAX_FILE_BYTES 限制为 96 KiB，超大文件不会出现在公共浏览中；如需浏览大文件应改用非演示部署。
3. 严格模式下面板空白：若 htmlCanvas 不可用且未隐藏 fallback 面板，前端会渲染空白；严格模式要求面板被隐藏并以诊断状态替代。
4. WebSocket 被网关拦截：local-gateway.js 仅代理非 dashboard 升级请求，仪表板自身的长连接不会被强制走网关。

See Also

• Project Graph MCP & Tools
• Agent Pool MCP
• XR / WebXR 诊断
• Marketplace Registry

Pitfall Log / 踩坑日志

项目：rnd-pro/mcp-agent-portal

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/rnd-pro/mcp-agent-portal | host_targets=mcp_host, claude, cursor

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

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

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

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

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

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

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

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

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

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

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