OPC UA Modeler

node-opcua-modeler-mcp-server

一个 MCP 服务，可让 AI Agent 访问 OPC UA 配套规范类型系统——涵盖 33 个工业命名空间中的 817 种类型，以及 1,533 种工程单位，并允许 Agent 验证、生成、逆向工程和创建 OPC UA 信息模型。

基于 node-opcua 构建，这是应用最广泛的 Node.js OPC UA 协议栈。

为什么选择它？

当 AI Agent 需要构建 OPC UA 信息模型时，必须了解：

• 有哪些 配套规范类型（DI、Machinery、Robotics、Machine Tools……）
• 每种类型有哪些 组件、属性和方法
• 需要哪些 命名空间依赖项
• 哪些 工程单位符号有效（UNECE Rec. 20）

此 MCP 服务可回答所有这些问题——离线、免费、毫秒级响应。

快速开始

使用 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "opcua-modeler": {
      "command": "npx",
      "args": ["-y", "node-opcua-modeler-mcp-server"],
      "env": {
        "OPCUA_MODELER_API_KEY": "stfv_your_api_key_here"
      }
    }
  }
}

**注意：**发现工具（离线）和 opcua_model_validate（每天 50 次匿名调用）无需 API 密钥。opcua_model_generate、opcua_model_reverse 和 opcua_model_create 则需要 API 密钥。请在 opcua-modeler.sterfive.io 注册并在 Settings → API 下创建密钥——免费套餐在 90 天内每天可调用 25 次；付费套餐请参阅定价。

使用任意 MCP 客户端

npx node-opcua-modeler-mcp-server

该服务使用 Model Context Protocol 通过 stdio 通信。

使用本地后端，而非托管 API

如果你在同一台机器上运行 OPC UA Modeler CLI，则可通过它提供模型工具，而非使用托管 API——你的 YAML 不会离开本机。

启动服务（需要包含 serve 权限的许可证）：

opcua-modeler serve

然后在 MCP 客户端配置中设置一个环境变量：

{
  "mcpServers": {
    "opcua-modeler": {
      "command": "npx",
      "args": ["-y", "node-opcua-modeler-mcp-server"],
      "env": {
        "OPCUA_MODELER_BACKEND": "local"
      }
    }
  }
}

此模式下无需 API 密钥——客户端会自动发现本地端点及其凭据。

变量	值	用途
OPCUA_MODELER_BACKEND	cloud（默认）、local	用于提供模型工具的后端
OPCUA_MODELER_API_KEY	stfv_…	API 密钥，仅用于 cloud 后端
OPCUA_MODELER_API_URL	URL	覆盖托管 API 基础 URL

注意事项

• 两种后端不会混用，也不会在两者之间回退。如果选择了 local，但没有正在运行的服务，调用会失败并显示说明，而不会悄悄将你的模型发送到托管 API。
• 七种发现工具属于此软件包本地工具，在任一设置下都可离线使用。
• opcua_model_create（AI 生成）仅适用于 cloud 后端。

工具

list_namespaces

列出全部 33 个 OPC UA 配套规范命名空间及其别名、URI 和依赖项。

→ list_namespaces()
← [
    { "alias": "di", "name": "OPC UA for Devices", "uri": "http://opcfoundation.org/UA/DI/", "dependencies": [] },
    { "alias": "robotics", "name": "OPC UA for Robotics", "uri": "http://opcfoundation.org/UA/Robotics/", "dependencies": ["di", "ia"] },
    ...
  ]

resolve_dependencies

解析配套规范别名的完整依赖链。返回按拓扑排序的列表，供 YAML 的 namespaces: 块使用。

→ resolve_dependencies({ aliases: ["machineTool"] })
← ["di", "ia", "machinery", "isa95JobControl", "machineryJobs", "machineTool"]

list_types

列出配套规范命名空间中定义的所有 ObjectTypes 和 VariableTypes。

