{ "markdown": "# node-opcua-modeler-mcp-server\n\n[![npm version](https://img.shields.io/npm/v/node-opcua-modeler-mcp-server.svg)](https://www.npmjs.com/package/node-opcua-modeler-mcp-server)\n[![npm downloads/month](https://img.shields.io/npm/dm/node-opcua-modeler-mcp-server.svg)](https://www.npmjs.com/package/node-opcua-modeler-mcp-server)\n[![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)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)\n\nAn [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.\n\nBuilt on [node-opcua](https://github.com/node-opcua/node-opcua), the most widely used OPC UA stack for Node.js.\n\n## Why?\n\nWhen an AI agent needs to build an OPC UA information model, it must know:\n- What **companion spec types** exist (DI, Machinery, Robotics, Machine Tools…)\n- What **components, properties, and methods** each type has\n- What **namespace dependencies** are required\n- What **engineering unit symbols** are valid (UNECE Rec. 20)\n\nThis MCP server answers all of those questions — **offline, for free, in milliseconds**.\n\n## Quick Start\n\n### With Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"opcua-modeler\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"node-opcua-modeler-mcp-server\"],\n \"env\": {\n \"OPCUA_MODELER_API_KEY\": \"stfv_your_api_key_here\"\n }\n }\n }\n}\n```\n\n> **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.\n\n### With any MCP client\n\n```bash\nnpx node-opcua-modeler-mcp-server\n```\n\nThe server communicates over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io).\n\n### Using a local backend instead of the hosted API\n\nIf you run the OPC UA Modeler CLI on the same machine, the model tools can be\nserved from it instead of the hosted API — your YAML never leaves the host.\n\nStart the server (requires a licence that includes the `serve` entitlement):\n\n```bash\nopcua-modeler serve\n```\n\nThen set one environment variable in your MCP client config:\n\n```json\n{\n \"mcpServers\": {\n \"opcua-modeler\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"node-opcua-modeler-mcp-server\"],\n \"env\": {\n \"OPCUA_MODELER_BACKEND\": \"local\"\n }\n }\n }\n}\n```\n\nNo API key is needed in this mode — the client discovers the local endpoint and\nits credentials automatically.\n\n| Variable | Values | Purpose |\n|----------|--------|---------|\n| `OPCUA_MODELER_BACKEND` | `cloud` (default), `local` | Which backend serves the model tools |\n| `OPCUA_MODELER_API_KEY` | `stfv_…` | API key, `cloud` backend only |\n| `OPCUA_MODELER_API_URL` | URL | Override the hosted API base URL |\n\n**Notes**\n\n- The two backends are never mixed, and there is no fallback between them. If\n `local` is selected and no server is running, the call fails with instructions\n rather than silently sending your model to the hosted API.\n- The seven discovery tools are local to this package and work offline on either\n setting.\n- `opcua_model_create` (AI generation) is available on the `cloud` backend only.\n\n## Tools\n\n### `list_namespaces`\n\nList all 25 OPC UA companion spec namespaces with aliases, URIs, and dependencies.\n\n```\n→ list_namespaces()\n← [\n { \"alias\": \"di\", \"name\": \"OPC UA for Devices\", \"uri\": \"http://opcfoundation.org/UA/DI/\", \"dependencies\": [] },\n { \"alias\": \"robotics\", \"name\": \"OPC UA for Robotics\", \"uri\": \"http://opcfoundation.org/UA/Robotics/\", \"dependencies\": [\"di\", \"ia\"] },\n ...\n ]\n```\n\n### `resolve_dependencies`\n\nResolve the full dependency chain for companion spec aliases. Returns a topologically sorted list for the YAML `namespaces:` block.\n\n```\n→ resolve_dependencies({ aliases: [\"machineTool\"] })\n← [\"di\", \"ia\", \"machinery\", \"isa95JobControl\", \"machineryJobs\", \"machineTool\"]\n```\n\n### `list_types`\n\nList all ObjectTypes and VariableTypes defined in a companion spec namespace.\n\n```\n→ list_types({ alias: \"robotics\" })\n← [\n { \"browseName\": \"MotionDeviceType\", \"kind\": \"ObjectType\", \"subtypeOf\": \"di:ComponentType\", ... },\n { \"browseName\": \"AxisType\", \"kind\": \"ObjectType\", \"subtypeOf\": \"di:ComponentType\", ... },\n ...\n ] // 25 types\n```\n\n### `get_type_details`\n\nGet the full structure of a type — components, properties, methods, interfaces, including inherited members.\n\n```\n→ get_type_details({ alias: \"robotics\", browseName: \"MotionDeviceType\" })\n← {\n \"browseName\": \"MotionDeviceType\",\n \"kind\": \"ObjectType\",\n \"subtypeOf\": \"di:ComponentType\",\n \"interfaces\": [\"di:IVendorNameplateType\", \"di:ITagNameplateType\"],\n \"components\": [\n { \"browseName\": \"robotics:Axes\", \"nodeClass\": \"Object\", \"typeDefinition\": \"FolderType\", \"modellingRule\": \"Mandatory\" },\n { \"browseName\": \"robotics:PowerTrains\", \"nodeClass\": \"Object\", \"typeDefinition\": \"FolderType\", \"modellingRule\": \"Mandatory\" },\n ...\n ],\n \"properties\": [\n { \"browseName\": \"di:Manufacturer\", \"dataType\": \"LocalizedText\", \"modellingRule\": \"Mandatory\" },\n { \"browseName\": \"robotics:MotionDeviceCategory\", \"dataType\": \"MotionDeviceCategoryEnumeration\", \"modellingRule\": \"Mandatory\" },\n ...\n ]\n }\n```\n\n### `search_types`\n\nSearch for types across **all** companion specs by keyword.\n\n```\n→ search_types({ query: \"temperature\" })\n← [\n { \"alias\": \"glass\", \"browseName\": \"MotorTemperatureTooHighEventType\", ... },\n { \"alias\": \"padim\", \"browseName\": \"TemperatureMeasurementVariableType\", ... },\n { \"alias\": \"amb\", \"browseName\": \"OverTemperatureConditionClassType\", ... }\n ]\n```\n\n### `find_engineering_unit`\n\nFind the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases.\n\n```\n→ find_engineering_unit({ query: \"celsius\" })\n← { \"symbol\": \"°C\", \"matchType\": \"alias\", \"confidence\": 1 }\n\n→ find_engineering_unit({ query: \"revolutions per minute\" })\n← { \"symbol\": \"r/min\", \"matchType\": \"alias\", \"confidence\": 1 }\n\n→ find_engineering_unit({ query: \"bar\" })\n← { \"symbol\": \"bar\", \"matchType\": \"exact\", \"confidence\": 1 }\n```\n\n### `opcua_model_validate` ☁️\n\nValidate 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).\n\n```\n→ opcua_model_validate({ yaml: \"namespaces:\\n di:\\n...\" })\n← {\n \"valid\": true,\n \"diagnostics\": [\n { \"severity\": \"warning\", \"code\": \"W001\", \"message\": \"...\", \"line\": 42 }\n ]\n }\n```\n\n### `opcua_model_generate` ☁️\n\nGenerate OPC UA NodeSet2.xml and Symbols.CSV from a validated YAML model. Returns base64-encoded artifacts. Requires an API key.\n\n```\n→ opcua_model_generate({ yaml: \"namespaces:\\n di:\\n...\", include_docs: false })\n← {\n \"valid\": true,\n \"artifacts\": {\n \"nodeset2_xml\": \"PD94bWwg...\",\n \"symbols_csv\": \"bmFtZSxu...\"\n },\n \"diagnostics\": []\n }\n```\n\n### `opcua_model_reverse` ☁️\n\nReverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key.\n\n```\n→ opcua_model_reverse({ xml: \"