node-opcua-modeler-mcp-server 1.0.1 → 1.2.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sterfive SAS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
5
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  Built on [node-opcua](https://github.com/node-opcua/node-opcua), the most widely used OPC UA stack for Node.js.
10
10
 
@@ -29,12 +29,17 @@ Add to your `claude_desktop_config.json`:
29
29
  "mcpServers": {
30
30
  "opcua-modeler": {
31
31
  "command": "npx",
32
- "args": ["-y", "node-opcua-modeler-mcp-server"]
32
+ "args": ["-y", "node-opcua-modeler-mcp-server"],
33
+ "env": {
34
+ "OPCUA_MODELER_API_KEY": "stfv_your_api_key_here"
35
+ }
33
36
  }
34
37
  }
35
38
  }
36
39
  ```
37
40
 
41
+ > **Note:** The API key is optional for discovery tools (offline) and `opcua_model_validate` (5 free calls/day). It is required for `opcua_model_generate`, `opcua_model_reverse`, and `opcua_model_create`. Get a free key at [opcua-modeler.sterfive.com](https://opcua-modeler.sterfive.com/settings/api-keys).
42
+
38
43
  ### With any MCP client
39
44
 
40
45
  ```bash
@@ -132,6 +137,74 @@ Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching
132
137
  ← { "symbol": "bar", "matchType": "exact", "confidence": 1 }
133
138
  ```
134
139
 
140
+ ### `opcua_model_validate` ☁️
141
+
142
+ 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).
143
+
144
+ ```
145
+ → opcua_model_validate({ yaml: "namespaces:\n di:\n..." })
146
+ ← {
147
+ "valid": true,
148
+ "diagnostics": [
149
+ { "severity": "warning", "code": "W001", "message": "...", "line": 42 }
150
+ ]
151
+ }
152
+ ```
153
+
154
+ ### `opcua_model_generate` ☁️
155
+
156
+ Generate OPC UA NodeSet2.xml and Symbols.CSV from a validated YAML model. Returns base64-encoded artifacts. Requires an API key.
157
+
158
+ ```
159
+ → opcua_model_generate({ yaml: "namespaces:\n di:\n...", include_docs: false })
160
+ ← {
161
+ "valid": true,
162
+ "artifacts": {
163
+ "nodeset2_xml": "PD94bWwg...",
164
+ "symbols_csv": "bmFtZSxu..."
165
+ },
166
+ "diagnostics": []
167
+ }
168
+ ```
169
+
170
+ ### `opcua_model_reverse` ☁️
171
+
172
+ Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key.
173
+
174
+ ```
175
+ → opcua_model_reverse({ xml: "<?xml version=..." })
176
+ ← {
177
+ "yaml": "namespaces:\n di:\n...",
178
+ "diagnostics": []
179
+ }
180
+ ```
181
+
182
+ ### `opcua_model_create` ☁️
183
+
184
+ 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.
185
+
186
+ ```
187
+ → opcua_model_create({ prompt: "A robotic welding cell with two robot arms, each having 6 axes, temperature monitoring on each motor" })
188
+ ← {
189
+ "success": true,
190
+ "yaml": "namespaces:\n di:\n robotics:\n...",
191
+ "attempts": 2,
192
+ "diagnostics": [],
193
+ "model": "gemini-2.5-pro",
194
+ "tokens": { "input": 4200, "output": 1800 }
195
+ }
196
+
197
+ → opcua_model_create({ prompt: "A CNC lathe with spindle speed and temperature", forceSpecs: ["di", "cnc"] })
198
+ ← {
199
+ "success": true,
200
+ "yaml": "namespaces:\n di:\n cnc:\n...",
201
+ "attempts": 1,
202
+ "diagnostics": [],
203
+ "model": "gemini-2.5-pro",
204
+ "tokens": { "input": 3500, "output": 1200 }
205
+ }
206
+ ```
207
+
135
208
  ## Coverage
136
209
 
137
210
  ### Companion Specifications (25)
@@ -167,19 +240,23 @@ Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching
167
240
  The server ships with a pre-generated `catalog.json` containing all type information extracted from OPC Foundation's official NodeSet2.xml files via [node-opcua](https://github.com/node-opcua/node-opcua). All queries are answered from this static catalog — **no network required, no API key needed**.
168
241
 
169
242
  ```
