# OPC UA Modeler [Health: Active]

**Category:** 🏭 Industrial & IoT  
**Repository:** https://github.com/node-opcua/node-opcua-modeler-mcp-server  
**GitHub Stars:** 2  
**npm Downloads (last month):** 346  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/opc-ua-modeler

## Description
OPC UA companion spec types, namespace dependencies, and engineering units for AI agents

## Tools
Capabilities this server exposes over MCP:

- **list_namespaces** — List all 33 OPC UA companion spec namespaces with aliases, URIs, and dependencies.
- **resolve_dependencies** — Resolve the full dependency chain for companion spec aliases. Returns a topologically sorted list for the YAML `namespaces:` block.
- **list_types** — List all ObjectTypes and VariableTypes defined in a companion spec namespace.
- **get_type_details** — Get the full structure of a type — components, properties, methods, interfaces, including inherited members.
- **search_types** — Search for types across **all** companion specs by keyword.
- **find_reusable_block** — Find reusable Interfaces and AddIns by capability — pass a member name or keyword
- **find_engineering_unit** — Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "opc-ua-modeler": {
    "command": "npx",
    "args": ["-y","node-opcua-modeler-mcp-server"]
  }
}
```

## Documentation & README

# 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: "<previous 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 `<name>.model.symbols.csv`, and writes `<name>.Nodeset2.xml`, the CSV and, with `include_docs`, `<name>.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: "<?xml version=..." })
← {
    "yaml": "namespaces:\n  di:\n...",
    "diagnostics": []
  }
```

### `opcua_model_create` ☁️

Generate an OPC UA YAML model from a natural language description using AI. The AI will auto-detect relevant companion specs, generate a validated model with documentation, and auto-correct validation errors. Requires an API key.

```
→ 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 }
  }
```

## Coverage

### Companion Specifications (33)

| Alias | Specification | Types |
|-------|--------------|-------|
| `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 |
| | *…and 13 more* | |
| **Total** | **32 namespaces with types** | **817 types** |

The registry holds **33** specs; `irdi` is a dictionary-entry namespace and
defines no ObjectTypes or VariableTypes. These figures come from
`catalog/catalog.json` and are asserted against it by
`test/catalog-coverage.test.ts`, so they cannot drift silently.

### Engineering Units

1,533 official UNECE Rec. 20 symbols plus 136 natural language aliases (e.g., "celsius" → °C, "revolutions per minute" → r/min). Every alias resolves to a symbol the modeler engine accepts — the lookup never invents one.

## How It Works

The server ships with a pre-generated `catalog.json` containing all type information extracted from OPC Foundation's official NodeSet2.xml files via [node-opcua](https://github.com/node-opcua/node-opcua). All queries are answered from this static catalog — **no network required, no API key needed**.

```
┌──────────────────────────────────────────────────┐
│  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)                      │
└──────────────────────────────────────────────────┘
```

## Use Cases

- **AI-assisted OPC UA modeling** — agents can discover types, resolve dependencies, and validate unit symbols before generating YAML/XML models
- **Copilot integration** — add OPC UA awareness to coding assistants
- **Industrial digital twin design** — explore companion spec type hierarchies interactively
- **Learning OPC UA** — ask an AI to explain types and their relationships

## Requirements

- Node.js ≥ 18

## Related

- [OPC UA Modeler on GitHub](https://github.com/node-opcua/opcua-modeler) — the open YAML DSL specification, the JSON Schema and example models; the place for questions and issues about the language
- [OPC UA Modeler — web app](https://opcua-modeler.sterfive.io) — Create, validate, and generate OPC UA information models in the browser
- [Product page](https://www.sterfive.com/product/opcua-modeler) — OPC UA Modeler overview, features, and licensing
- [Documentation](https://opcua-modeler.doc.sterfive.com) — Guides, YAML DSL reference, and how-tos
- [Specification reference](https://opcua-modeler.doc.sterfive.com/specification/spec.html) — Rendered OPC UA information-model specification
- [node-opcua](https://github.com/node-opcua/node-opcua) — Full OPC UA stack for Node.js
- [Model Context Protocol](https://modelcontextprotocol.io) — Open protocol for AI tool integration

## Licensing

Three layers, stated once:

| What | Licence |
|------|---------|
| **This package** (`node-opcua-modeler-mcp-server`, the MCP client and its catalog) | [Apache License 2.0](https://github.com/node-opcua/node-opcua-modeler-mcp-server/blob/HEAD/LICENSE) from version 1.5.0 — see [NOTICE](https://github.com/node-opcua/node-opcua-modeler-mcp-server/blob/HEAD/NOTICE) for trademark and third-party notices. Versions 1.0–1.4.x were published under MIT and remain so. |
| **The hosted OPC UA Modeler API** (`opcua-modeler.sterfive.io/api/v1`) that the cloud backend calls | [Sterfive API Terms of Use](https://opcua-modeler.sterfive.io/terms) — anonymous discovery, free and paid plans. |
| **The OPC UA Modeler CLI and `opcua-modeler serve`** (the local backend) | Sterfive commercial licence — see the [product page](https://www.sterfive.com/product/opcua-modeler). |

"OPC UA Modeler" and "Sterfive" are trademarks of Sterfive SAS; the Apache
licence grants no rights to them. Contributions are accepted under the
[Developer Certificate of Origin](https://github.com/node-opcua/node-opcua-modeler-mcp-server/blob/HEAD/CONTRIBUTING.md).

© [Sterfive SAS](https://www.sterfive.com)