19. MCP 服务器 (AI 助手联动)

MCP (Model Context Protocol) 服务器 是让像 Claude 这样的 AI 助手能够以 自然语言询问并诊断 Platform 现场数据的通道。助手可以读取标签值、收集报警上下文、浏览资产层级，甚至执行确认处理 (ack)。

它并非替代 REST API — 而是在 同一个 JVM 中调用相同的 V5 服务层，并直接使用 /api/v5/* 的认证、审计和速率限制。

项目	值
端点	`POST https://<server>/api/v5/mcp`
传输	Streamable HTTP, stateless — 不创建会话，因此重启安全
规格	MCP 2025-11-25 稳定版
提供	32 种工具 · 7 种资源 · 3 种提示词 · 自动补全 · 进度条 · Elicitation

配置方法

第 1 步 — 发行 `api_key`

MCP 不设单独的认证体系，而是 直接使用 V5 API 密钥。通过管理员发行的 api_token 进行交换。

curl -s -X POST "https://<server>/api/v5/auth" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"token":"<api_token>"}'
# 200: { "data": { "api_key": "..." }, "meta": { "status": "OK" }, "errors": null }

成功判定并非 «HTTP 200»

必须满足 meta.status 为 OK 且 data.api_key 不为空 才算成功。此外，503 并不意味着凭证错误 — 而是由于无法连接到令牌存储库而导致没有判定结果。根据响应类型应如何修正，请参阅开始使用 §1.8 中的表格。

令牌角色必须为 ADMIN 或 API

MCP 将包括读取调用在内的 全部请求通过 POST 发送。由于 V5 过滤器仅允许 ADMIN/API 角色 使用 POST·PUT·DELETE·PATCH，如果令牌角色为 USER，则 即使是读取工具也会被 403 拒绝。即便计划仅用于读取，令牌本身也请发行给 ADMIN/API。

第 2 步 — 在客户端注册

# Claude Code
claude mcp add --transport http plantpulse "https://<server>/api/v5/mcp" \
  --header "X-API-Key: <api_key>"

// Claude Desktop — .mcp.json
{
  "mcpServers": {
    "plantpulse": {
      "type": "http",
      "url": "https://<server>/api/v5/mcp",
      "headers": { "X-API-Key": "<api_key>" }
    }
  }
}

可以使用 Authorization: Bearer <api_key> 代替 X-API-Key。如果认证失败，将收到 401 及 WWW-Authenticate: Bearer 请求头。

从浏览器连接的客户端需要注册 Origin

为了防止 DNS 重绑定，系统会对 Origin 请求头进行白名单检查。像 Claude Desktop · Claude Code 这样不发送 Origin 的原生客户端始终允许，但 基于浏览器的客户端必须在 AI_MCP_ALLOWED_ORIGINS 中注册。默认值为空，注册前全部为 403。

32 种工具

包含 31 种读取工具 + 1 种写入工具 (acknowledge_alarm)。在设计层面 不提供 删除、控制或更改设置的工具。

工具	功能	必填参数
`search_entities`	通过名称 · ID · 描述查找领域对象 (名称 → ID)。无 ID 时优先调用	`query`
`list_latest_tag_values`	标签当前值	`tag_ids`
`get_tag_history`	标签期间历史	`tag_id`, `from`
`get_asset_snapshot`	设备前标签快照	`asset_id`
`list_alarms`	报警列表	—
`acknowledge_alarm`	报警确认 — 必填原因 (`comment`)，记录于审计	`alarm_seq`, `comment`
`get_alarm_context`	报警原因诊断包	`alarm_seq`
`list_alarm_suppressions`	隐藏报警 (隐藏 · 抑制 · 服务排除)	—
`get_alarm_performance`	报警系统性能 — 与 `GET /alarm/performance` 相同的值	`scope_type`, `scope_id`
`get_edge_status`	单个 Edge 网关状态	`edge_id`
`list_edge_status`	Edge 网关列表	—
`get_edge_connection_history`	Edge 健康历史 (日区间)	`edge_id`, `date`
`list_opc_connections`	OPC 采集连接列表	—
`get_asset_tree`	设备层级树	`asset_id`
`get_asset_by_external`	通过 MES · EAM 编号查找层级节点	`external_system`, `external_id`
`get_site_overview`	站点本体概览	`site_id`
`trace_asset_relations`	关系追踪 — 上游 · 下游影响	`entity_id`
`query_knowledge_graph`	本体 SPARQL 查询	`sparql`
`list_asset_documents`	设备附件文档	`asset_id`
`get_asset_timeline`	设备事件时间线	`asset_id`
`list_work_orders`	工单列表	—
`get_work_order_kpi`	工单详情 + KPI	`order_id`
`get_work_order_by_external`	通过 MES · ERP 编号查找工单	`external_system`, `external_id`
`get_asset_kpi`	设备期间 KPI 摘要 (状态 · 报警 · OEE)	`asset_id`, `from`
`get_asset_schedule`	设备 · 站点日历 (班次 · 停机 · 节假日)	`asset_id`
`list_maintenance_orders`	维修工单 (调用 · 维修 · 零件 · ISO 代码)	`scope_id`
`get_maintenance_summary`	维修摘要 (部位 · 故障模式 · 等待/维修 · 重复)	`scope_id`
`get_maintenance_order_by_external`	通过 CMMS 编号查找维修工单	`external_system`, `external_id`
`get_connection_health`	设备层级健康汇总	—
`get_current_time`	服务器当前时间	—
`get_eql_reference`	控制台输入框的 EQL 引用 (语法 · 事件类型 · 函数 · 示例)	`surface`
`validate_eql`	EQL 编译检查 (不部署)	`surface`, `eql`

维修行的键与 V5 维修工单相同 — 为 maintenance_order_id (字符) · maintenance_kind_code · status_code · failure_record_seq · maintenance_plan_id (字符) · failure_mode_code · maintainable_item_code。由于 maintenance_order_id 是 MAINTENANCE_ORDER_000001 或旧行的数字字符串 ("12")，请勿将其视为数字处理。

严重程度值为 ERROR · WARN · INFO

get_connection_health 界面标签中显示的 critical/major/minor 是显示用分桶。在 list_alarms(severity=) 过滤器中必须使用 规范值 才能匹配。

7 种资源

这是在助手调用工具之前用来浏览「有哪些内容」的只读通道。

pp://sites · pp://ontology/{site_id} · pp://assets/{site_id}/tree · pp://uns/{site_id} · pp://catalog/{store}/tables · pp://catalog/{store}/{table}/schema · pp://domain-graph

{store} 仅允许 metastore · eventstore · analytics。

3 种提示词

名称	流程
`diagnose-asset`	资产故障诊断 — 报警 → 上下文 → 标签历史 → 连接 → 下游影响 → 原因候选
`shift-briefing`	班次简报 — 健康 → 报警 → 工单/KPI → 交接摘要
`alarm-triage`	报警分类 — 列表 → 优先级 → 建议 → (批准后) 确认处理

设置 — `pp.mm_config` 的 `AI_MCP_*`

非配置文件

正本为 PostgreSQL pp.mm_config 表。plantpulse-ai.properties 已删除且读取路径已消失 — 请参阅属性参考。

键	默认值	含义
`AI_MCP_ENABLED`	`true`	若为 `false`，则 `/api/v5/mcp` 返回 404
`AI_MCP_ALLOWED_ORIGINS`	(空值)	浏览器客户端 Origin 白名单 (逗号分隔)
`AI_MCP_TREE_MAX_NODES`	`2000`	树响应节点上限
`AI_MCP_TREE_DEFAULT_DEPTH`	`2`	`get_asset_tree` 默认深度
`AI_MCP_TREE_MAX_NODE_TAGS`	`100`	单个节点承载的标签数
`AI_MCP_TREE_ONTOLOGY_MAX_CHARS`	`200000`	本体响应字符数上限
`AI_MCP_TREE_ONTOLOGY_DEFAULT_DEPTH`	`3`	`trace_asset_relations` 默认深度
`AI_MCP_TREE_ONTOLOGY_MAX_TAGS`	`500`	本体响应整体的标签行预算

修改值的路径仅有一种 — 通过设置界面 (/config/index) 或修改 pp.mm_config。由于 MCP 在每次请求时读取缓存，因此 无需重启。

🔴 PP_AI_MCP_* 环境变量不生效

无论首次启动与否均如此。将环境变量移至表格的 Seeder 与 ${PP_AI_*} 替换层已于 2026-09-18 移除。即使配置了环境变量，系统也会 静默忽略 而不报错 — 记录此处是因为「已配置但未生效」是最难排查的故障。缺失的键将读取上述表格的默认值。

审计与安全机制

认证 · 速率限制 · 审计 同样经过 /api/v5/* 过滤器链。
acknowledge_alarm 记录独立审计 (操作者 MCP)。若缺失原因，将要求助手补全；对于不具备该功能的客户端，则通知「原因必填」。
排除在一般变更审计钩子之外。由于包括读取在内的所有操作均为 POST，若挂载钩子，每次调用都会被误记为变更。
无令牌传递路径 — 由于直接调用同一 JVM 服务层，因此不存在将接收到的凭证传递给其他系统的路径。

配置方法​

第 1 步 — 发行 api_key​

第 2 步 — 在客户端注册​

32 种工具​

7 种资源​

3 种提示词​

设置 — pp.mm_config 的 AI_MCP_*​

审计与安全机制​

相关阅读​