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 +149 -23
- package/SKILL.md +16 -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 +13 -1
- package/dist/cloud.js +32 -11
- 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/http-cli.d.ts +11 -0
- package/dist/http-cli.js +13 -0
- package/dist/http-cli.js.map +1 -0
- package/dist/http-server.d.ts +36 -0
- package/dist/http-server.js +150 -0
- package/dist/http-server.js.map +1 -0
- package/dist/http.js +3 -3
- package/dist/http.js.map +1 -1
- package/dist/index.js +12 -5
- package/dist/index.js.map +1 -1
- package/dist/local.d.ts +11 -1
- package/dist/local.js +60 -6
- package/dist/local.js.map +1 -1
- package/dist/server.d.ts +11 -1
- package/dist/server.js +72 -44
- package/dist/server.js.map +1 -1
- package/dist/validate-tool.d.ts +33 -0
- package/dist/validate-tool.js +74 -0
- package/dist/validate-tool.js.map +1 -0
- package/package.json +7 -2
- package/server.json +14 -2
package/README.md
CHANGED
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
[](https://www.npmjs.com/package/node-opcua-modeler-mcp-server)
|
|
6
6
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
7
7
|
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](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** —
|
|
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
|
|
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
|
|
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
|
|
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({
|
|
313
|
+
→ opcua_model_generate({ model_path: "models/pump.model.yaml" })
|
|
207
314
|
← {
|
|
208
315
|
"valid": true,
|
|
209
|
-
"
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
"
|
|
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 (
|
|
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
|
-
|
|
|
275
|
-
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
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
|
|
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
|
-
│ │ •
|
|
297
|
-
│ │ •
|
|
420
|
+
│ │ • 33 companion spec registries │ │
|
|
421
|
+
│ │ • 817 type summaries + details │ │
|
|
298
422
|
│ │ • 1,533 engineering units │ │
|
|
299
423
|
│ └────────────────────────────────────────┘ │
|
|
300
|
-
│
|
|
424
|
+
│ 7 tools → query the catalog │
|
|
301
425
|
│ │
|
|
302
426
|
│ CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
|
|
303
|
-
│
|
|
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
|
|
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,
|