@etm-professional-control/winccoa-mcp-server 1.3.1 → 1.4.0

package/.env.example

@@ -83,10 +83,17 @@ WINCCOA_FIELD=default
 #   - Datapoints: datapoints/dp_basic, datapoints/dp_create, datapoints/dp_set, datapoints/dp_types, datapoints/dp_type_create
 #   - Icons: icons/icon (for creating custom SVG icons for widget headers/footers)
 #   - OPC UA: opcua/opcua_connection, opcua/opcua_address
+#   - MQTT: mqtt/mqtt_connection
 #   - Common Config: common/common_query, common/common_set, common/common_delete
 #   - Alarms: alarms/alarm_set, alarms/alarm_delete
 #   - Archive: archive/archive_set, archive/archive_delete, archive/archive_query
 #   - Dashboards: dashboards/dashboard, dashboards/widget
 #   - PV Range: pv_range/pv_range_query, pv_range/pv_range_set, pv_range/pv_range_delete
 #   - Manager: manager/manager_list, manager/manager_add, manager/manager_remove, manager/manager_control, manager/manager_properties
-TOOLS=datapoints/dp_basic,datapoints/dp_create,datapoints/dp_set,datapoints/dp_types,datapoints/dp_type_create,icons/icon,opcua/opcua_connection,opcua/opcua_address,common/common_query,common/common_set,common/common_delete,alarms/alarm_set,alarms/alarm_delete,archive/archive_set,archive/archive_delete,archive/archive_query,dashboards/dashboard,dashboards/widget,pv_range/pv_range_query,pv_range/pv_range_set,pv_range/pv_range_delete
+
+# Default: Read-only tools only (safe starting point)
+# Uncomment and modify for write access - see README.md for security considerations
+TOOLS=datapoints/dp_basic,datapoints/dp_types,archive/archive_query,common/common_query,pv_range/pv_range_query,manager/manager_list
+
+# Full feature set (includes write operations - use with caution):
+# TOOLS=datapoints/dp_basic,datapoints/dp_create,datapoints/dp_set,datapoints/dp_types,datapoints/dp_type_create,icons/icon,opcua/opcua_connection,opcua/opcua_address,mqtt/mqtt_connection,common/common_query,common/common_set,common/common_delete,alarms/alarm_set,alarms/alarm_delete,archive/archive_set,archive/archive_delete,archive/archive_query,dashboards/dashboard,dashboards/widget,pv_range/pv_range_query,pv_range/pv_range_set,pv_range/pv_range_delete,manager/manager_list,manager/manager_control,manager/manager_add,manager/manager_remove,manager/manager_properties

package/README.md

@@ -25,6 +25,7 @@ This Model Context Protocol (MCP) server connects AI assistants to WinCC OA SCAD
 - **Managers**: `manager/manager_control`, `manager/manager_add`, `manager/manager_remove`, `manager/manager_properties`
 - **Dashboards**: `dashboards/dashboard`, `dashboards/widget`
 - **OPC UA**: `opcua/opcua_connection`, `opcua/opcua_address`
+- **MQTT**: `mqtt/mqtt_connection`
 
 **Note**: Icon tools (`icons/icon`) create/delete SVG files but don't modify SCADA data.
 
@@ -101,16 +102,18 @@ WINCCOA_FIELD=default  # or 'oil', 'transport'
 
 # Configure available tools (examples - see docs/TOOLS.md for complete list)
 # Full feature set
-TOOLS=datapoints/dp_basic,datapoints/dp_set,opcua/opcua_connection,dashboards/dashboard,manager/manager_list
+TOOLS=datapoints/dp_basic,datapoints/dp_set,opcua/opcua_connection,mqtt/mqtt_connection,dashboards/dashboard,manager/manager_list
+# Default: Read-only monitoring (safe starting point)
+TOOLS=datapoints/dp_basic,datapoints/dp_types,archive/archive_query,common/common_query,pv_range/pv_range_query,manager/manager_list
 
-# Dashboard-focused setup
+# Dashboard-focused setup (includes write operations)
 # TOOLS=datapoints/dp_basic,dashboards/dashboard,dashboards/widget,icons/icon
 
-# Manager control setup
+# Manager control setup (includes write operations)
 # TOOLS=manager/manager_list,manager/manager_control,manager/manager_add
 
