跳到主要内容

MCP 工具地图

提问（聊天）中的 AI 与自动化可调用的工具来自 七个 MCP 服务器。本文梳理各服务器分别负责什么，以及 为什么工具明明存在，AI 却不使用。

                              묻기(코파일럿) 의 AI
                                       │
   ┌────────────┬────────────┬─────────┼──┬────────────┬────────────┬────────────┐
   ▼            ▼            ▼            ▼            ▼            ▼            ▼
 플랫폼 통합   시계열 인사이트   RAG       문서 이해      비전       디지털 스레드     공학 계산
 /api/v5/mcp  insight_ 39개  rag_ 2개  document_ 2개  vision_ 5개  thread_ 4~9개   eng_ 4개
   22개
 «공장의 실제  «파형을 보고   «문서에서   «PDF·표를     «사진을     «무엇이 언제     «공식으로
   데이터»      판단»         찾는다»     읽는다»       본다»       일어났고 무엇과    계산한다»
                                                                  이어졌나»

副驾驶并不直接接入这些服务器。自 2026.10 再发布（2026-10-20） 起，由 MCP 网关（plantpulse-mcp-gateway-api，内部 7160）统一汇集 平台 · 内置服务器 · 运维人员接入的外部服务器的工具，副驾驶只看这一个地址。内置服务器由网关在安装时自行注册。

首次启用的工具 — 网关策略​

工具首次被发现时启用还是关闭，由 MCP 网关的策略 决定。更改启用/关闭的位置是 AI 管理控制台 › MCP 网关 › 工具 → AI 管理控制台 — MCP 网关

服务器首次被发现时
平台集成 MCP全部启用
时序洞察 insight_34 种启用 —— 39 种中，一个写入工具（trigger_feature_pipeline，无法启用）以及 forecast_order_completion · autonomy_status · get_oee_losses · get_spc_chart 四个为关闭 → 时序洞察工具
数字主线 thread_9 种启用 —— 全部读取工具
工程计算 eng_4 种启用 —— 四项全部
RAG rag_2 种启用 —— rag_search（文档检索）· rag_list_documents
文档理解 document_2 种启用 —— document_understand · document_profiles
视觉 vision_5 种启用 —— vision_read_meter · vision_inspect · vision_ocr · vision_analyze · vision_classify
运维人员接入的外部服务器关闭 —— 逐个阅读工具说明后再启用
  • 列表按名称记录。内置服务器 新增工具时以关闭状态 加入。
  • 管理员改过一次的值保留在网关 DB 中，启动或版本升级都不会覆盖。
  • 🔴 聊天的文档检索只有 rag_search 这一条路。 此工具关闭或未授权给该账户时，对手册 · 图纸 · 规程类问题会回答「文档检索工具已关闭，或未授权给此账户」。
  • 🔴 启用这么多工具的前提是 工具检索已启用。网关针对每个问题挑选最多 20 个（预算）相符的工具载入模型， 按名称 → ID 查找的 search_domains 与文档检索 rag_search 不受预算限制，始终另外载入（账户获准时）。若在 检索设置 中关闭检索，模型每个问题都会收到已启用的 70 多种工具。
  • 检索除工具名称 · 说明外，还依据检索词挑选。由于工具说明是英文，检索词是把韩语问题连接到工具的词语，只用于词语检索，模型看不到。 来源按本安装的覆盖 › 服务器声明 › 网关默认值（平台集成 MCP）的顺序优先。外部 MCP 服务器可以在工具的 _meta["io.plantpulse/search_terms"] 中 像 {"ko": ["알람 확인 처리"]} 这样声明。每个工具最多 4 种语言、所有语言合计 8 个 · 64 字，超出则整体丢弃 → AI 管理控制台 — 工具检索词

旧版（至再发布 8）由副驾驶保存启用/关闭状态，时序洞察只启用了 get_attention_ranking 等少数几个。 升级到再发布（2026-10-20） 后，这些值 不会迁移，而是按上述策略重新开始。若旧版中特意关闭过某些工具，请在升级后重新关闭。

