node-opcua-modeler-mcp-server

# 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** — 589 types across 22 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 25 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_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 }
```

### `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 5 calls/day).

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

### `opcua_model_generate` ☁️

Generate OPC UA NodeSet2.xml and Symbols.CSV from a validated YAML model. Returns base64-encoded artifacts. Requires an API key.

```
→ opcua_model_generate({ yaml: "namespaces:\n  di:\n...", include_docs: false })
← {
    "valid": true,
    "artifacts": {
      "nodeset2_xml": "PD94bWwg...",
      "symbols_csv": "bmFtZSxu..."
    },
    "diagnostics": []
  }
```

### `opcua_model_reverse` ☁️

Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key.

```
→ 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 (25)

| Alias | Specification | Types |
|-------|--------------|-------|
| `padim` | OPC UA for PA-DIM | 101 |
| `ijtBase` | OPC UA for IJT Base | 65 |
| `machineTool` | OPC UA for Machine Tools | 63 |
| `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 |
| `robotics` | OPC UA for Robotics | 25 |
| `ia` | OPC UA for Industrial Automation | 20 |
| `amb` | OPC UA for AMB | 18 |
| `autoId` | OPC UA for AutoID | 18 |
| `metalForming` | OPC UA for Metal Forming | 16 |
| `machinery` | OPC UA for Machinery | 15 |
| `gds` | OPC UA GDS | 14 |
| `woodworking` | OPC UA for Woodworking | 13 |
| `cnc` | OPC UA for CNC Systems | 12 |
| | *…and 5 more* | |
| **Total** | **22 namespaces** | **589 types** |

### Engineering Units

1,533 official UNECE Rec. 20 symbols plus 134 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 Work