# node-opcua-modeler-mcp-server [![npm version](https://img.shields.io/npm/v/node-opcua-modeler-mcp-server.svg)](https://www.npmjs.com/package/node-opcua-modeler-mcp-server) [![npm downloads/month](https://img.shields.io/npm/dm/node-opcua-modeler-mcp-server.svg)](https://www.npmjs.com/package/node-opcua-modeler-mcp-server) [![npm downloads total](https://img.shields.io/npm/dt/node-opcua-modeler-mcp-server.svg)](https://www.npmjs.com/package/node-opcua-modeler-mcp-server) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io) An [MCP server](https://modelcontextprotocol.io) that gives AI agents access to the **OPC UA companion specification type system** — 817 types across 33 industrial namespaces, plus 1,533 engineering units — and lets agents **validate, generate, reverse-engineer, and create** OPC UA information models. Built on [node-opcua](https://github.com/node-opcua/node-opcua), the most widely used OPC UA stack for Node.js. ## Why? When an AI agent needs to build an OPC UA information model, it must know: - What **companion spec types** exist (DI, Machinery, Robotics, Machine Tools…) - What **components, properties, and methods** each type has - What **namespace dependencies** are required - What **engineering unit symbols** are valid (UNECE Rec. 20) This MCP server answers all of those questions — **offline, for free, in milliseconds**. ## Quick Start ### With Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "opcua-modeler": { "command": "npx", "args": ["-y", "node-opcua-modeler-mcp-server"], "env": { "OPCUA_MODELER_API_KEY": "stfv_your_api_key_here" } } } } ``` > **Note:** The API key is optional for discovery tools (offline) and `opcua_model_validate` (50 anonymous calls/day). It is required for `opcua_model_generate`, `opcua_model_reverse`, and `opcua_model_create`. Register at [opcua-modeler.sterfive.io](https://opcua-modeler.sterfive.io/signup) and create a key under **Settings → API** — the free tier gives 25 calls/day for 90 days; see [pricing](https://opcua-modeler.sterfive.io/pricing) for paid plans. ### With any MCP client ```bash npx node-opcua-modeler-mcp-server ``` The server communicates over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io). ### Using a local backend instead of the hosted API If you run the OPC UA Modeler CLI on the same machine, the model tools can be served from it instead of the hosted API — your YAML never leaves the host. Start the server (requires a licence that includes the `serve` entitlement): ```bash opcua-modeler serve ``` Then set one environment variable in your MCP client config: ```json { "mcpServers": { "opcua-modeler": { "command": "npx", "args": ["-y", "node-opcua-modeler-mcp-server"], "env": { "OPCUA_MODELER_BACKEND": "local" } } } } ``` No API key is needed in this mode — the client discovers the local endpoint and its credentials automatically. | Variable | Values | Purpose | |----------|--------|---------| | `OPCUA_MODELER_BACKEND` | `cloud` (default), `local` | Which backend serves the model tools | | `OPCUA_MODELER_API_KEY` | `stfv_…` | API key, `cloud` backend only | | `OPCUA_MODELER_API_URL` | URL | Override the hosted API base URL | **Notes** - The two backends are never mixed, and there is no fallback between them. If `local` is selected and no server is running, the call fails with instructions rather than silently sending your model to the hosted API. - The seven discovery tools are local to this package and work offline on either setting. - `opcua_model_create` (AI generation) is available on the `cloud` backend only. ## Tools ### `list_namespaces` List all 33 OPC UA companion spec namespaces with aliases, URIs, and dependencies. ``` → 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` Resolve the full dependency chain for companion spec aliases. Returns a topologically sorted list for the YAML `namespaces:` block. ``` → resolve_dependencies({ aliases: ["machineTool"] }) ← ["di", "ia", "machinery", "isa95JobControl", "machineryJobs", "machineTool"] ``` ### `list_types` List all ObjectTypes and VariableTypes defined in a companion spec namespace. ``` → list_types({ alias: "robotics" }) ← [ { "browseName": "MotionDeviceType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... }, { "browseName": "AxisType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... }, ... ] // 25 types ``` ### `get_type_details` Get the full structure of a type — components, properties, methods, interfaces, including inherited members. ``` → 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 for types across **all** companion specs by keyword. ``` → search_types({ query: "temperature" }) ← [ { "alias": "glass", "browseName": "MotorTemperatureTooHighEventType", ... }, { "alias": "padim", "browseName": "TemperatureMeasurementVariableType", ... }, { "alias": "amb", "browseName": "OverTemperatureConditionClassType", ... } ] ``` ### `find_reusable_block` Find reusable Interfaces and AddIns by capability — pass a member name or keyword and get the standard blocks that already expose it. Prefer composing an existing block over redefining its members by hand. ``` → 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` tells you how to apply it: `interface` goes in `interfaces:`, `addin` in `addIns:`. ### `find_engineering_unit` Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases. ``` → 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` ☁️ Fetch the YAML DSL grammar reference — the file header, top-level sections, type and instance syntax, and a list of common mistakes. **No API key required.** Served from the API rather than bundled into this package, so the reference an agent reads always matches the validator that will judge its output. ``` → get_dsl_reference() ← { "version": "1", "reference": "# OPC UA Modeler YAML DSL ..." } ``` ### `opcua_model_validate` ☁️ Validate an OPC UA YAML model for correctness. Returns diagnostics with severity, codes, messages, and line numbers. Works without an API key (limited to 50 calls/day per IP). ``` → opcua_model_validate({ yaml: "namespaces:\n di:\n..." }) ← { "valid": true, "diagnostics": [ { "severity": "warning", "code": "W001", "message": "...", "line": 42 } ] } ``` **By path (local stdio server only).** Pass `model_path` instead of `yaml`. With `OPCUA_MODELER_BACKEND=local`, the model's `imports:` then resolve from its own folder (beside it, then `deps/`), as in VS Code: an import that names only a `uri:` needs this, because a model sent as text resolves against the folder `opcua-modeler serve` was started in. The hosted connector never takes paths. ``` → opcua_model_validate({ model_path: "C:/models/cip/cip-example.model.yaml" }) ``` ### `opcua_model_generate` ☁️ Generate OPC UA NodeSet2.xml and the symbols CSV from a validated YAML model. Requires an API key. **Keep NodeIds stable.** The symbols CSV records the NodeId given to every node. A regeneration that does not pass it back allocates new ids, which breaks every server and client bound to the old ones. So each call must say what it is: | Call | Meaning | |---|---| | `symbols_csv: ""` | Regeneration: existing nodes keep their ids. Accepts the CSV text, or the base64 `symbols_csv` a previous call returned. | | `mode: "new"` | First generation: there are no symbols yet. | | `mode: "renumber"` | Allocate new ids on purpose. | | a self-contained `.opcua.yaml` stream | It carries its own symbol table, which is replayed. | A call with none of these is refused before reaching the backend with `SYMBOLS_DECISION_REQUIRED`, and the message says how to retry. **By path (local stdio server only).** Pass `model_path` instead of `yaml`. The server reads the model and its paired `.model.symbols.csv`, and writes `.Nodeset2.xml`, the CSV and, with `include_docs`, `.md` beside the model (or into `output_dir`): the same files and bytes as `opcua-modeler generate`. Unchanged files are not touched. Nothing large passes through the conversation: for the `demoRobot` sample the result is about 700 characters instead of about 71 KB of base64. `include_artifacts: "inline"` also returns the artefacts. With `OPCUA_MODELER_BACKEND=local`, the model's `deps/` folder is resolved too. The hosted connector never takes paths. ``` → 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."] } ``` **As text.** Pass `yaml`; the artefacts come back base64-encoded in `artifacts.nodeset2_xml` / `artifacts.symbols_csv`, with the same `symbols`, `hints` and `next_steps`. Hint codes: `INVALID`, `IDS_RENUMBERED`, `IDS_DROPPED`, `SYMBOLS_LOW_MATCH` (the CSV passed probably belongs to another model), `SAVE_SYMBOLS`, `SYMBOLS_UPDATED`, `STREAM_TABLE_NOT_UPDATED`, `WARNINGS_PRESENT`, `PREFER_STREAM`. Refusal codes: `SYMBOLS_DECISION_REQUIRED`, `SYMBOLS_REQUIRED`, `SYMBOLS_FILE_EXISTS`, `MODE_CONFLICT`. ### `opcua_model_reverse` ☁️ Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key. On the local stdio server, pass `xml_path` instead of `xml`: the file is read by the server, so even a multi-megabyte companion spec never passes through the conversation. ``` → opcua_model_reverse({ xml: "