HugAgentOS MCP工具生态：8个内置服务解析+自定义MCP接入完全指南

HugAgentOS 是一款面向可信推理的自进化 AgentOS，其工具生态构建在 MCP（Model Context Protocol）之上：联网搜索、网页抓取、知识库检索、图表生成等能力全部以独立的 MCP Server 形态提供。本文带你完整解析 HugAgentOS 的 8 个内置 MCP 工具服务，并给出自定义 MCP 接入的分步指南，帮助新手快速扩展智能体能力。

一、为什么用 MCP 组织工具生态？

在 HugAgentOS 中，每一类外部能力都是一个独立的 MCP Server，统一运行在专用的mcp容器中，后端通过 streamable-http 协议连接调用。这种设计带来三大好处：

• 🧩插拔粒度在 Server 级——启用/禁用一个能力只需在 catalog 配置或管理台开关，无需改代码；
• 🛡️故障隔离——单个工具崩溃由 launcher 自动重启，不影响后端主进程；
• 🔌生态开放——管理员可接入任意第三方 MCP Server，用户也可自助添加私有远程 MCP。

二、内置MCP架构：一个容器、多个端口、故障自愈

所有内置 MCP Server 都跑在同一个mcp容器里（镜像定义见 docker/Dockerfile.mcp）。容器入口是 src/backend/mcp_servers/_launcher.py：它为每个 Server 启动一个 streamable-http 子进程，单个 Server 崩溃时会指数退避重启；若 60 秒内崩溃超过 5 次，则让整个容器退出交给 Docker 拉起，实现故障隔离。

端口分配的唯一真源是 src/backend/mcp_servers/_ports.py：后端拼http://mcp:NNNN/mcp/URL 和容器内绑定端口都从这里读取，保证两侧永远一致。后端侧由 src/backend/core/llm/mcp_pool.py 的MCPConnectionPool连接池负责预连接与复用，src/backend/core/llm/mcp_manager.py 则把工具名还原为裸名（如internet_search），保证前端展示、图标渲染与引用溯源正常工作。

每个内置 Server 都遵循统一的目录约定：mcp_servers/<name>_mcp/下有server.py（FastMCP 薄壳）、impl.py（业务实现）、_selftest.py（不出网自检）。其中两条"铁律"值得记住：stdout 保留给 MCP 协议（业务日志一律走 stderr），对 LLM 生成的畸形参数保持容错。

三、8个内置MCP服务逐一解析

1️⃣ 知识库检索 retrieve_dataset_content

知识库 RAG 的检索入口，一个 Server 暴露三个工具：语义/混合检索、列出可用知识库、检索平台自建私有库。它是唯一的per-requestServer——每次请求按当前用户通过 HTTP 头注入允许访问的知识库 ID 与用户身份，天然实现多用户隔离。

2️⃣ 联网搜索 internet_search

支持 Tavily、百度、LangSearch 等引擎，单个查询或最多 4 个查询并发，按 URL 去重后返回最多 8 条来源。典型链路是"先internet_search拿 URL，再web_fetch核验原文"，来源可被引用系统自动标注锚点。

3️⃣ 图表生成 generate_chart_tool

generate_chart_tool(data, query)接收 JSON 数据与绘图指令，用 matplotlib 渲染折线图/柱状图/饼图，图片保存为平台 artifact 并返回file_id/ 下载 URL。工具描述中强制要求"先拿到真实数据再绘图，禁止编造数据"（见 src/backend/mcp_servers/generate_chart_tool_mcp/server.py）；mcp 容器内置中文字体，保证 CJK 渲染不出乱码。

4️⃣ 网页抓取 web_fetch

web_fetch(url, extractMode, maxChars)抓取指定 URL 并提取正文，支持text/markdown/html三种模式（src/backend/mcp_servers/web_fetch_mcp/server.py），正文默认最多 50,000 字符，是搜索结果的"原文核验搭档"。

5️⃣ 批量执行 batch_runner

batch_plan(instruction, file_ids, text_items, chat_id)识别"对一组对象逐个做同一件事"的批量意图（枚举对象 / Excel 行 / 多份文档），生成带占位符的执行计划并暂停回合——前端弹出确认对话框，用户审阅/修改模板后由后端逐条执行并实时推送结果。

6️⃣ 定时任务 automation_task

让智能体在对话中直接维护当前用户的自动化任务：create_scheduled_task创建、list_scheduled_tasks查看、update_scheduled_task修改 Cron 与提示词，以及暂停/恢复/删除。身份从X-Current-User-Id请求头注入，只能操作自己的任务。

7️⃣ 技能管理 skill_manager

服务于能力中心：search_marketplace搜索技能市场、install_from_marketplace一键安装、register_skill从上传包注册个人技能、submit_to_marketplace提交上架申请（src/backend/mcp_servers/skill_manager_mcp/server.py）。