原因有两点。

  1. 一次性丢给 AI 几十个工具，它 会选错。
  2. 用不到的工具，其描述 每次请求都在消耗 token。

因此由策略决定要启用的工具，并在已启用的工具中再由检索按问题缩小范围。

新接入的外部服务器以关闭、且未授权给任何人的状态开始

在网关中添加外部服务器并读取工具后，AI 和自动化仍然什么都用不了。 需要启用服务器、逐个启用工具， 并在 权限 中向调用方（副驾驶）授权。外部工具的说明会原样进入模型提示词，请阅读后再启用。

「工具明明在，AI 却不用」的第一排查点就在这里 → AI 管理控制台 — MCP 网关

写入类工具无法开启

会改变状态的工具会被自动隐藏并 按策略拦截。唯一的例外是报警确认（ack_alarm），而且它还要在核对目标设备范围之后才放行。控制设备或修改配置的手段 根本不存在。

平台集成 MCP — 22 个​

这是工厂的真实数据。由 Platform（server-web）以 /api/v5/mcp 提供，并通过 api_key 认证。

维度工具功能
时间get_current_time服务器当前时刻
结构search_domains按名称查找并解析出 ID（通常从这里开始）
结构get_asset_tree资产层级树
结构get_ontology站点本体概览
结构query_ontology资产关系图遍历
结构query_sparql本体 SPARQL 查询
结构get_asset_documents挂在设备上的文档列表
连接get_edge_statusEdge 网关状态
连接get_edge_health_historyEdge 健康历史（按日期区间）
连接list_connectionsOPC 采集连接列表
标签get_tag_values标签当前值
标签get_tag_history标签区间历史
报警list_alarms报警列表
报警get_alarm_context报警原因诊断包
报警ack_alarm报警确认处理 — 🔴 唯一的写入工具
设备get_asset_snapshot设备全标签快照
设备get_asset_timeline设备事件时间线
设备get_asset_stats设备区间业务统计
生产list_orders工单列表
生产get_order_metrics工单详情·KPI
生产get_asset_kpi设备按工单的 KPI（OEE/EMS/RAM）
汇总get_health资产层级健康汇总
把名称换成 ID 几乎总是第一步

人说的是「3 线压缩机」，而工具接收的是 ID。search_domains 就是两者之间的桥梁 —— 如果 AI 抓错了设备，多半就是在这一步岔开的。

用法见 MCP 服务器管理，本体类工具的详细用法见 本体。

时序洞察 — insight_ 39 个​

负责看波形做判断的一侧。异常检测·预测·历史对比·设备综合·报警统计·剖面分析，以及 自 2026.10 起的 AI 发现 · 关注设备 · 生产分析（工单完工预测 · OEE 损失 · 控制图）。

→ 时序洞察工具完整列表

RAG — rag_ 2 个​

工具功能
rag_search以混合模式检索相关文档，给出答案与出处。每条出处的 reference_id 与答案正文中的 [n] 一一对应
rag_list_documents已索引文档列表
检索不到时会以«失败»返回

若检索什么也没取到，rag_search 会返回 success: false · retrieved: false 与 code（NO_CONTEXT · EMPTY_ANSWER） · reason，并且 不附带 answer。 这是为了避免把空结果当作«检索结果»，导致 AI 用自身知识编造答案 —— AI 回答「在文档中未找到」属于正常行为。

→ 文档检索（RAG）

文档理解 — document_ 2 个​

工具功能
document_understand将 URL 指向的一份文档转换为 结构化 markdown —— 可识别表格·版式·公式。支持 PDF · DOCX · PPTX · XLSX · 图像
document_profiles可选解析配置文件列表
配置文件用途
default与 RAG 索引 相同的选项 —— 用于查看「RAG 是怎么读这份文档的」
fast快速 —— 关闭 OCR，表格从简
ocr仅文字 —— 从图像中读取文字（关闭表格结构识别）
scan扫描件 —— 忽略文本层，全部走 OCR
为什么要单独设置配置文件

