node-opcua-modeler-mcp-server 1.6.0 → 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 +97 -23
- package/SKILL.md +15 -1
- package/catalog/catalog.json +10254 -527
- package/dist/catalog.d.ts +4 -0
- package/dist/catalog.js.map +1 -1
- package/dist/cloud.d.ts +2 -1
- package/dist/cloud.js +26 -7
- package/dist/cloud.js.map +1 -1
- package/dist/generate-tool.d.ts +148 -0
- package/dist/generate-tool.js +236 -0
- package/dist/generate-tool.js.map +1 -0
- package/dist/generate.d.ts +134 -0
- package/dist/generate.js +289 -0
- package/dist/generate.js.map +1 -0
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/local.d.ts +1 -1
- package/dist/local.js +2 -1
- package/dist/local.js.map +1 -1
- package/dist/server.d.ts +11 -1
- package/dist/server.js +96 -29
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
7
7
|
[](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** —
|
|
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
|
|
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
|
|
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
|
|
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({
|
|
261
|
+
→ opcua_model_generate({ model_path: "models/pump.model.yaml" })
|
|
207
262
|
← {
|
|
208
263
|
"valid": true,
|
|
209
|
-
"
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
"
|
|
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 (
|
|
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
|
-
|
|
|
275
|
-
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
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
|
|
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
|
-
│ │ •
|
|
297
|
-
│ │ •
|
|
368
|
+
│ │ • 33 companion spec registries │ │
|
|
369
|
+
│ │ • 817 type summaries + details │ │
|
|
298
370
|
│ │ • 1,533 engineering units │ │
|
|
299
371
|
│ └────────────────────────────────────────┘ │
|
|
300
|
-
│
|
|
372
|
+
│ 7 tools → query the catalog │
|
|
301
373
|
│ │
|
|
302
374
|
│ CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
|
|
303
|
-
│
|
|
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
|
|
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,
|