8️⃣ 对话建站 site_publish

publish_site把沙箱里的静态站或构建产物一键发布为托管站点并返回可访问 URL，list_sites先查已有站点再更新原站（src/backend/mcp_servers/site_publish_mcp/server.py）；还支持管理应用数据库记录与"把数据表定义发布为个人 MCP"。

还有哪些 MCP？

• 插件提供族：agent_manager（9115，子智能体管理）、plugin_manager（9116，插件管理）、browser_runtime（9117，共享浏览器自动化，见 src/backend/mcp_servers/browser_runtime_mcp/server.py），它们的启停与卸载跟随插件生命周期；
• 商业版 EE：query_database（9101，内网数仓 NL2SQL 查询）与产业知识中心统一 MCP（9103，27 个产业链/企业/政策/专利工具）。

社区版启停门控由 src/backend/core/config/catalog.json 的mcp段控制：enabled=false的 Server 即使连接着也不会注册给智能体。

四、自定义MCP接入完全指南

HugAgentOS 支持三层接入方式，从普通用户到管理员再到平台级分发：

4.1 用户自助添加私有远程 MCP（最快上手）

普通用户在能力中心即可添加仅自己可见的远程 MCP，入口在 src/backend/api/routes/v1/me_capabilities.py（POST /v1/me/mcp-servers）：

1. 填写展示名称、简介、传输方式（仅streamable_http/sse）与远程端点 URL；
2. 需要鉴权时，在headers中填入自定义请求头（如Authorization），值会经 Fernet 加密落库，接口一律以***脱敏返回；
3. 创建即试连——系统真实连接一次，连不上直接拒绝落库；地址还会经过 DNS/IP 检查，阻断 localhost 与内网地址；
4. 成功后 server_id 自动生成umcp_<hex>前缀，即可在自己的对话中直接使用；DELETE /v1/me/mcp-servers/{id}可删除。

⚠️ 用户入口禁止 stdio传输（避免在服务器执行任意命令）；生产环境建议使用 HTTPS。该功能由can_add_mcp权限位控制（社区版单租户默认放开）。

4.2 管理员接入与 MCP 市场

管理员可在系统配置台的「MCP 工具 → MCP 服务管理」中创建任意 transport（stdio / HTTP / SSE）的全局 Server，支持环境变量注入、创建即试连、即时启停（联动刷新 catalog 与连接池）与密钥脱敏。Server 配置真源是数据库表admin_mcp_servers，由 src/backend/core/services/mcp_service.py 以 30 秒 TTL 缓存读出。

更进一步，MCP 市场（src/backend/core/services/mcp_marketplace_service.py）提供平台级治理：上架审核、可见范围控制、Token/OAuth 认证策略、风险分级（命中"删除/执行/写入"语义的工具会标记中高风险），以及每 6 小时的工具快照漂移复检。系统预置高德地图、秘塔搜索、GitHub、GitLab、阿里云可观测等精选模板，用户填入自己的 API Key 即可一键安装。详见 MCP 工具系统文档。

4.3 让工具结果可被引用：__citations__约定

开发自定义 MCP tool 时，想让结果进入平台的引用系统（证据锚点），只需在返回 JSON 中带__citations__字段：

{ "result": "……业务数据本体……", "__citations__": [ {"title": "来源标题", "url": "https://…", "snippet": "关键摘录"} ] }

中间件会自动为每条注入cite_id（e1、e2…），模型引用时原样复制，前端渲染成可点击的条目徽章。标准列表结构可在 src/backend/orchestration/citation_anchor.py 的TOOL_SPECS里登记，零代码改造。

五、本地调试速查

每个内置 Server 都可以脱离容器单独运行，便于调试你的新工具：

# stdio 方式跑单个 server（配合 MCP Inspector 等客户端） PYTHONPATH=src/backend python -m mcp_servers.internet_search_mcp.server # streamable-http 方式（模拟容器内形态） PYTHONPATH=src/backend python -m mcp_servers.internet_search_mcp.server \ --transport streamable-http --port 9102 # 不出网自检（验证导入与工具签名） PYTHONPATH=src/backend python -m mcp_servers.internet_search_mcp._selftest

修改 MCP 代码后重建容器即可生效：docker-compose up -d --build mcp。

总结

HugAgentOS 的 MCP 工具生态用"一个容器、端口即契约、Server 级插拔"的设计，把 8 个内置能力（知识库检索、联网搜索、图表生成、网页抓取、批量执行、定时任务、技能管理、建站发布）做得既稳定又开放；而用户自助 MCP、管理员全局接入与 MCP 市场三层通道，则让任何第三方 MCP Server 都能以受控、可审计的方式融入智能体能力体系。掌握本文的解析与接入指南，你就能让 HugAgentOS 的智能体按业务需要"长出"新工具。