如果解析选项由各调用方自行决定，同一份文档在不同调用处会被读成不同结果。 因此把策略打包成配置文件 ——「表格乱掉」这类问题，先换一个配置文件试试是第一招。

一个字都没识别出来即视为«失败»

即使解析器报告成功，若正文为空也会以 ok: false 返回（REST 响应为 status: "empty"）。多数情况是 对没有文字层的扫描件未启用 OCR 就读取，请改用 scan 或 ocr 配置文件重新调用。

单份文档上限默认为 200 MiB（MAX_DOCUMENT_BYTES），超出则拒绝（REST 返回 413）。 代理路径会等待结果产出，但若超过 MCP_WAIT_TIMEOUT（默认 300 秒） 则以失败返回。

视觉 — vision_ 5 个​

用于看照片。无状态 —— 不保存图像，处理后即丢弃。

工具功能
vision_read_meter读取仪表（表盘·数字显示器）的 示值
vision_inspect从设备照片中查找 缺陷 —— 漏油·腐蚀·裂纹·破损·异物·过热
vision_ocr读取照片中的 文字 —— 铭牌·标签·标识·屏幕。韩语按韩语原样转写
vision_classify在给定标签中选其一 进行分类（需要 2 个以上标签）
vision_analyze针对照片自由提问
判定不一致时将拒绝作答

视觉对模棱两可的情况 不会硬猜。 同一张照片多次判定若未能达成一致，它会拒绝而不是编造答案 —— 因为在现场判定中，「看似合理的错误答案」远比「不知道」代价高。

工具一致性规则
vision_read_meter5 次中 4 次 —— 数值与单位必须 完全 一致（最严格）
vision_inspect · vision_classify3 次中 2 次 —— 判定（标签）必须一致
vision_analyze无一致性校验 —— 属自由描述，请勿用于读数·合格判定
vision_ocr3 次中 2 次 —— 去除空格后的字符串须一致。自 2026.10 再发布起由在线服务的 LLM 读取（此前使用文档理解的 docling OCR —— 无法识别韩语）。引擎可通过 VISION_OCR_ENGINE 回退 → 环境变量配置

数字主线 — thread_ 4~9 个​

用于查看工厂里 发生了什么、按什么顺序发生、什么与什么相连。返回的不是数值，而是事件与连接的 引用 —— 测量值 · KPI 请走平台集成 MCP 或时序洞察。

