node-opcua-modeler-mcp-server 1.6.1 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,8 +5,9 @@
5
5
  [![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)
6
6
  [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
7
7
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
8
+ [![mcptry](https://mcptry.com/badge/io.github.node-opcua/node-opcua-modeler-mcp-server)](https://mcptry.com/servers/io.github.node-opcua/node-opcua-modeler-mcp-server)
8
9
 
9
- 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.
10
+ 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.
10
11
 
11
12
  Built on [node-opcua](https://github.com/node-opcua/node-opcua), the most widely used OPC UA stack for Node.js.
12
13
 
@@ -42,6 +43,36 @@ Add to your `claude_desktop_config.json`:
42
43
 
43
44
  > **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.
44
45
 
46
+ ### With VS Code (GitHub Copilot)
47
+
48
+ Add to `.vscode/mcp.json`. VS Code's top-level key is `servers`, not
49
+ `mcpServers`; a file copied from the Claude Desktop example is silently ignored.
50
+
51
+ ```json
52
+ {
53
+ "inputs": [
54
+ { "type": "promptString", "id": "opcua-modeler-api-key", "description": "OPC UA Modeler API key (optional)", "password": true }
55
+ ],
56
+ "servers": {
57
+ "opcua-modeler": {
58
+ "type": "stdio",
59
+ "command": "npx",
60
+ "args": ["-y", "node-opcua-modeler-mcp-server"],
61
+ "env": { "OPCUA_MODELER_API_KEY": "${input:opcua-modeler-api-key}" }
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
67
+ Click **Start** above the server entry, then use Copilot Chat in **Agent** mode
68
+ with the tools ticked under the tools icon. **MCP: List Servers → Show Output**
69
+ shows why a server failed to start.
70
+
71
+ When VS Code is connected to **WSL**, this server runs inside WSL and needs
72
+ Node.js there. VS Code does not start it from an interactive shell, so an nvm
73
+ install is not on its `PATH`: set `command` to the absolute path printed by
74
+ `which npx`.
75
+
45
76
  ### With any MCP client
46
77
 
47
78
  ```bash
@@ -50,6 +81,12 @@ npx node-opcua-modeler-mcp-server
50
81
 
51
82
  The server communicates over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io).
52
83
 
84
+ ### As a remote connector (Mistral, claude.ai, any streamable-HTTP client)
85
+
86
+ Use the hosted endpoint `https://api.opcua-modeler.sterfive.io/mcp`, or host your
87
+ own with `node-opcua-modeler-mcp-http` (or `--http`), Docker, or the bundled
88
+ Caddy compose file for HTTPS: see [docs/http-hosting.md](docs/http-hosting.md).
89
+
53
90
  ### Using a local backend instead of the hosted API
54
91
 
55
92
  If you run the OPC UA Modeler CLI on the same machine, the model tools can be
@@ -94,12 +131,21 @@ its credentials automatically.
94
131
  - The seven discovery tools are local to this package and work offline on either
95
132
  setting.
96
133
  - `opcua_model_create` (AI generation) is available on the `cloud` backend only.
134
+ - `serve` and this MCP server must run as the same user on the same system: they
135
+ talk over a named pipe or Unix socket, which cannot cross from Windows into
136
+ WSL. Under WSL, start `serve` in a WSL terminal.
137
+ - On Linux, macOS and WSL, `serve` publishes its discovery file in
138
+ `$XDG_RUNTIME_DIR/opcua-modeler/` and copies it to `/tmp/opcua-modeler-<user>/`;
139
+ this server looks in both. Editors do not always pass `XDG_RUNTIME_DIR` to the
140
+ servers they start (VS Code under WSL may not), and the copy is what lets the
141
+ two meet. With an older `serve`, set `XDG_RUNTIME_DIR` in this server's `env`
142
+ to the value it has in the terminal running `serve`.
97
143
 
98
144
  ## Tools
99
145
 
100
146
  ### `list_namespaces`
101
147
 
102
- List all 25 OPC UA companion spec namespaces with aliases, URIs, and dependencies.
148
+ List all 33 OPC UA companion spec namespaces with aliases, URIs, and dependencies.
103
149
 
104
150
  ```
105
151
  → list_namespaces()
@@ -169,6 +215,35 @@ Search for types across **all** companion specs by keyword.
169
215
  ]
170
216
  ```
171
217
 
218
+ ### `find_reusable_block`
219
+
220
+ Find reusable Interfaces and AddIns by capability — pass a member name or keyword
221
+ and get the standard blocks that already expose it. Prefer composing an existing
222
+ block over redefining its members by hand.
223
+
224
+ ```
225
+ → find_reusable_block({ query: "SerialNumber" })
226
+ ← [
227
+ {
228
+ "browseName": "di:IVendorNameplateType",
229
+ "alias": "di",
230
+ "kind": "interface",
231
+ "matchedMembers": ["di:SerialNumber"],
232
+ "members": ["di:Manufacturer", "di:Model", "di:SerialNumber", ...]
233
+ },
234
+ {
235
+ "browseName": "machinery:MachineIdentificationType",
236
+ "alias": "machinery",
237
+ "kind": "addin",
238
+ "matchedMembers": ["di:SerialNumber"],
239
+ "members": ["machinery:Location", "di:SerialNumber", ...]
240
+ }
241
+ ]
242
+ ```
243
+
244
+ `kind` tells you how to apply it: `interface` goes in `interfaces:`, `addin` in
245
+ `addIns:`.
246
+
172
247
  ### `find_engineering_unit`
173
248
 
174
249
  Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases.
@@ -184,9 +259,22 @@ Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching
184
259
  ← { "symbol": "bar", "matchType": "exact", "confidence": 1 }
185
260
  ```
186
261
 
262
+ ### `get_dsl_reference` ☁️
263
+
264
+ Fetch the YAML DSL grammar reference — the file header, top-level sections, type
265
+ and instance syntax, and a list of common mistakes. **No API key required.**
266
+
267
+ Served from the API rather than bundled into this package, so the reference an
268
+ agent reads always matches the validator that will judge its output.
269
+
270
+ ```
271
+ → get_dsl_reference()
272
+ ← { "version": "1", "reference": "# OPC UA Modeler YAML DSL ..." }
273
+ ```
274
+
187
275
  ### `opcua_model_validate` ☁️
188
276
 
189
- 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).
277
+ 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).
190
278
 
191
279
  ```
192
280
  → opcua_model_validate({ yaml: "namespaces:\n di:\n..." })
@@ -198,25 +286,54 @@ Validate an OPC UA YAML model for correctness. Returns diagnostics with severity
198
286
  }
199
287
  ```
200
288
 
289
+ **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.
290
+
291
+ ```
292
+ → opcua_model_validate({ model_path: "C:/models/cip/cip-example.model.yaml" })
293
+ ```
294
+
201
295
  ### `opcua_model_generate` ☁️
202
296
 
203
- Generate OPC UA NodeSet2.xml and Symbols.CSV from a validated YAML model. Returns base64-encoded artifacts. Requires an API key.
297
+ Generate OPC UA NodeSet2.xml and the symbols CSV from a validated YAML model. Requires an API key.
298
+
299
+ **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:
300
+
301
+ | Call | Meaning |
302
+ |---|---|
303
+ | `symbols_csv: "<previous CSV>"` | Regeneration: existing nodes keep their ids. Accepts the CSV text, or the base64 `symbols_csv` a previous call returned. |
304
+ | `mode: "new"` | First generation: there are no symbols yet. |
305
+ | `mode: "renumber"` | Allocate new ids on purpose. |
306
+ | a self-contained `.opcua.yaml` stream | It carries its own symbol table, which is replayed. |
307
+
308
+ A call with none of these is refused before reaching the backend with `SYMBOLS_DECISION_REQUIRED`, and the message says how to retry.
309
+
310
+ **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.
204
311
 
205
312
  ```
206
- → opcua_model_generate({ yaml: "namespaces:\n di:\n...", include_docs: false })
313
+ → opcua_model_generate({ model_path: "models/pump.model.yaml" })
207
314
  ← {
208
315
  "valid": true,
209
- "artifacts": {
210
- "nodeset2_xml": "PD94bWwg...",
211
- "symbols_csv": "bmFtZSxu..."
212
- },
213
- "diagnostics": []
316
+ "mode": "update",
317
+ "symbols_source": "paired-file",
318
+ "symbols": { "reused": 41, "new": 1, "dropped": 0, "renumbered": 0, "match": 1,
319
+ "new_names": ["Pump_Temperature"], "dropped_names": [] },
320
+ "files": [
321
+ { "role": "nodeset", "path": ".../pump.model.Nodeset2.xml", "bytes": 54210, "status": "written" },
322
+ { "role": "symbols", "path": ".../pump.model.symbols.csv", "bytes": 1312, "status": "written" }
323
+ ],
324
+ "diagnostics": [],
325
+ "hints": [{ "code": "SYMBOLS_UPDATED", "level": "info", "message": ".../pump.model.symbols.csv updated: 1 new id(s) (Pump_Temperature)." }],
326
+ "next_steps": ["Commit pump.model.Nodeset2.xml, pump.model.symbols.csv with the model."]
214
327
  }
215
328
  ```
216
329
 
330
+ **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`.
331
+
332
+ 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`.
333
+
217
334
  ### `opcua_model_reverse` ☁️
218
335
 
219
- Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key.
336
+ 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.
220
337
 
221
338
  ```
222
339
  → opcua_model_reverse({ xml: "<?xml version=..." })
@@ -254,33 +371,40 @@ Generate an OPC UA YAML model from a natural language description using AI. The
254
371
 
255
372
  ## Coverage
256
373
 
257
- ### Companion Specifications (25)
374
+ ### Companion Specifications (33)
258
375
 
259
376
  | Alias | Specification | Types |
260
377
  |-------|--------------|-------|
261
378
  | `padim` | OPC UA for PA-DIM | 101 |
262
379
  | `ijtBase` | OPC UA for IJT Base | 65 |
263
380
  | `machineTool` | OPC UA for Machine Tools | 63 |
381
+ | `scales` | OPC UA for Scales | 58 |
382
+ | `lads` | OPC UA for Laboratory Devices | 53 |
264
383
  | `di` | OPC UA for Devices | 44 |
265
384
  | `glass` | OPC UA for Glass Manufacturing | 36 |
266
385
  | `machineVision` | OPC UA for Machine Vision | 36 |
267
386
  | `adi` | OPC UA for Analyzer Devices | 35 |
268
387
  | `commercialKitchenEquipment` | OPC UA for Commercial Kitchen Equipment | 35 |
388
+ | `i4aas` | OPC UA for I4AAS | 32 |
389
+ | `fxAc` | OPC UA FX Automation Component | 28 |
269
390
  | `robotics` | OPC UA for Robotics | 25 |
391
+ | `fxCm` | OPC UA FX Connection Manager | 24 |
270
392
  | `ia` | OPC UA for Industrial Automation | 20 |
271
393
  | `amb` | OPC UA for AMB | 18 |
272
394
  | `autoId` | OPC UA for AutoID | 18 |
395
+ | `iolink` | OPC UA for IO-Link | 16 |
273
396
  | `metalForming` | OPC UA for Metal Forming | 16 |
274
- | `machinery` | OPC UA for Machinery | 15 |
275
- | `gds` | OPC UA GDS | 14 |
276
- | `woodworking` | OPC UA for Woodworking | 13 |
277
- | `cnc` | OPC UA for CNC Systems | 12 |
278
- | | *…and 5 more* | |
279
- | **Total** | **22 namespaces** | **589 types** |
397
+ | | *…and 13 more* | |
398
+ | **Total** | **32 namespaces with types** | **817 types** |
399
+
400
+ The registry holds **33** specs; `irdi` is a dictionary-entry namespace and
401
+ defines no ObjectTypes or VariableTypes. These figures come from
402
+ `catalog/catalog.json` and are asserted against it by
403
+ `test/catalog-coverage.test.ts`, so they cannot drift silently.
280
404
 
281
405
  ### Engineering Units
282
406
 
283
- 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.
407
+ 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.
284
408
 
285
409
  ## How It Works
286
410
 
@@ -293,14 +417,15 @@ The server ships with a pre-generated `catalog.json` containing all type informa
293
417
  │ LOCAL TOOLS (offline, free) │
294
418
  │ ┌────────────────────────────────────────┐ │
295
419
  │ │ catalog.json (1.7 MB) │ │
296
- │ │ • 25 companion spec registries │ │
297
- │ │ • 589 type summaries + details │ │
420
+ │ │ • 33 companion spec registries │ │
421
+ │ │ • 817 type summaries + details │ │
298
422
  │ │ • 1,533 engineering units │ │
299
423
  │ └────────────────────────────────────────┘ │
300
- │ 6 tools → query the catalog │
424
+ │ 7 tools → query the catalog │
301
425
  │ │
302
426
  │ CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
303
- │ 4 tools → validate / generate / reverse / create│
427
+ │ 5 tools → reference / validate / generate / │
428
+ │ reverse / create │
304
429
  │ │
305
430
  │ stdio transport (JSON-RPC) │
306
431
  └──────────────────────────────────────────────────┘
@@ -319,6 +444,7 @@ The server ships with a pre-generated `catalog.json` containing all type informa
319
444
 
320
445
  ## Related
321
446
 
447
+ - [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
322
448
  - [OPC UA Modeler — web app](https://opcua-modeler.sterfive.io) — Create, validate, and generate OPC UA information models in the browser
323
449
  - [Product page](https://www.sterfive.com/product/opcua-modeler) — OPC UA Modeler overview, features, and licensing
324
450
  - [Documentation](https://opcua-modeler.doc.sterfive.com) — Guides, YAML DSL reference, and how-tos
package/SKILL.md CHANGED
@@ -26,7 +26,7 @@ answers come from the official published NodeSet2.xml files.
26
26
 
27
27
  ## Workflow
28
28
 
29
- 1. **`list_namespaces`** — see the ~28 available companion specs with
29
+ 1. **`list_namespaces`** — see the 28 available companion specs with
30
30
  aliases, URIs, and dependency lists. Pick the spec(s) matching the domain
31
31
  (e.g. `scales` for weighing, `lads` for lab devices).
32
32
  2. **`search_types` / `list_types`** — find candidate types by keyword
@@ -54,6 +54,21 @@ answers come from the official published NodeSet2.xml files.
54
54
  - Types missing from a spec are a signal to compose (add components) rather
55
55
  than to invent look-alike type names.
56
56
 
57
+ ## Keeping NodeIds stable
58
+
59
+ `opcua_model_generate` returns a symbols CSV recording every NodeId. Pass it
60
+ back as `symbols_csv` on every later generate of the same model, or the ids
61
+ change and every client bound to them breaks. Save it as
62
+ `<name>.model.symbols.csv` next to the model and commit it. On a first
63
+ generation say `mode: "new"`; to renumber on purpose, `mode: "renumber"`. A
64
+ call that says none of this is refused with `SYMBOLS_DECISION_REQUIRED`.
65
+
66
+ When the server runs locally, prefer `model_path` over `yaml`: the server then
67
+ reads the paired CSV itself and writes the outputs beside the model, so
68
+ nothing has to be carried between calls. Likewise `model_path` for
69
+ `opcua_model_validate`, whose imports then resolve from the model's folder and
70
+ its `deps/`, and `xml_path` for `opcua_model_reverse`. Follow the `hints` and `next_steps` in each result.
71
+
57
72
  ## Model generation and validation (API key)
58
73
 
59
74
  The discovery tools above are free and offline. Compiling, validating,