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

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
@@ -6,7 +6,7 @@
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
8
 
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.
9
+ 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
10
 
11
11
  Built on [node-opcua](https://github.com/node-opcua/node-opcua), the most widely used OPC UA stack for Node.js.
12
12
 
@@ -99,7 +99,7 @@ its credentials automatically.
99
99
 
100
100
  ### `list_namespaces`
101
101
 
102
- List all 25 OPC UA companion spec namespaces with aliases, URIs, and dependencies.
102
+ List all 33 OPC UA companion spec namespaces with aliases, URIs, and dependencies.
103
103
 
104
104
  ```
105
105
  → list_namespaces()
@@ -169,6 +169,35 @@ Search for types across **all** companion specs by keyword.
169
169
  ]
170
170
  ```
171
171
 
172
+ ### `find_reusable_block`
173
+
174
+ Find reusable Interfaces and AddIns by capability — pass a member name or keyword
175
+ and get the standard blocks that already expose it. Prefer composing an existing
176
+ block over redefining its members by hand.
177
+
178
+ ```
179
+ → find_reusable_block({ query: "SerialNumber" })
180
+ ← [
181
+ {
182
+ "browseName": "di:IVendorNameplateType",
183
+ "alias": "di",
184
+ "kind": "interface",
185
+ "matchedMembers": ["di:SerialNumber"],
186
+ "members": ["di:Manufacturer", "di:Model", "di:SerialNumber", ...]
187
+ },
188
+ {
189
+ "browseName": "machinery:MachineIdentificationType",
190
+ "alias": "machinery",
191
+ "kind": "addin",
192
+ "matchedMembers": ["di:SerialNumber"],
193
+ "members": ["machinery:Location", "di:SerialNumber", ...]
194
+ }
195
+ ]
196
+ ```
197
+
198
+ `kind` tells you how to apply it: `interface` goes in `interfaces:`, `addin` in
199
+ `addIns:`.
200
+
172
201
  ### `find_engineering_unit`
173
202
 
174
203
  Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases.
@@ -184,9 +213,22 @@ Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching
184
213
  ← { "symbol": "bar", "matchType": "exact", "confidence": 1 }
185
214
  ```
186
215
 
216
+ ### `get_dsl_reference` ☁️
217
+
218
+ Fetch the YAML DSL grammar reference — the file header, top-level sections, type
219
+ and instance syntax, and a list of common mistakes. **No API key required.**
220
+
221
+ Served from the API rather than bundled into this package, so the reference an
222
+ agent reads always matches the validator that will judge its output.
223
+
224
+ ```
225
+ → get_dsl_reference()
226
+ ← { "version": "1", "reference": "# OPC UA Modeler YAML DSL ..." }
227
+ ```
228
+
187
229
  ### `opcua_model_validate` ☁️
188
230
 
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).
231
+ 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
232
 
191
233
  ```
192
234
  → opcua_model_validate({ yaml: "namespaces:\n di:\n..." })
@@ -200,23 +242,46 @@ Validate an OPC UA YAML model for correctness. Returns diagnostics with severity
200
242
 
201
243
  ### `opcua_model_generate` ☁️
202
244
 
203
- Generate OPC UA NodeSet2.xml and Symbols.CSV from a validated YAML model. Returns base64-encoded artifacts. Requires an API key.
245
+ Generate OPC UA NodeSet2.xml and the symbols CSV from a validated YAML model. Requires an API key.
246
+
247
+ **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:
248
+
249
+ | Call | Meaning |
250
+ |---|---|
251
+ | `symbols_csv: "<previous CSV>"` | Regeneration: existing nodes keep their ids. Accepts the CSV text, or the base64 `symbols_csv` a previous call returned. |
252
+ | `mode: "new"` | First generation: there are no symbols yet. |
253
+ | `mode: "renumber"` | Allocate new ids on purpose. |
254
+ | a self-contained `.opcua.yaml` stream | It carries its own symbol table, which is replayed. |
255
+
256
+ A call with none of these is refused before reaching the backend with `SYMBOLS_DECISION_REQUIRED`, and the message says how to retry.
257
+
258
+ **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
259
 
205
260
  ```
206
- → opcua_model_generate({ yaml: "namespaces:\n di:\n...", include_docs: false })
261
+ → opcua_model_generate({ model_path: "models/pump.model.yaml" })
207
262
  ← {
208
263
  "valid": true,
209
- "artifacts": {
210
- "nodeset2_xml": "PD94bWwg...",
211
- "symbols_csv": "bmFtZSxu..."
212
- },
213
- "diagnostics": []
264
+ "mode": "update",
265
+ "symbols_source": "paired-file",
266
+ "symbols": { "reused": 41, "new": 1, "dropped": 0, "renumbered": 0, "match": 1,
267
+ "new_names": ["Pump_Temperature"], "dropped_names": [] },
268
+ "files": [
269
+ { "role": "nodeset", "path": ".../pump.model.Nodeset2.xml", "bytes": 54210, "status": "written" },
270
+ { "role": "symbols", "path": ".../pump.model.symbols.csv", "bytes": 1312, "status": "written" }
271
+ ],
272
+ "diagnostics": [],
273
+ "hints": [{ "code": "SYMBOLS_UPDATED", "level": "info", "message": ".../pump.model.symbols.csv updated: 1 new id(s) (Pump_Temperature)." }],
274
+ "next_steps": ["Commit pump.model.Nodeset2.xml, pump.model.symbols.csv with the model."]
214
275
  }
215
276
  ```
216
277
 
278
+ **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`.
279
+
280
+ 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`.
281
+
217
282
  ### `opcua_model_reverse` ☁️
218
283
 
219
- Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key.
284
+ 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
285
 
221
286
  ```
222
287
  → opcua_model_reverse({ xml: "<?xml version=..." })
@@ -254,33 +319,40 @@ Generate an OPC UA YAML model from a natural language description using AI. The
254
319
 
255
320
  ## Coverage
256
321
 
257
- ### Companion Specifications (25)
322
+ ### Companion Specifications (33)
258
323
 
259
324
  | Alias | Specification | Types |
260
325
  |-------|--------------|-------|
261
326
  | `padim` | OPC UA for PA-DIM | 101 |
262
327
  | `ijtBase` | OPC UA for IJT Base | 65 |
263
328
  | `machineTool` | OPC UA for Machine Tools | 63 |
329
+ | `scales` | OPC UA for Scales | 58 |
330
+ | `lads` | OPC UA for Laboratory Devices | 53 |
264
331
  | `di` | OPC UA for Devices | 44 |
265
332
  | `glass` | OPC UA for Glass Manufacturing | 36 |
266
333
  | `machineVision` | OPC UA for Machine Vision | 36 |
267
334
  | `adi` | OPC UA for Analyzer Devices | 35 |
268
335
  | `commercialKitchenEquipment` | OPC UA for Commercial Kitchen Equipment | 35 |
336
+ | `i4aas` | OPC UA for I4AAS | 32 |
337
+ | `fxAc` | OPC UA FX Automation Component | 28 |
269
338
  | `robotics` | OPC UA for Robotics | 25 |
339
+ | `fxCm` | OPC UA FX Connection Manager | 24 |
270
340
  | `ia` | OPC UA for Industrial Automation | 20 |
271
341
  | `amb` | OPC UA for AMB | 18 |
272
342
  | `autoId` | OPC UA for AutoID | 18 |
343
+ | `iolink` | OPC UA for IO-Link | 16 |
273
344
  | `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** |
345
+ | | *…and 13 more* | |
346
+ | **Total** | **32 namespaces with types** | **817 types** |
347
+
348
+ The registry holds **33** specs; `irdi` is a dictionary-entry namespace and
349
+ defines no ObjectTypes or VariableTypes. These figures come from
350
+ `catalog/catalog.json` and are asserted against it by
351
+ `test/catalog-coverage.test.ts`, so they cannot drift silently.
280
352
 
281
353
  ### Engineering Units
282
354
 
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.
355
+ 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
356
 
285
357
  ## How It Works
286
358
 
@@ -293,14 +365,15 @@ The server ships with a pre-generated `catalog.json` containing all type informa
293
365
  │ LOCAL TOOLS (offline, free) │
294
366
  │ ┌────────────────────────────────────────┐ │
295
367
  │ │ catalog.json (1.7 MB) │ │
296
- │ │ • 25 companion spec registries │ │
297
- │ │ • 589 type summaries + details │ │
368
+ │ │ • 33 companion spec registries │ │
369
+ │ │ • 817 type summaries + details │ │
298
370
  │ │ • 1,533 engineering units │ │
299
371
  │ └────────────────────────────────────────┘ │
300
- │ 6 tools → query the catalog │
372
+ │ 7 tools → query the catalog │
301
373
  │ │
302
374
  │ CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
303
- │ 4 tools → validate / generate / reverse / create│
375
+ │ 5 tools → reference / validate / generate / │
376
+ │ reverse / create │
304
377
  │ │
305
378
  │ stdio transport (JSON-RPC) │
306
379
  └──────────────────────────────────────────────────┘
@@ -319,6 +392,7 @@ The server ships with a pre-generated `catalog.json` containing all type informa
319
392
 
320
393
  ## Related
321
394
 
395
+ - [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
396
  - [OPC UA Modeler — web app](https://opcua-modeler.sterfive.io) — Create, validate, and generate OPC UA information models in the browser
323
397
  - [Product page](https://www.sterfive.com/product/opcua-modeler) — OPC UA Modeler overview, features, and licensing
324
398
  - [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,20 @@ 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 `xml_path` for
69
+ `opcua_model_reverse`. Follow the `hints` and `next_steps` in each result.
70
+
57
71
  ## Model generation and validation (API key)
58
72
 
59
73
  The discovery tools above are free and offline. Compiling, validating,