工具功能默认
thread_get_timeline针对某一设备 · 工单 · 标签，按时间顺序列出发生的事 —— 状态变化 · 报警发生/解除 · 工单开始/结束 · 计划停机，以及副驾驶的事件 · 建议 · 发现。时间窗最长 31 天开启
thread_trace_links对象之间 如何相连 —— 设备层级 · 标签 · 设备间供给/依赖 · 绑定到设备的作业指令 · 工序 · 零件 · 在该设备上运行过的工单 · 挂在该设备上的事件 · 建议。给定两个对象时返回最短路径开启
thread_today_work班组长的 今日作业清单（省略 date 时为当天）—— 针对当天计划的或正在 Platform 上运行的每道工序，给出就绪度 · 设备状态 · 所履行客户订单的余裕天数与风险 · 在等的物料 PO · 要用的图纸与版本标识。按客户余裕天数紧张程度排序开启
thread_impact_range延期的 PO · 供应商 · 设备 · 不良批次 波及到哪里 —— 作业指令 · 客户订单 · 客户。向前（延期波及之处：从 PO 行 · 供应商 · 零件 · 设备 · 设计变更 · 维修作业指令出发）或向后（质量追溯：从批次 · 序列号 · 不合格 · 刀具 · 样品出发）。用 as_of 查看过去时刻的连接，客户订单行附带 ERP 交期与剩余天数（D-n）。未连接的类别不是«没有»而是«未知»开启
thread_interval_production设备异常 · 报警 · 停机 区间内该设备在生产什么 —— 该区间的作业指令 · 批次 · 序列号（MES 执行时刻），以及这些批次波及的客户订单 · 客户。区间最长 31 天。没有 MES 时不是«什么都没运行»而是«未知»；仅通过区间之后产生的连接才波及到的客户，与确定影响分开记录开启
thread_explain_recovery零件延期时里程碑会推迟多少以及恢复方案（what-if）—— 数字由服务器的优化求解给出，AI 只负责转述。若启用了 PLM · QM 连接器，还会计入设计变更 · 不合格带来的额外延期；若 SCM 提供供应商供货能力，还能回答能否提前取得延期零件。同时附带受影响的客户订单行（customer_orders[]）与 ERP · SCM 不一致的 PO 值（purchase_order_conflicts[]）开启
thread_work_readiness班组长作业就绪度 —— 每道工序给出 GO · AT_RISK · NO_GO · UNKNOWN 及逐项理由开启
thread_part_revision_status判断某料号 · 版本当前是否可用 —— current · outdated · change_open · unknown开启
thread_check_tooling来自刀具管理连接器 —— 使用超期校准或已掉落的量具所做的测量、投入作业指令的刀具、不合格的候选原因开启
  • 全部为 只读（无需审批即可调用）。结果会压缩到 16,000 字以内返回。
  • 它们出现在服务器列表中的条件各不相同。get_timeline · trace_links · impact_range · interval_production 这四项始终存在；explain_recovery 需要配置好输入读取源（连接器注册表等）；today_work · work_readiness · part_revision_status · check_tooling 这四项仅在配置了连接器注册表（DT_PG_* · PI_DT_SECRET_KEY）时出现。因此数量为 4~9 个。
  • 自再发布（2026-10-20） 起，九项全部初始即开启（网关策略）。关闭的位置是 AI 管理控制台 › MCP 网关 › 工具 → MCP 网关
  • trace_links · get_timeline · impact_range · interval_production 结果中的对象（时间线中为事件的对象与头部），只有在该系统的连接器设有链接模板时， 才会附上原系统画面地址 open_url 与按钮文字 open_label。没有时两栏都不存在 → 数字主线 — 外部链接
  • 接入连接器与填充镜像数据属于管理控制台一侧 → 数字主线

工程计算 — eng_ 4 个​

用于 按公式计算 轴承故障频率 · NPSH 等工程量。这是为了不让模型靠脑补估算而设的服务器。 服务器为 plantpulse-engcalc-api（位于栈内 :7150，不对外开放），不依赖 DB · 卷 · LLM 即可运行。没有单独的开关 —— 它随栈一起常驻。

工具界面名称功能默认
eng_list_formulas工程公式列表可计算的公式列表开启
eng_formula工程公式计算具名公式 29 种 —— 返回结果的同时给出单位 · 代入步骤 · 出处开启
eng_unit_convert单位换算单位转换开启
eng_calc_eval表达式计算四则 · 指数等表达式计算。仅执行允许的运算，且对指数 · 长度 · 时间设有上限（不运行程序）开启
  • 全部为 只读，无需审批即可调用。
  • 密钥与其他后端相同，为 PI_INBOUND_API_KEY。若为空，服务器将 拒绝启动。

外部系统连接器不在这里接入​

MES · SCM · ERP · PLM · QM 等 外部系统的 MCP 连接器 在 AI 管理控制台 → 数字主线 → 集成地图 中注册。 需在那里通过适配性测试后才会启用，副驾驶则通过数字主线服务器来使用它们。

  • 若作为外部服务器接入 MCP 网关，连接器工具（以 mes_ · scm_ · sched_ · erp_ · plm_ · qm_ · cmms_ · tool_ · wms_ · lims_ · ehs_ 开头的工具） 无法启用 —— 这些工具只由数字主线中转。
  • 旧版本中若在副驾驶上注册过外部连接器，其记录会在再发布（2026-10-20） 中被删除。请在集成地图中重新注册并重新填写认证信息 → 数字主线