→ list_types({ alias: "robotics" })
← [
    { "browseName": "MotionDeviceType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... },
    { "browseName": "AxisType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... },
    ...
  ]   // 25 types

get_type_details

获取类型的完整结构——包括组件、属性、方法、接口及继承的成员。

→ get_type_details({ alias: "robotics", browseName: "MotionDeviceType" })
← {
    "browseName": "MotionDeviceType",
    "kind": "ObjectType",
    "subtypeOf": "di:ComponentType",
    "interfaces": ["di:IVendorNameplateType", "di:ITagNameplateType"],
    "components": [
      { "browseName": "robotics:Axes", "nodeClass": "Object", "typeDefinition": "FolderType", "modellingRule": "Mandatory" },
      { "browseName": "robotics:PowerTrains", "nodeClass": "Object", "typeDefinition": "FolderType", "modellingRule": "Mandatory" },
      ...
    ],
    "properties": [
      { "browseName": "di:Manufacturer", "dataType": "LocalizedText", "modellingRule": "Mandatory" },
      { "browseName": "robotics:MotionDeviceCategory", "dataType": "MotionDeviceCategoryEnumeration", "modellingRule": "Mandatory" },
      ...
    ]
  }

search_types

按关键字在所有配套规范中搜索类型。

→ search_types({ query: "temperature" })
← [
    { "alias": "glass", "browseName": "MotorTemperatureTooHighEventType", ... },
    { "alias": "padim", "browseName": "TemperatureMeasurementVariableType", ... },
    { "alias": "amb", "browseName": "OverTemperatureConditionClassType", ... }
  ]

find_reusable_block

按能力查找可复用的 Interfaces 和 AddIns——传入成员名称或关键字， 即可获取已包含该成员的标准块。优先组合现有块，而不是手动重新定义其成员。

→ find_reusable_block({ query: "SerialNumber" })
← [
    {
      "browseName": "di:IVendorNameplateType",
      "alias": "di",
      "kind": "interface",
      "matchedMembers": ["di:SerialNumber"],
      "members": ["di:Manufacturer", "di:Model", "di:SerialNumber", ...]
    },
    {
      "browseName": "machinery:MachineIdentificationType",
      "alias": "machinery",
      "kind": "addin",
      "matchedMembers": ["di:SerialNumber"],
      "members": ["machinery:Location", "di:SerialNumber", ...]
    }
  ]

kind 指明了如何应用它：interface 放在 interfaces: 中，addin 放在 addIns: 中。

find_engineering_unit

查找官方 UNECE Rec. 20 工程单位符号。支持模糊匹配和自然语言别名。

→ find_engineering_unit({ query: "celsius" })
← { "symbol": "°C", "matchType": "alias", "confidence": 1 }

→ find_engineering_unit({ query: "revolutions per minute" })
← { "symbol": "r/min", "matchType": "alias", "confidence": 1 }

→ find_engineering_unit({ query: "bar" })
← { "symbol": "bar", "matchType": "exact", "confidence": 1 }

get_dsl_reference ☁️

获取 YAML DSL 语法参考——文件头、顶层分段、类型和实例语法，以及常见错误列表。无需 API 密钥。

参考内容由 API 提供，而非打包在此软件包中，因此 Agent 读取的参考内容始终与评判其输出的验证器一致。

→ get_dsl_reference()
← { "version": "1", "reference": "# OPC UA Modeler YAML DSL ..." }

opcua_model_validate ☁️

验证 OPC UA YAML 模型的正确性。返回包含严重性、代码、消息和行号的诊断信息。无需 API 密钥即可使用（每个 IP 每天最多 50 次调用）。

→ opcua_model_validate({ yaml: "namespaces:\n  di:\n..." })
← {
    "valid": true,
    "diagnostics": [
      { "severity": "warning", "code": "W001", "message": "...", "line": 42 }
    ]
  }

按路径操作（仅限本地 stdio 服务）。 传入 model_path 而非 yaml。当使用 OPCUA_MODELER_BACKEND=local 时，模型的 imports: 会从模型所在文件夹解析（先查同一文件夹，再查 deps/），与 VS Code 中的行为相同：对于只指定了 uri: 的导入，需要使用此方式，因为以文本形式发送的模型会相对于启动 opcua-modeler serve 时所在的文件夹进行解析。托管连接器不接受路径。

→ opcua_model_validate({ model_path: "C:/models/cip/cip-example.model.yaml" })

opcua_model_generate ☁️

根据已验证的 YAML 模型生成 OPC UA NodeSet2.xml 和符号 CSV。需要 API 密钥。

保持 NodeId 稳定。 符号 CSV 会记录分配给每个节点的 NodeId。重新生成时若不传回该 CSV，就会分配新的 ID，导致所有绑定旧 ID 的服务和客户端失效。因此，每次调用都必须说明生成类型：

调用	含义
symbols_csv: "<previous CSV>"	重新生成：现有节点保留原 ID。接受 CSV 文本，或先前调用返回的 base64 symbols_csv。
mode: "new"	首次生成：尚无符号。
mode: "renumber"	有意分配新 ID。
一个自包含的 .opcua.yaml 流	流中包含自己的符号表，并会重放该表。

如果调用中未包含上述任何一项，系统会在请求到达后端前拒绝该调用，并返回 SYMBOLS_DECISION_REQUIRED，同时说明如何重试。

按路径操作（仅限本地 stdio 服务）。 传入 model_path 而非 yaml。服务会读取模型及其配套的 <name>.model.symbols.csv，并在模型旁边（或 output_dir 中）写入 <name>.Nodeset2.xml、CSV，以及在启用 include_docs 时写入 <name>.md：生成的文件和字节内容与 opcua-modeler generate 相同。未更改的文件不会被触碰。大量内容不会经过对话传输：对于 demoRobot 示例，结果约为 700 个字符，而非约 71 KB 的 base64。include_artifacts: "inline" 也会返回这些工件。使用 OPCUA_MODELER_BACKEND=local 时，也会解析模型的 deps/ 文件夹。托管连接器不接受路径。

→ opcua_model_generate({ model_path: "models/pump.model.yaml" })
← {
    "valid": true,
    "mode": "update",
    "symbols_source": "paired-file",
    "symbols": { "reused": 41, "new": 1, "dropped": 0, "renumbered": 0, "match": 1,
                 "new_names": ["Pump_Temperature"], "dropped_names": [] },
    "files": [
      { "role": "nodeset", "path": ".../pump.model.Nodeset2.xml", "bytes": 54210, "status": "written" },
      { "role": "symbols", "path": ".../pump.model.symbols.csv", "bytes": 1312, "status": "written" }
    ],
    "diagnostics": [],
    "hints": [{ "code": "SYMBOLS_UPDATED", "level": "info", "message": ".../pump.model.symbols.csv updated: 1 new id(s) (Pump_Temperature)." }],
    "next_steps": ["Commit pump.model.Nodeset2.xml, pump.model.symbols.csv with the model."]
  }

以文本形式操作。 传入 yaml；工件会以 base64 编码的形式返回在 artifacts.nodeset2_xml / artifacts.symbols_csv 中，同时返回相同的 symbols、hints 和 next_steps。

提示代码：INVALID、IDS_RENUMBERED、IDS_DROPPED、SYMBOLS_LOW_MATCH（传入的 CSV 可能属于另一个模型）、SAVE_SYMBOLS、SYMBOLS_UPDATED、STREAM_TABLE_NOT_UPDATED、WARNINGS_PRESENT、PREFER_STREAM。拒绝代码：SYMBOLS_DECISION_REQUIRED、SYMBOLS_REQUIRED、SYMBOLS_FILE_EXISTS、MODE_CONFLICT。

opcua_model_reverse ☁️

将 NodeSet2.xml 文件逆向转换为 YAML DSL 格式。需要 API 密钥。在本地 stdio 服务上，传入 xml_path 而非 xml：文件由服务读取，因此即使是数 MB 的配套规范也不会经过对话传输。

→ opcua_model_reverse({ xml: "<?xml version=..." })
← {
    "yaml": "namespaces:\n  di:\n...",
    "diagnostics": []
  }

opcua_model_create ☁️

使用 AI 根据自然语言描述生成 OPC UA YAML 模型。AI 会自动检测相关的配套规范，生成经过验证并附带文档的模型，并自动修正验证错误。需要 API 密钥。

→ opcua_model_create({ prompt: "A robotic welding cell with two robot arms, each having 6 axes, temperature monitoring on each motor" })
← {
    "success": true,
    "yaml": "namespaces:\n  di:\n  robotics:\n...",
    "attempts": 2,
    "diagnostics": [],
    "model": "gemini-2.5-pro",
    "tokens": { "input": 4200, "output": 1800 }
  }

→ opcua_model_create({ prompt: "A CNC lathe with spindle speed and temperature", forceSpecs: ["di", "cnc"] })
← {
    "success": true,
    "yaml": "namespaces:\n  di:\n  cnc:\n...",
    "attempts": 1,
    "diagnostics": [],
    "model": "gemini-2.5-pro",
    "tokens": { "input": 3500, "output": 1200 }
  }

覆盖范围

配套规范（33 项）

别名	规范	类型数
padim	OPC UA for PA-DIM	101
ijtBase	OPC UA for IJT Base	65
machineTool	OPC UA for Machine Tools	63
scales	OPC UA for Scales	58
lads	OPC UA for Laboratory Devices	53
di	OPC UA for Devices	44
glass	OPC UA for Glass Manufacturing	36
machineVision	OPC UA for Machine Vision	36
adi	OPC UA for Analyzer Devices	35
commercialKitchenEquipment	OPC UA for Commercial Kitchen Equipment	35
i4aas	OPC UA for I4AAS	32
fxAc	OPC UA FX Automation Component	28
robotics	OPC UA for Robotics	25
fxCm	OPC UA FX Connection Manager	24
ia	OPC UA for Industrial Automation	20
amb	OPC UA for AMB	18
autoId	OPC UA for AutoID	18
iolink	OPC UA for IO-Link	16
metalForming	OPC UA for Metal Forming	16
	…还有 13 项
总计	包含类型的 32 个命名空间	817 种类型

注册表包含 33 项规范；irdi 是一个词典条目命名空间，不定义 ObjectTypes 或 VariableTypes。这些数据来自 catalog/catalog.json，并由 test/catalog-coverage.test.ts 对其进行断言，因此不会悄然偏离。

工程单位

1,533 个官方 UNECE Rec. 20 符号，以及 136 个自然语言别名（例如，“celsius” → °C，“revolutions per minute” → r/min）。每个别名都会解析为建模引擎接受的符号；查询绝不会凭空生成符号。

工作原理

该服务附带预生成的 catalog.json，其中包含通过 node-opcua 从 OPC Foundation 官方 NodeSet2.xml 文件中提取的所有类型信息。所有查询均由此静态目录作答——无需联网，也不需要 API 密钥。

┌──────────────────────────────────────────────────┐
│  node-opcua-modeler-mcp-server                   │
│                                                  │
│  LOCAL TOOLS (offline, free)                      │
│  ┌────────────────────────────────────────┐       │
│  │ catalog.json (1.7 MB)                  │       │
│  │ • 33 companion spec registries         │       │
│  │ • 817 type summaries + details         │       │
│  │ • 1,533 engineering units              │       │
│  └────────────────────────────────────────┘       │
│  7 tools → query the catalog                     │
│                                                  │
│  CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
│  5 tools → reference / validate / generate /     │
│           reverse / create                       │
│                                                  │
│  stdio transport (JSON-RPC)                      │
└──────────────────────────────────────────────────┘

使用场景

• AI 辅助 OPC UA 建模 — Agent 可以在生成 YAML/XML 模型前发现类型、解析依赖项并验证单位符号
• Copilot 集成 — 为编码助手添加 OPC UA 相关能力
• 工业数字孪生设计 — 交互式探索配套规范的类型层级
• 学习 OPC UA — 让 AI 解释类型及其关系

要求

• Node.js ≥ 18

相关链接

• GitHub 上的 OPC UA Modeler — 开放的 YAML DSL 规范、JSON Schema 和示例模型；可在此提出有关该语言的问题和问题报告
• OPC UA Modeler — Web 应用 — 在浏览器中创建、验证和生成 OPC UA 信息模型
• 产品页面 — OPC UA Modeler 概览、功能和许可信息
• 文档 — 指南、YAML DSL 参考和操作教程
• 规范参考 — 渲染后的 OPC UA 信息模型规范
• node-opcua — 完整的 Node.js OPC UA 协议栈
• Model Context Protocol — 用于 AI 工具集成的开放协议

许可

分为三个部分，统一说明：

内容	许可
本软件包（node-opcua-modeler-mcp-server、MCP 客户端及其目录）	自 1.5.0 版本起采用 Apache License 2.0——商标及第三方声明请参阅 NOTICE。1.0–1.4.x 版本采用 MIT 许可发布，且仍受该许可约束。
托管的 OPC UA Modeler API（opcua-modeler.sterfive.io/api/v1），由云端后端调用	Sterfive API 使用条款——匿名发现，提供免费和付费计划。
OPC UA Modeler CLI 和 opcua-modeler serve（本地后端）	Sterfive 商业许可——请参阅产品页面。

“OPC UA Modeler”和“Sterfive”是 Sterfive SAS 的商标；Apache 许可不授予对这些商标的任何权利。我们依据开发者原创声明接受贡献。

© Sterfive SAS