-# Read-only monitoring
-# TOOLS=datapoints/dp_basic,archive/archive_query,alarms/alarm_query,manager/manager_list
+# Full feature set (includes all write operations - use with caution)
+# TOOLS=datapoints/dp_basic,datapoints/dp_set,opcua/opcua_connection,dashboards/dashboard,manager/manager_list
 ```
 
 ### 3. Start Server
@@ -162,6 +165,33 @@ This method uses `cmd` to properly handle paths with spaces in Windows.
 - On Windows: Close Claude through the task-tray menu by selecting "Exit", or end the task in Task Manager if needed
 - On macOS/Linux: Quit Claude Desktop completely and restart
 
+**Remote Host:** When connecting to a remote WinCC OA server (not `localhost`), you must add the `--allow-http` flag to the `mcp-remote` args. Example:
+
+```json
+{
+  "mcpServers": {
+    "winccoa": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://winccoaserver:3000/mcp", "--header", "Authorization: Bearer YOUR_TOKEN_HERE", "--allow-http"]
+    }
+  }
+}
+```
+
+### 5. Connect Claude Code (CLI)
+
+If you are using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (the CLI), you can add the MCP server directly from your terminal:
+
+```bash
+claude mcp add --transport http winccoa http://localhost:3000/mcp --header "Authorization: Bearer your-secure-token-here"
+```
+
+**Remote Host:** When connecting to a remote WinCC OA server (not `localhost`), add the `--allow-http` flag:
+
+```bash
+claude mcp add --transport http winccoa http://winccoaserver:3000/mcp --header "Authorization: Bearer your-secure-token-here" --allow-http
+```
+
 ## Documentation
 
 - **[📦 Installation Guide](docs/INSTALLATION.md)** - Complete setup instructions
@@ -182,6 +212,7 @@ This method uses `cmd` to properly handle paths with spaces in Windows.
 
 - **📊 Datapoints** - Read, write, and create datapoints and types
 - **🔗 OPC UA** - Connect to OPC UA servers and browse address spaces
+- **📡 MQTT** - Connect to MQTT brokers and map topics to datapoints
 - **📈 Dashboards & Widgets** - Create and manage visualization dashboards
 - **🚨 Alarms** - Configure alarm thresholds and notifications
 - **📁 Archives** - Query and configure historical data storage

package/build/helpers/drivers/MqttConnection.d.ts

@@ -0,0 +1,113 @@
+/**
+ * MQTT Connection Manager
+ *
+ * Provides functionality to create, configure, and manage MQTT connections in WinCC OA.
+ * Based on WinCC OA _MqttConnection internal datapoint structure.
+ */
+import { BaseConnection } from './BaseConnection.js';
+import type { MqttConnectionConfig, MqttAddressParams } from '../../types/index.js';
+import { MqttConnectionState } from '../../types/index.js';
+export { MqttConnectionType, MqttConnectionState, MqttProtocolVersion, MqttSslVersion, MqttQoS, MqttAddressDirection, MqttTransformation, MQTT_DEFAULTS } from '../../types/index.js';
+/**
+ * MQTT Connection Manager Class
+ *
+ * Extends BaseConnection with MQTT-specific functionality.
+ */
+export declare class MqttConnection extends BaseConnection {
+    /**
+     * Generate a unique connection name for MQTT
+     * @returns Connection name in format _MqttConnection<n>
+     */
+    generateConnectionName(): Promise<string>;
+    /**
+     * Get available MQTT driver numbers from Pmon
+     * Similar to CTRL paMqttCheckDrvNums()
+     * @returns Array of MQTT driver numbers, sorted ascending
+     */
+    getMqttDriverNumbers(): Promise<number[]>;
+    /**
+     * Get all used driver numbers (MQTT, simulation, other drivers)
+     * @returns Array of used driver numbers
+     */
+    getUsedDriverNumbers(): Promise<number[]>;
+    /**
+     * Get the lowest available MQTT driver number (avoiding sim driver conflicts)
+     * @returns Lowest available driver number for MQTT
+     */
+    getDefaultMqttDriverNumber(): Promise<number>;
+    /**
+     * Ensure MQTT driver with specified number is running
+     * Creates and starts the driver if it doesn't exist
+     * @param managerNumber - The driver number to ensure
+     * @returns Object with success status and optional warnings
+     */
+    ensureMqttDriverRunning(managerNumber: number): Promise<{
+        success: boolean;
+        error?: string;
+        warnings?: string[];
+    }>;
+    /**
+     * Build the JSON address string for Config.Address
+     * This is the format stored in _MqttConnection.Config.Address
+     * Required keys: Username, ConnectionType, ConnectionString, Certificate, Password, Identity, PSK
+     */
+    private buildAddressJson;
+    /**
+     * Add a new MQTT connection
+     *
+     * @param config - MQTT connection configuration
+     * @returns Object with success status, connection name, and any errors
+     */
+    addConnection(config: MqttConnectionConfig): Promise<{
+        success: boolean;
+        connectionName?: string;
+        error?: string;
+    }>;
+    /**
+     * Delete an MQTT connection
+     *
+     * @param connectionName - Name of the connection to delete (with or without leading _)
+     * @returns Object with success status and any errors
+     */
+    deleteConnection(connectionName: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get the connection state of an MQTT connection
+     *
+     * @param connectionName - Name of the connection
+     * @returns Connection state or error
+     */
+    getConnectionState(connectionName: string): Promise<{
+        success: boolean;
+        state?: MqttConnectionState;
+        stateText?: string;
+        error?: string;
+    }>;
+    /**
+     * List all MQTT connections
+     *
+     * @returns Array of connection names and their states
+     */
+    listConnections(): Promise<{
+        success: boolean;
+        connections?: Array<{
+            name: string;
+            state: MqttConnectionState;
+            stateText: string;
+            connectionString?: string;
+        }>;
+        error?: string;
+    }>;
+    /**
+     * Configure address settings for a datapoint (peripheral address)
+     * Implementation of abstract method from BaseConnection
+     *
+     * @param params - MQTT address parameters
+     * @returns true on success
+     * @throws Error with detailed message on failure
+     */
+    addAddressConfig(params: MqttAddressParams): Promise<boolean>;
+}
+//# sourceMappingURL=MqttConnection.d.ts.map

package/build/helpers/drivers/MqttConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MqttConnection.d.ts","sourceRoot":"","sources":["../../../src/helpers/drivers/MqttConnection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,mBAAmB,EAOpB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,OAAO,EACP,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAE9B;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAEhD;;;OAGG;IACG,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI/C;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B/C;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA4B/C;;;OAGG;IACG,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBnD;;;;;OAKG;IACG,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5D,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IA+IF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAmCxB;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC;QACzD,OAAO,EAAE,OAAO,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IA0MF;;;;;OAKG;IACG,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QACtD,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAuCF;;;;;OAKG;IACG,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QACxD,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,mBAAmB,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAgCF;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC;QAC/B,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,CAAC,EAAE,KAAK,CAAC;YAClB,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,mBAAmB,CAAC;YAC3B,SAAS,EAAE,MAAM,CAAC;YAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;SAC3B,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAyDF;;;;;;;OAOG;IACG,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;CAoFpE"}