以 URL 接收的工具 —— 内部地址一律拒绝​

文档理解与视觉工具不接收文件，而是接收 URL。该 URL 是 AI 生成的字符串，若不加限制地抓取，AI 就可能借此读取只有容器内部才能访问的位置。因此在入口处就做拦截。

  • 仅接受 http · https。
  • 若地址解析到 环回 · 私有网段（10/8 · 172.16/12 · 192.168/16） · 链路本地（含云元数据），则 拒绝。重定向每跳转一次都会重新校验。
  • 大小上限 —— 文档 200 MiB，图片 32 MiB。

被拒绝时，工具会返回 ok: false 及 refused to fetch … 理由。

公司内部文件服务器的 URL «必须写入白名单»才能读取

像 http://192.168.x.x/… 这类位于 内网地址上的文档·图片 默认会被拒绝。把需要放行的主机写入 /etc/kopens/plantpulse-ai.env 的 FETCH_ALLOWED_HOSTS（多个用逗号分隔，默认为空），compose 会将其一并传给文档理解与视觉服务（自 2026.10 再发布起）。

  • 必须与 URL 中的主机名 完全一致（忽略大小写）。若像 files.example.local:8080 那样带端口，则只放行该端口。以 IP 访问的服务器直接写 IP。不支持通配符 · 网段。
  • 即使是已放行的主机，http · https 与大小上限依然适用；若经重定向跳到其他内部地址，仍会在那一步被拒绝。
  • 写入后执行 bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api 重建这两个服务。

→ 环境变量配置

命名规则​

后端工具名称采用 snake_case（vision_read_meter）。前缀由 MCP 网关添加，因此服务器文档中看到的名称（read_meter）与聊天中调用的名称（vision_read_meter）可能不同。

  • 两个服务器发出相同的公开名称时，先注册的一方胜出，后来者不公开（在 工具 画面中标为冲突）。修改后来服务器的前缀即可解决。

🔴 请勿手工抄录工具列表。 安装状态（启用了什么）的权威来源是 网关 DB，画面为 AI 管理控制台 › MCP 网关 › 工具，全量清单为网关 REST GET /api/v1/tools。网关在启动时及每 5 分钟重新读取各服务器的工具列表， 也可通过 服务器 画面的 重新发现 当场重新读取。

反方向 —— 副驾驶本身也是 MCP 服务器​

以上讲的都是 副驾驶«使用»工具。反过来，其他 AI 代理也可以把副驾驶当作工具来用，因为副驾驶会以 MCP 对外提供自身能力。

项目值
端点POST /mcp（末尾斜杠 /mcp/ 也接受）
协议JSON-RPC 2.0
认证与 /api/v1 相同 —— 仅限 X-API-Key（自 2026.10 再发布 6 起，登录会话返回 403）
工具功能
ask_plant自然语言提问 → 答案。所需的查询工具由副驾驶自行选择，并附带依据。以调用所用 API 密钥的主体（该密钥的持有人）权限提问；若 sessionId 留空，则以该主体为所有者新建一个会话
list_plant_tools副驾驶«当前»可触达的查询工具列表
daily_tasks晨报卡片（以 KST 为准）
为什么只有三个 —— 只开放读取

会产生变更的工具都附带人工审批流程，而通过 MCP 调用的一方并不了解该流程。因此 只开放查询。

这三个与 /api/v1 功能相同，并委托给同一实现 —— 同一能力以两种协议对外提供，但代码只有一套。一旦变成两套，就只会修好其中一边。

末尾斜杠两种都接受

/mcp 与 /mcp/ 都能工作。不同客户端调用的形式不一样，实际发生过 因为这一个字符导致每次调用都被 307 弹回 的情况。调用我们的一方不会踩到这个坑。

相关文档​