fix: AI 控制台 MCP 不可达给出明确文案——不再显示 SDK 含糊报错

MCP 客户端(streamable_http)在工具服务不可达/返回非 MCP 响应时只抛
'Server returned an error response',用户无法判断原因。改为:
- 后端 web/agent_api.py:_execute 包裹 _load_tools/run_stream,识别连接类错误
  (Server returned an error response/ConnectError/refused 等)后抛明确文案:
  'MCP server(8033) 不可达:无法加载设备工具(<url>)。请确认 MCP server 已启动…'
- 前端 static/admin/agent.js 加 _friendlyAgentError() 兜底映射并去掉
  'RuntimeError:' 之类前缀,三处错误展示统一使用
- 文档同步:MCP.md(依赖提示+本机启动命令)、API.md(SSE error 文案说明)、
  DEPLOY.md(故障排查新增一行)
实测:停掉 MCP 复现 → 前端显示明确文案;启动 MCP 后 AI 控制台正常完成任务
This commit is contained in:
2026-09-10 10:28:57 +08:00
parent 4e67764589
commit 357fe98e22
5 changed files with 55 additions and 12 deletions
+5
View File
@@ -166,3 +166,8 @@ Web 端「AI 控制台」Tab 内建的 Agent(`mcp_agent/`,OpenAI 兼容协
- 多轮会话记忆(同会话上下文保留,新建会话清空)
- **自进化经验记忆**:一轮成功操作会被提炼成「配方」存入 `agent_experience` 表,下次相似任务自动注入参考(命中/写入均有 🧠 提示卡)
- 模型与 API Key 在 AI 控制台右上角 ⚙ 配置,存平台 `app_meta`
> **依赖提示**:AI 控制台依赖本 MCP Server(默认 `http://127.0.0.1:8033/mcp`)。若未启动,发起指令会直接失败——平台已把 SDK 的含糊报错(`Server returned an error response` 等)映射为明确文案:**「MCP server(8033) 不可达 …」**。
> 本机(非容器)需手动拉起:
> `MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> MCP_AUDIT_FILE=data/mcp_audit.log python -m mcp_server.mcp_server`
> 220 生产容器由 `scripts/start.sh` 自动拉起(`MCP_ENABLED=0` 会关)。