170
- ┌─────────────────────────────────────────┐
171
- │ node-opcua-modeler-mcp-server │
172
- │ │
173
- │ ┌─────────────────────────────────┐ │
174
- │ │ catalog.json (1.7 MB) │ │
175
- │ │ • 25 companion spec registries │ │
176
- │ │ • 589 type summaries + details │ │
177
- │ │ • 1,533 engineering units │ │
178
- │ └─────────────────────────────────┘ │
179
- │ │
180
- │ 6 MCP tools → query the catalog │
181
- │ stdio transport (JSON-RPC) │
182
- └─────────────────────────────────────────┘
243
+ ┌──────────────────────────────────────────────────┐
244
+ │ node-opcua-modeler-mcp-server │
245
+ │ │
246
+ │ LOCAL TOOLS (offline, free) │
247
+ │ ┌────────────────────────────────────────┐ │
248
+ │ │ catalog.json (1.7 MB) │ │
249
+ │ │ • 25 companion spec registries │ │
250
+ │ │ • 589 type summaries + details │ │
251
+ │ │ • 1,533 engineering units │ │
252
+ │ └────────────────────────────────────────┘ │
253
+ │ 6 tools → query the catalog │
254
+ │ │
255
+ │ CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
256
+ │ 4 tools → validate / generate / reverse / create│
257
+ │ │
258
+ │ stdio transport (JSON-RPC) │
259
+ └──────────────────────────────────────────────────┘
183
260
  ```
184
261
 
185
262
  ## Use Cases
package/SKILL.md ADDED
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: opcua-modeling
3
+ description: >
4
+ Design OPC UA information models grounded in real companion specifications
5
+ (DI, Machinery, Robotics, LADS, Scales, …) using the OPC UA Modeler MCP
6
+ server — look up types, their members and valid optionals, resolve
7
+ namespace dependencies, and find engineering units before writing any
8
+ model, instead of guessing from training data.
9
+ ---
10
+
11
+ # OPC UA Modeling with the OPC UA Modeler MCP Server
12
+
13
+ ## When to use this skill
14
+
15
+ Use it whenever a task involves OPC UA information modeling:
16
+
17
+ - designing a NodeSet2 / information model for a machine or device
18
+ - choosing which **companion specification** types to derive from
19
+ - checking what components, properties, methods, or **optionals** a type has
20
+ - validating namespace dependencies (`di`, `machinery`, `robotics`, …)
21
+ - finding the correct UNECE engineering-unit symbol (`°C`, `l/min`, `N·m`)
22
+
23
+ Never invent OPC UA type names, browse paths, or unit symbols from memory —
24
+ companion specs are too niche for that. Query the catalog instead: the
25
+ answers come from the official published NodeSet2.xml files.
26
+
27
+ ## Workflow
28
+
29
+ 1. **`list_namespaces`** — see the ~28 available companion specs with
30
+ aliases, URIs, and dependency lists. Pick the spec(s) matching the domain
31
+ (e.g. `scales` for weighing, `lads` for lab devices).
32
+ 2. **`search_types` / `list_types`** — find candidate types by keyword
33
+ (e.g. "weighing") or enumerate everything a spec defines.
34
+ 3. **`get_type_details`** — get a type's full structure: components,
35
+ properties, methods, interfaces, `subtypeOf` chain, and
36
+ **`availableOptionals`** — the exhaustive list of valid optional browse
37
+ paths (including nested dotted paths like
38
+ `di:Identification.machinery:InitialOperationDate`).
39
+ 4. **`resolve_dependencies`** — given the spec aliases you use, get the
40
+ complete transitively-resolved, load-ordered namespace list to declare.
41
+ 5. **`find_engineering_unit`** — map natural language ("litre per minute")
42
+ to the valid UNECE symbol before writing any EUInformation.
43
+
44
+ ## Rules of thumb
45
+
46
+ - **Anchor on companion-spec base types.** Subclass the closest existing
47
+ type (e.g. `scales:ScaleDeviceType`, not `ua:BaseObjectType`) so clients
48
+ recognize the model.
49
+ - **`optionals:` entries MUST come from `availableOptionals`.** Never guess
50
+ optional paths and never re-declare inherited components — inherited
51
+ members come for free from the supertype.
52
+ - **Declare only the namespaces you use**, in the dependency order returned
53
+ by `resolve_dependencies`.
54
+ - Types missing from a spec are a signal to compose (add components) rather
55
+ than to invent look-alike type names.
56
+
57
+ ## Model generation and validation (API key)
58
+
59
+ The discovery tools above are free and offline. Compiling, validating,
60
+ generating, and reverse-engineering full models
61
+ (`opcua_model_validate`, `opcua_model_generate`, `opcua_model_reverse`,
62
+ `opcua_model_create`) are backed by the Sterfive cloud service — get an API
63
+ key at <https://opcua-modeler.sterfive.com> and set `OPCUA_MODELER_API_KEY`.