opcua-mcp-server 0.2.1__tar.gz

opcua_mcp_server-0.2.1/.gitignore

@@ -0,0 +1,42 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Python
+__pycache__/
+*.py[oc]
+*.egg-info/
+build/
+dist/
+wheels/
+.venv/
+.pytest_cache/
+
+# Node / TypeScript
+node_modules/
+*.tsbuildinfo
+.npm
+*.tgz
+coverage/
+.eslintcache
+.env
+.env.*
+
+# Local Claude Code config (machine-specific)
+.mcp.json
+.claude/settings.local.json

opcua_mcp_server-0.2.1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: opcua-mcp-server
+Version: 0.2.1
+Summary: MCP server exposing OPC UA read/write/browse/method/history tools (FastMCP + python-opcua).
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=45.0.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]<2,>=1.9.1
+Requires-Dist: opcua>=0.98.13
+Description-Content-Type: text/markdown
+
+# OPC UA MCP Server
+
+A Model Context Protocol (MCP) server that provides seamless integration with OPC UA servers. This server enables AI assistants and other MCP clients to interact with industrial automation systems through standardized OPC UA communication protocols.
+
+## Overview
+
+This MCP server acts as a bridge between AI assistants and OPC UA servers, allowing for:
+- Reading sensor data and system variables
+- Writing control values to actuators and systems
+- Browsing OPC UA node hierarchies
+- Calling OPC UA methods for system operations
+- Batch operations for multiple nodes
+
+## Tools
+
+See the central per-tool reference in **[../../docs/examples.md](../../docs/examples.md)**; the shared tool surface is defined in **[../../contract/tools.json](../../contract/tools.json)**.
+
+## Features
+
+### Key Capabilities
+
+- **Automatic Connection Management**: Handles OPC UA client lifecycle with proper connection setup and teardown
+- **Type-Safe Operations**: Automatic type conversion based on existing node data types
+- **Error Handling**: Comprehensive error reporting for debugging and monitoring
+- **Async Support**: Built on FastMCP for efficient asynchronous operations
+- **Configurable**: Environment-based server URL configuration
+
+## Installation
+
+### Prerequisites
+
+- Python 3.13 or higher
+- Access to an OPC UA server (local or remote)
+- UV package manager (recommended) or pip
+
+### Setup
+
+1. **Install dependencies for the whole workspace (run from the repo root):**
+   ```bash
+   uv sync --all-packages
+   ```
+
+2. **Configure the OPC UA server URL:**
+   ```bash
+   export OPCUA_SERVER_URL="opc.tcp://localhost:4840"
+   ```
+
+## Usage
+
+### Running the Server
+
+After `uv sync --all-packages` from the repo root:
+```bash
+uv run --no-sync opcua-mcp-server
+```
+
+Or run it directly against this package from anywhere in the repo:
+```bash
+uv --directory packages/server-python run opcua-mcp-server
+```
+
+### Integration with MCP Clients
+
+Add to your MCP client configuration (e.g., `config.json`):
+
+```json
+{
+  "mcpServers": {
+    "opcua-mcp": {
+      "command": "/path/to/uv",
+      "args": [
+        "--directory",
+        "/path/to/packages/server-python",
+        "run",
+        "opcua-mcp-server"
+      ],
+      "env": {
+        "OPCUA_SERVER_URL": "opc.tcp://localhost:4840"
+      }
+    }
+  }
+}
+```
+
+## Example Usage in Conversation
+
+Once configured, you can ask Claude to perform real-world OPC UA operations:
+
+### Reading Sensor Values
+- "What is the current temperature reading from the reactor vessel?"
+- "Check the pressure level in Tank A"
+- "Read all temperature sensors in the cooling system"
+- "Get the current flow rate on production line B"
+
+### Controlling Equipment
+- "Turn on the conveyor motor"
+- "Set the mixer speed to 80 RPM"
+- "Open valve V-101 to 75% position"
+- "Start the circulation pump"
+- "Set the heating element to 150°C"
+
+### Production Operations
+- "Start production on line 1 with rate 100 units/hour"
+- "Stop all motors in emergency mode"
+- "Initialize the batch reactor with recipe A"
+- "Begin the cleaning cycle for Tank B"
+
+### System Monitoring
+- "Show me all alarm states in the system"
+- "Read all sensor values from the water treatment plant"
+- "Check the status of all pumps and motors"
+- "Get the energy consumption readings"
+- "What variables are available on this OPC UA server?"
+- "Show me all sensors and their current values"
+
+### Real Example Scenarios
+```
+User: "What's the temperature in reactor R-101?"
+Assistant: I'll read the temperature sensor for reactor R-101.
+Tool call: read_opcua_node with node_id "ns=2;i=11"
+Result: "Reactor R-101 temperature: 87.3°C"
+
+User: "Turn on the main conveyor motor"
+Assistant: I'll start the main conveyor motor for you.
+Tool call: write_opcua_node with node_id "ns=2;i=12" and value "true"
+Result: "Main conveyor motor started successfully"
+
+User: "Set the pump speed to 65%"
+Assistant: I'll adjust the pump speed to 65%.
+Tool call: write_opcua_node with node_id "ns=2;i=13" and value "65"
+Result: "Pump speed set to 65%"
+
+User: "What variables are available on this OPC UA server?"
+Assistant: I'll retrieve all available variables from the OPC UA server.
+Tool call: get_all_variables
+Result: Found 5 variables:
+- Temperature (ns=2;i=2): 25.3°C - Temperature sensor
+- Pressure (ns=2;i=3): 5.0 bar - Pressure sensor  
+- MotorSpeed (ns=2;i=4): 1500 RPM - Motor speed
+- MotorState (ns=2;i=5): True - Motor ON/OFF state
+- ValvePosition (ns=2;i=6): False - Valve OPEN/CLOSED position
+```
+
+## API Reference
+
+See the central per-tool reference in **[../../docs/examples.md](../../docs/examples.md)** for full tool signatures, parameters, and return formats. The shared tool surface is defined in **[../../contract/tools.json](../../contract/tools.json)**.

opcua_mcp_server-0.2.1/README.md

@@ -0,0 +1,146 @@
+# OPC UA MCP Server
+
+A Model Context Protocol (MCP) server that provides seamless integration with OPC UA servers. This server enables AI assistants and other MCP clients to interact with industrial automation systems through standardized OPC UA communication protocols.
+
+## Overview
+
+This MCP server acts as a bridge between AI assistants and OPC UA servers, allowing for:
+- Reading sensor data and system variables
+- Writing control values to actuators and systems
+- Browsing OPC UA node hierarchies
+- Calling OPC UA methods for system operations
+- Batch operations for multiple nodes
+
+## Tools
+
+See the central per-tool reference in **[../../docs/examples.md](../../docs/examples.md)**; the shared tool surface is defined in **[../../contract/tools.json](../../contract/tools.json)**.
+
+## Features
+
+### Key Capabilities
+
+- **Automatic Connection Management**: Handles OPC UA client lifecycle with proper connection setup and teardown
+- **Type-Safe Operations**: Automatic type conversion based on existing node data types
+- **Error Handling**: Comprehensive error reporting for debugging and monitoring
+- **Async Support**: Built on FastMCP for efficient asynchronous operations
+- **Configurable**: Environment-based server URL configuration
+
+## Installation
+
+### Prerequisites
+
+- Python 3.13 or higher
+- Access to an OPC UA server (local or remote)
+- UV package manager (recommended) or pip
+
+### Setup
+
+1. **Install dependencies for the whole workspace (run from the repo root):**
+   ```bash
+   uv sync --all-packages
+   ```
+
+2. **Configure the OPC UA server URL:**
+   ```bash
+   export OPCUA_SERVER_URL="opc.tcp://localhost:4840"
+   ```
+
+## Usage
+
+### Running the Server
+
+After `uv sync --all-packages` from the repo root:
+```bash
+uv run --no-sync opcua-mcp-server
+```
+
+Or run it directly against this package from anywhere in the repo:
+```bash
+uv --directory packages/server-python run opcua-mcp-server
+```
+
+### Integration with MCP Clients
+
+Add to your MCP client configuration (e.g., `config.json`):
+
+```json
+{
+  "mcpServers": {
+    "opcua-mcp": {
+      "command": "/path/to/uv",
+      "args": [
+        "--directory",
+        "/path/to/packages/server-python",
+        "run",
+        "opcua-mcp-server"
+      ],
+      "env": {
+        "OPCUA_SERVER_URL": "opc.tcp://localhost:4840"
+      }
+    }
+  }
+}
+```
+
+## Example Usage in Conversation
+
+Once configured, you can ask Claude to perform real-world OPC UA operations:
+
+### Reading Sensor Values
+- "What is the current temperature reading from the reactor vessel?"
+- "Check the pressure level in Tank A"
+- "Read all temperature sensors in the cooling system"
+- "Get the current flow rate on production line B"
+
+### Controlling Equipment
+- "Turn on the conveyor motor"
+- "Set the mixer speed to 80 RPM"
+- "Open valve V-101 to 75% position"
+- "Start the circulation pump"
+- "Set the heating element to 150°C"
+
+### Production Operations
+- "Start production on line 1 with rate 100 units/hour"
+- "Stop all motors in emergency mode"
+- "Initialize the batch reactor with recipe A"
+- "Begin the cleaning cycle for Tank B"
+
+### System Monitoring
+- "Show me all alarm states in the system"
+- "Read all sensor values from the water treatment plant"
+- "Check the status of all pumps and motors"
+- "Get the energy consumption readings"
+- "What variables are available on this OPC UA server?"
+- "Show me all sensors and their current values"
+
+### Real Example Scenarios
+```
+User: "What's the temperature in reactor R-101?"
+Assistant: I'll read the temperature sensor for reactor R-101.
+Tool call: read_opcua_node with node_id "ns=2;i=11"
+Result: "Reactor R-101 temperature: 87.3°C"
+
+User: "Turn on the main conveyor motor"
+Assistant: I'll start the main conveyor motor for you.
+Tool call: write_opcua_node with node_id "ns=2;i=12" and value "true"
+Result: "Main conveyor motor started successfully"
+
+User: "Set the pump speed to 65%"
+Assistant: I'll adjust the pump speed to 65%.
+Tool call: write_opcua_node with node_id "ns=2;i=13" and value "65"
+Result: "Pump speed set to 65%"
+
+User: "What variables are available on this OPC UA server?"
+Assistant: I'll retrieve all available variables from the OPC UA server.
+Tool call: get_all_variables
+Result: Found 5 variables:
+- Temperature (ns=2;i=2): 25.3°C - Temperature sensor
+- Pressure (ns=2;i=3): 5.0 bar - Pressure sensor  
+- MotorSpeed (ns=2;i=4): 1500 RPM - Motor speed
+- MotorState (ns=2;i=5): True - Motor ON/OFF state
+- ValvePosition (ns=2;i=6): False - Valve OPEN/CLOSED position
+```
+
+## API Reference
+
+See the central per-tool reference in **[../../docs/examples.md](../../docs/examples.md)** for full tool signatures, parameters, and return formats. The shared tool surface is defined in **[../../contract/tools.json](../../contract/tools.json)**.

opcua_mcp_server-0.2.1/contract/tools.json

@@ -0,0 +1,197 @@
+{
+  "$comment": "Single source of truth for the OPC UA MCP tool surface shared by both servers. The Node server builds its tools/list response directly from this file (copied into build/ at build time). The Python (FastMCP) server reads tool descriptions and the capability node IDs from it; its signature-derived input schemas are checked against this file by tests/test_contract_parity.py. To add or change a tool: edit this file, then update each server's per-tool logic (Node: a case in the CallTool switch; Python: the @mcp.tool function), and add an E2E test.",
+  "capabilities": {
+    "history": {
+      "nodeId": "ns=0;i=11193",
+      "browseName": "AccessHistoryDataCapability",
+      "check": "readBooleanTrue"
+    },
+    "aggregate": {
+      "nodeId": "ns=0;i=2997",
+      "browseName": "AggregateFunctions",
+      "check": "browseNonEmpty"
+    }
+  },
+  "tools": [
+    {
+      "name": "read_opcua_node",
+      "capability": null,
+      "description": "Read the value of a specific OPC UA node",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'. Example: 'ns=2;i=2'."
+          }
+        },
+        "required": ["node_id"]
+      }
+    },
+    {
+      "name": "write_opcua_node",
+      "capability": null,
+      "description": "Write a value to a specific OPC UA node",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'. Example: 'ns=2;i=3'."
+          },
+          "value": {
+            "type": "string",
+            "description": "The value to write to the node. Will be converted based on node type."
+          }
+        },
+        "required": ["node_id", "value"]
+      }
+    },
+    {
+      "name": "browse_opcua_node_children",
+      "capability": null,
+      "description": "Browse the children of a specific OPC UA node",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID to browse (e.g., 'ns=0;i=85' for Objects folder)."
+          }
+        },
+        "required": ["node_id"]
+      }
+    },
+    {
+      "name": "read_multiple_opcua_nodes",
+      "capability": null,
+      "description": "Read the values of multiple OPC UA nodes in a single request",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "A list of OPC UA node IDs to read (e.g., ['ns=2;i=2', 'ns=2;i=3'])."
+          }
+        },
+        "required": ["node_ids"]
+      }
+    },
+    {
+      "name": "write_multiple_opcua_nodes",
+      "capability": null,
+      "description": "Write values to multiple OPC UA nodes in a single request",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "nodes_to_write": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "node_id": { "type": "string" },
+                "value": { "type": "string" }
+              },
+              "required": ["node_id", "value"]
+            },
+            "description": "A list of objects containing 'node_id' and 'value'. Example: [{'node_id': 'ns=2;i=2', 'value': '10.5'}, {'node_id': 'ns=2;i=3', 'value': 'active'}]"
+          }
+        },
+        "required": ["nodes_to_write"]
+      }
+    },
+    {
+      "name": "call_opcua_method",
+      "capability": null,
+      "description": "Call a method on a specific OPC UA object node",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "object_node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID of the object that contains the method. Example: 'ns=2;i=1' for the Methods folder."
+          },
+          "method_node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID of the method to call. Example: 'ns=2;i=2' for StartProduction method."
+          },
+          "arguments": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "List of arguments to pass to the method. Arguments will be converted to appropriate OPC UA variants."
+          }
+        },
+        "required": ["object_node_id", "method_node_id"]
+      }
+    },
+    {
+      "name": "get_all_variables",
+      "capability": null,
+      "description": "Get all available variables from the OPC UA server, excluding those under the built-in 'Server' object",
+      "inputSchema": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      }
+    },
+    {
+      "name": "read_history_opcua_node",
+      "capability": "history",
+      "description": "Read the historical values of a specific OPC UA node",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'. Example: 'ns=2;i=2'."
+          },
+          "start_time": {
+            "type": "string",
+            "description": "Beginning of the retrieval"
+          },
+          "end_time": {
+            "type": "string",
+            "description": "End of the retrieval"
+          },
+          "num_values": {
+            "type": "number",
+            "description": "Number of values to read (default: unlimited)"
+          }
+        },
+        "required": ["node_id"]
+      }
+    },
+    {
+      "name": "read_aggregate_opcua_node",
+      "capability": "aggregate",
+      "description": "Calculate the historical aggregates over a defined time range, divided into smaller chunks defined by the `processing_interval` (in milliseconds). The server divides the [`start_time`, `end_time`] domain into these intervals, returning one aggregated value per interval",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'. Example: 'ns=2;i=2'."
+          },
+          "start_time": {
+            "type": "string",
+            "description": "Beginning of the retrieval"
+          },
+          "end_time": {
+            "type": "string",
+            "description": "End of the retrieval (defaults to 'now')"
+          },
+          "aggregate_function": {
+            "type": "string",
+            "description": "The specific formula"
+          },
+          "processing_interval": {
+            "type": "number",
+            "description": "The duration (ms) for each computed value. If set to 0, the server calculates a single aggregate value for the entire range."
+          }
+        },
+        "required": ["node_id", "start_time", "aggregate_function"]
+      }
+    }
+  ]
+}

opcua_mcp_server-0.2.1/hatch_build.py

@@ -0,0 +1,46 @@
+"""Build hook that stages the shared tool contract inside the wheel.
+
+The canonical contract lives at the repo root (`/contract/tools.json`), outside
+this package. A static `force-include` pointing at `../../` works when building
+from a checkout, but breaks when the wheel is built *from an sdist* — which is
+what `uv build` and `pip install <sdist>` do — because an sdist cannot contain
+files from outside its own root:
+
+    FileNotFoundError: Forced include not found: .../contract/tools.json
+
+So the sdist carries its own copy at `contract/tools.json` (see the sdist
+force-include in pyproject.toml), and this hook injects whichever copy exists
+into the wheel at build time. It adds to `build_data` rather than writing into
+the source tree, so building never leaves artefacts behind.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+#: Where the wheel expects to find it; `contract.py` reads this path.
+WHEEL_PATH = "opcua_mcp_server/tools.json"
+
+
+class ContractBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "opcua-contract"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        if self.target_name != "wheel":
+            return
+
+        root = Path(self.root)
+        candidates = (
+            root.parents[1] / "contract" / "tools.json",  # repo checkout
+            root / "contract" / "tools.json",  # unpacked sdist
+        )
+        for candidate in candidates:
+            if candidate.is_file():
+                build_data["force_include"][str(candidate)] = WHEEL_PATH
+                return
+
+        raise FileNotFoundError(
+            "Shared tool contract not found; looked in " + ", ".join(str(c) for c in candidates)
+        )

opcua_mcp_server-0.2.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "opcua-mcp-server"
+version = "0.2.1"
+description = "MCP server exposing OPC UA read/write/browse/method/history tools (FastMCP + python-opcua)."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=45.0.2",
+    "httpx>=0.28.1",
+    # Upper bound is load-bearing: mcp 2.x renamed FastMCP to MCPServer, so an
+    # unbounded install resolves 2.x and crashes on import. Migrating to the 2.x
+    # API is tracked separately.
+    "mcp[cli]>=1.9.1,<2",
+    "opcua>=0.98.13",
+]
+
+[project.scripts]
+opcua-mcp-server = "opcua_mcp_server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opcua_mcp_server"]
+
+# The contract is injected into the wheel by hatch_build.py rather than by a
+# static force-include, because the path differs between a checkout and an
+# unpacked sdist. See that file for the full explanation.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+# The sdist must be self-contained: it carries its own copy of the contract (and
+# the build hook) so that building a wheel from it works outside a checkout.
+[tool.hatch.build.targets.sdist]
+include = ["src", "hatch_build.py", "pyproject.toml", "README.md"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../contract/tools.json" = "contract/tools.json"

opcua_mcp_server-0.2.1/src/opcua_mcp_server/__init__.py

@@ -0,0 +1,27 @@
+"""OPC UA MCP server (Python runtime).
+
+Exposes OPC UA read/write/browse/method/history operations as MCP tools. The
+tool surface is defined once in ``contract/tools.json`` and shared with the Node
+runtime; see ``contract.py``.
+
+Importing this package connects to the configured OPC UA server once, to probe
+which capability-gated tools to register (see ``capabilities``).
+"""
+
+from __future__ import annotations
+
+from .config import SERVER_URL
+from .contract import CONTRACT, DESC, HISTORY_NODE_ID, load_contract
+from .datetimes import parse_iso_datetime
+from .server import main, mcp
+
+__all__ = [
+    "CONTRACT",
+    "DESC",
+    "HISTORY_NODE_ID",
+    "SERVER_URL",
+    "load_contract",
+    "main",
+    "mcp",
+    "parse_iso_datetime",
+]

opcua_mcp_server-0.2.1/src/opcua_mcp_server/aggregates.py

@@ -0,0 +1,58 @@
+"""Mapping between OPC UA aggregate function names and their node IDs.
+
+The OPC UA spec defines aggregate functions as well-known nodes in namespace 0
+(``AggregateFunction_Average`` = ``i=2342`` and friends). A server advertises the
+subset it implements by exposing them under ``Server/ServerCapabilities/
+AggregateFunctions``; this module turns the browse names found there back into
+the node IDs a ``ReadProcessedDetails`` request needs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+
+from opcua import ua
+
+_PREFIX = "AggregateFunction_"
+
+
+def known_aggregate_names() -> frozenset[str]:
+    """Every aggregate function name defined by the OPC UA spec."""
+    return frozenset(name[len(_PREFIX) :] for name in dir(ua.ObjectIds) if name.startswith(_PREFIX))
+
+
+def spec_aggregate_node_ids() -> dict[str, ua.NodeId]:
+    """Every spec-defined aggregate function name mapped to its node ID."""
+    return {
+        name.removeprefix(_PREFIX): ua.NodeId(identifier, 0)
+        for name, identifier in vars(ua.ObjectIds).items()
+        if name.startswith(_PREFIX)
+    }
+
+
+def aggregate_node_id(name: str) -> ua.NodeId:
+    """Node ID for a spec-defined aggregate function name.
+
+    Raises ValueError for anything not in the spec, so an unknown name fails
+    before a request is put on the wire.
+    """
+    try:
+        identifier = getattr(ua.ObjectIds, f"{_PREFIX}{name}")
+    except AttributeError:
+        raise ValueError(f"Unknown aggregate function: {name}") from None
+    return ua.NodeId(identifier, 0)
+
+
+def validate_aggregate_function(name: str, supported: Collection[str]) -> None:
+    """Raise unless ``name`` is one the connected server advertises.
+
+    The two messages are mirrored verbatim by the Node server, so both runtimes
+    reject the same input the same way.
+    """
+    if name in supported:
+        return
+    raise ValueError(
+        "Server does not advertise any aggregate functions"
+        if not supported
+        else f"Invalid aggregate function. Supported: {', '.join(supported)}"
+    )

opcua_mcp_server-0.2.1/src/opcua_mcp_server/capabilities.py

@@ -0,0 +1,65 @@
+"""Runtime probes for optional OPC UA server capabilities.
+
+Tools that depend on a capability are only registered when the connected
+server actually advertises it, mirroring the Node server's gating.
+"""
+
+from __future__ import annotations
+
+from opcua import Client, ua
+
+from .aggregates import spec_aggregate_node_ids
+from .contract import AGGREGATE_NODE_ID, HISTORY_NODE_ID
+
+
+def server_supports_history(url: str) -> bool:
+    """Probe the server's AccessHistoryDataCapability (ns=0;i=11193).
+
+    Used to expose `read_history_opcua_node` only when the server actually
+    supports historical reads, matching the Node server's behaviour.
+    """
+    try:
+        probe = Client(url)
+        probe.connect()
+        try:
+            return bool(probe.get_node(HISTORY_NODE_ID).get_value())
+        finally:
+            probe.disconnect()
+    except Exception:
+        return False
+
+
+def server_aggregate_functions(url: str) -> dict[str, ua.NodeId]:
+    """The aggregate functions the server advertises, mapped to their node IDs.
+
+    Browses ``Server/ServerCapabilities/AggregateFunctions`` and keeps only
+    children whose browse name *and* node ID match a spec-defined aggregate, so a
+    server exposing something unexpected under that folder cannot smuggle in a
+    node ID we then send back in a request.
+
+    Best-effort: any failure yields an empty mapping rather than an error, so a
+    transient outage leaves the core tools advertised instead of breaking
+    tools/list.
+    """
+    spec = spec_aggregate_node_ids()
+    try:
+        probe = Client(url)
+        probe.connect()
+        try:
+            node = probe.get_node(AGGREGATE_NODE_ID)
+            advertised = {}
+            for child in node.get_referenced_nodes(
+                refs=ua.ObjectIds.References,
+                direction=ua.BrowseDirection.Forward,
+            ):
+                try:
+                    name = child.get_browse_name().Name
+                except Exception:
+                    continue
+                if name in spec and child.nodeid == spec[name]:
+                    advertised[name] = child.nodeid
+            return advertised
+        finally:
+            probe.disconnect()
+    except Exception:
+        return {}

opcua_mcp_server-0.2.1/src/opcua_mcp_server/config.py

@@ -0,0 +1,8 @@
+"""Runtime configuration, read from the environment."""
+
+from __future__ import annotations
+
+import os
+
+#: OPC UA endpoint both the server and the capability probes connect to.
+SERVER_URL = os.getenv("OPCUA_SERVER_URL", "opc.tcp://localhost:4840")

opcua_mcp_server-0.2.1/src/opcua_mcp_server/contract.py

@@ -0,0 +1,42 @@
+"""The shared tool contract — the single source of truth both servers derive from."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def load_contract() -> dict:
+    """Load the shared tool contract (single source of truth).
+
+    Two locations, in order:
+
+    1. ``tools.json`` inside this package — how it ships in the wheel (see the
+       ``force-include`` in pyproject.toml). Bundling it *inside* the package
+       rather than at the install root keeps the distribution from adding
+       top-level files to ``site-packages``.
+    2. ``/contract/tools.json`` at the repo root — the canonical source, used when
+       running from a checkout (dev, editable installs, tests).
+
+    Without (1) a pip/uvx install would raise FileNotFoundError on import, because
+    the repo-root path does not exist outside a checkout.
+    """
+    here = Path(__file__).resolve()
+    candidates = (
+        here.parent / "tools.json",  # bundled inside the wheel
+        here.parents[4] / "contract" / "tools.json",  # repo-root source layout
+    )
+    for path in candidates:
+        if path.is_file():
+            return json.loads(path.read_text())
+    raise FileNotFoundError(
+        "Shared tool contract not found; looked in " + ", ".join(str(p) for p in candidates)
+    )
+
+
+# Shared tool contract so tool descriptions and capability node IDs stay in sync
+# with the Node server.
+CONTRACT = load_contract()
+DESC = {t["name"]: t["description"] for t in CONTRACT["tools"]}
+HISTORY_NODE_ID = CONTRACT["capabilities"]["history"]["nodeId"]
+AGGREGATE_NODE_ID = CONTRACT["capabilities"]["aggregate"]["nodeId"]

opcua_mcp_server-0.2.1/src/opcua_mcp_server/datetimes.py

@@ -0,0 +1,22 @@
+"""Conversion between the ISO-8601 strings MCP delivers and datetimes."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+
+def parse_iso_datetime(value: str | None) -> datetime | None:
+    """Parse an optional ISO-8601 string into a datetime.
+
+    MCP delivers these as strings, so they are converted here before being handed
+    to the opcua client. Mirrors the Node server's ``toDate`` error wording so both
+    servers reject malformed input identically.
+    """
+    if value is None:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        raise ValueError(
+            f'Invalid date/time: "{value}". Use ISO 8601, e.g. 2026-04-23T17:40:00Z'
+        ) from None

opcua_mcp_server-0.2.1/src/opcua_mcp_server/server.py

@@ -0,0 +1,511 @@
+"""The MCP server: lifecycle, tool registration, and the stdio entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from mcp.server.fastmcp import Context, FastMCP
+from opcua import Client, ua
+from opcua.ua import NodeClass
+
+from .aggregates import validate_aggregate_function
+from .capabilities import server_aggregate_functions, server_supports_history
+from .config import SERVER_URL
+from .contract import DESC
+from .datetimes import parse_iso_datetime
+
+
+# Manage the lifecycle of the OPC UA client connection
+@asynccontextmanager
+async def opcua_lifespan(server: FastMCP) -> AsyncIterator[dict]:
+    """Handle OPC UA client connection lifecycle."""
+    client = Client(SERVER_URL)
+    try:
+        # Connect to OPC UA server synchronously, wrapped in a thread for async compatibility
+        await asyncio.to_thread(client.connect)
+        # Log to stderr: stdout is reserved for the MCP stdio JSON-RPC transport.
+        print("Connected to OPC UA server", file=sys.stderr)
+        yield {"opcua_client": client}
+    finally:
+        # Disconnect from OPC UA server on shutdown
+        await asyncio.to_thread(client.disconnect)
+        print("Disconnected from OPC UA server", file=sys.stderr)
+
+
+def _package_version() -> str:
+    """Version of the installed distribution, single-sourced from pyproject.toml.
+
+    Falls back to "0.0.0+unknown" when running from a source tree that was never
+    installed (the distribution metadata is absent), so importing never fails.
+    """
+    try:
+        return version("opcua-mcp-server")
+    except PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+# Create an MCP server instance. The server identity must match the Node server's
+# so both runtimes present themselves as the same product to MCP clients.
+mcp = FastMCP("opcua-mcp-server", lifespan=opcua_lifespan)
+# FastMCP does not expose the protocol-level version in its constructor, so set it
+# on the underlying low-level server. Without this the Python server reports a
+# null version over MCP while the Node server reports a real one.
+mcp._mcp_server.version = _package_version()
+
+
+# Tool: Read the value of an OPC UA node
+@mcp.tool(description=DESC["read_opcua_node"])
+def read_opcua_node(node_id: str, ctx: Context) -> str:
+    """
+    Read the value of a specific OPC UA node.
+
+    Parameters:
+        node_id (str): The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'.
+                       Example: 'ns=2;i=2'.
+
+    Returns:
+        str: The value of the node as a string, prefixed with the node ID.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    node = client.get_node(node_id)
+    value = node.get_value()  # Synchronous call to get node value
+    return f"Node {node_id} value: {value}"
+
+
+# Tool: Read historical values of an OPC UA node.
+# Registered only when the server supports historical data access (see below),
+# mirroring the Node server's capability gating.
+def read_history_opcua_node(
+    node_id: str,
+    ctx: Context,
+    start_time: str | None = None,
+    end_time: str | None = None,
+    num_values: int = 0,
+) -> list[dict]:
+    """
+    Read the historical values of a specific OPC UA node.
+
+    Parameters:
+        node_id (str): The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'.
+                       Example: 'ns=2;i=2'.
+        start_time (str): Start time (ISO 8601).
+                          Example: '2026-04-22T18:50:00Z'
+        end_time (str): End time (ISO 8601).
+                        Example: '2026-04-22T18:51:00Z'
+        num_values (int): Number of values to read (default: unlimited)
+
+    Returns:
+        list[dict]: An array of values shaped
+            `{ "value": <value>, "timestamp": <timestamp>, "status": "Good" }`
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    node = client.get_node(node_id)
+    values = node.read_raw_history(
+        starttime=parse_iso_datetime(start_time),
+        endtime=parse_iso_datetime(end_time),
+        numvalues=num_values,
+    )
+    return [
+        {
+            "value": str(v.Value.Value),
+            "timestamp": str(v.SourceTimestamp),
+            "status": str(v.StatusCode.name),
+        }
+        for v in values
+    ]
+
+
+# Conditionally register the history tool based on server capability.
+if server_supports_history(SERVER_URL):
+    read_history_opcua_node = mcp.tool(description=DESC["read_history_opcua_node"])(
+        read_history_opcua_node
+    )
+
+
+# Tool: Read server-computed aggregates over a node's history.
+# Registered only when the server advertises aggregate functions, mirroring the
+# Node server's capability gating.
+_AGGREGATE_FUNCTIONS = server_aggregate_functions(SERVER_URL)
+
+
+def read_aggregate_opcua_node(
+    node_id: str,
+    ctx: Context,
+    start_time: str,
+    aggregate_function: str,
+    end_time: str | None = None,
+    processing_interval: float = 0,
+) -> list[dict]:
+    """
+    Calculate historical aggregates over a time range, in fixed-size intervals.
+
+    Parameters:
+        node_id (str): The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'.
+                       Example: 'ns=2;i=2'.
+        start_time (str): Beginning of the retrieval (ISO 8601).
+        aggregate_function (str): The specific formula, e.g. 'Average'.
+        end_time (str): End of the retrieval (ISO 8601, defaults to 'now').
+        processing_interval (float): Duration (ms) for each computed value. 0 asks
+                                     the server for a single value over the range.
+
+    Returns:
+        list[dict]: One entry per interval, shaped
+            `{ "value": <value>, "timestamp": <timestamp>, "status": <status> }`
+    """
+    # Re-probe rather than trusting the import-time snapshot: a server may gain or
+    # lose aggregate support while this process is running, and answering from a
+    # stale cache would report the wrong supported set.
+    aggregate_functions = server_aggregate_functions(SERVER_URL)
+    validate_aggregate_function(aggregate_function, aggregate_functions)
+
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    try:
+        details = ua.ReadProcessedDetails()
+        details.StartTime = parse_iso_datetime(start_time)
+        # UTC, not naive local time: `parse_iso_datetime` yields aware UTC, so a
+        # naive `datetime.now()` here would shift the window end by the host's UTC
+        # offset and pad the result with an empty bucket per interval in between.
+        details.EndTime = parse_iso_datetime(end_time) or datetime.now(timezone.utc)
+        details.ProcessingInterval = processing_interval
+        details.AggregateType = [aggregate_functions[aggregate_function]]
+
+        result = client.get_node(node_id).history_read(details)
+        if not result.StatusCode.is_good():
+            raise ValueError(f"Read aggregate failed with status: {result.StatusCode}")
+
+        return [
+            {
+                "value": str(v.Value.Value),
+                "timestamp": str(v.SourceTimestamp),
+                "status": str(v.StatusCode.name),
+            }
+            for v in result.HistoryData.DataValues
+        ]
+    except Exception as e:
+        raise ValueError(f"Failed to read node {node_id}: {e!s}") from e
+
+
+if _AGGREGATE_FUNCTIONS:
+    read_aggregate_opcua_node = mcp.tool(description=DESC["read_aggregate_opcua_node"])(
+        read_aggregate_opcua_node
+    )
+
+
+# Tool: Write a value to an OPC UA node
+@mcp.tool(description=DESC["write_opcua_node"])
+def write_opcua_node(node_id: str, value: str, ctx: Context) -> str:
+    """
+    Write a value to a specific OPC UA node.
+
+    Parameters:
+        node_id (str): The OPC UA node ID in the format 'ns=<namespace>;i=<identifier>'.
+                       Example: 'ns=2;i=3'.
+        value (str): The value to write to the node. Will be converted based on node type.
+
+    Returns:
+        str: A message indicating success or failure of the write operation.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    node = client.get_node(node_id)
+    try:
+        # Convert value based on the node's current type.
+        # Note: check bool before (int, float) because bool is a subclass of int.
+        current_value = node.get_value()
+        if isinstance(current_value, bool):
+            node.set_value(str(value).lower() in ["true", "1", "yes", "on"])
+        elif isinstance(current_value, (int, float)):
+            node.set_value(float(value))
+        else:
+            node.set_value(value)
+        return f"Successfully wrote {value} to node {node_id}"
+    except Exception as e:
+        return f"Error writing to node {node_id}: {e!s}"
+
+
+# Tool: Browse the children of a specific OPC UA node
+@mcp.tool(description=DESC["browse_opcua_node_children"])
+def browse_opcua_node_children(node_id: str, ctx: Context) -> str:
+    """
+    Browse the children of a specific OPC UA node.
+
+    Parameters:
+        node_id (str): The OPC UA node ID to browse (e.g., 'ns=0;i=85' for Objects folder).
+
+    Returns:
+        str: A string representation of a list of child nodes, including their
+             NodeId and BrowseName.
+             Returns an error message on failure.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    try:
+        node = client.get_node(node_id)
+        children = node.get_children()
+
+        children_info = []
+        for child in children:
+            try:
+                browse_name = child.get_browse_name()
+                children_info.append(
+                    {
+                        "node_id": child.nodeid.to_string(),
+                        "browse_name": f"{browse_name.NamespaceIndex}:{browse_name.Name}",
+                    }
+                )
+            except Exception as e:
+                children_info.append(
+                    {"node_id": child.nodeid.to_string(), "browse_name": f"Error getting name: {e}"}
+                )
+
+        # import json
+        # return json.dumps(children_info, indent=2)
+        return f"Children of {node_id}: {children_info!r}"
+
+    except Exception as e:
+        return f"Error Browse children of node {node_id}: {e!s}"
+
+
+# Tool: Call an OPC UA method
+@mcp.tool(description=DESC["call_opcua_method"])
+def call_opcua_method(
+    object_node_id: str, method_node_id: str, ctx: Context, arguments: list[Any] | None = None
+) -> str:
+    """
+    Call a method on a specific OPC UA object node.
+
+    Parameters:
+        object_node_id (str): The OPC UA node ID of the object that contains the method.
+                             Example: 'ns=2;i=1' for the Methods folder.
+        method_node_id (str): The OPC UA node ID of the method to call.
+                             Example: 'ns=2;i=2' for StartProduction method.
+        ctx (Context): The context for the request.
+        arguments (List[Any], optional): List of arguments to pass to the method.
+                                       Arguments will be converted to appropriate OPC UA variants.
+
+    Returns:
+        str: The result of the method call or an error message if the call fails.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    try:
+        # Get the object and method nodes
+        object_node = client.get_node(object_node_id)
+        method_node = client.get_node(method_node_id)
+
+        # Prepare arguments
+        method_args = []
+        if arguments:
+            for arg in arguments:
+                # Convert arguments to appropriate types
+                if isinstance(arg, str):
+                    # Try to convert string to appropriate type
+                    try:
+                        # Try float first
+                        method_args.append(float(arg))
+                    except ValueError:
+                        try:
+                            # Try int
+                            method_args.append(int(arg))
+                        except ValueError:
+                            # Keep as string
+                            method_args.append(arg)
+                else:
+                    method_args.append(arg)
+
+        # Call the method on the object node. python-opcua exposes call_method on Node
+        # (not Client), and a string methodid is treated as a child browse-name, so pass
+        # the resolved method Node to call it by node id.
+        result = object_node.call_method(method_node, *method_args)
+
+        return (
+            f"Method call successful. Object: {object_node_id}, "
+            f"Method: {method_node_id}, Result: {result}"
+        )
+
+    except Exception as e:
+        return f"Error calling method {method_node_id} on object {object_node_id}: {e!s}"
+
+
+# Tool: Read multiple OPC UA nodes
+@mcp.tool(description=DESC["read_multiple_opcua_nodes"])
+def read_multiple_opcua_nodes(node_ids: list[str], ctx: Context) -> str:
+    """
+    Read the values of multiple OPC UA nodes in a single request.
+
+    Parameters:
+        node_ids (List[str]): A list of OPC UA node IDs to read (e.g., ['ns=2;i=2', 'ns=2;i=3']).
+
+    Returns:
+        str: A string representation of a dictionary mapping node IDs to their
+             values, or an error message.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    try:
+        results = {}
+        for node_id in node_ids:
+            try:
+                node = client.get_node(node_id)
+                value = node.get_value()
+                results[node_id] = value
+            except Exception as e:
+                results[node_id] = f"Error: {e!s}"
+
+        return f"Multiple node read results: {results!r}"
+
+    except Exception as e:
+        return f"Error reading multiple nodes: {e!s}"
+
+
+# Tool: Write multiple OPC UA nodes
+@mcp.tool(description=DESC["write_multiple_opcua_nodes"])
+def write_multiple_opcua_nodes(nodes_to_write: list[dict[str, Any]], ctx: Context) -> str:
+    """
+    Write values to multiple OPC UA nodes in a single request.
+
+    Parameters:
+        nodes_to_write (List[Dict[str, Any]]): A list of dictionaries, where each dictionary
+                                               contains 'node_id' (str) and 'value' (Any).
+                                               The value will be wrapped in an OPC UA Variant.
+                                               Example: [{'node_id': 'ns=2;i=2', 'value': 10.5},
+                                                         {'node_id': 'ns=2;i=3', 'value': 'active'}]
+
+    Returns:
+        str: A message indicating the success or failure of the write operation.
+             Returns status codes for each write attempt.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    try:
+        results = []
+        for item in nodes_to_write:
+            node_id = item["node_id"]
+            value = item["value"]
+
+            try:
+                node = client.get_node(node_id)
+
+                # Convert value based on the node's current type.
+                # Note: check bool before (int, float) because bool is a subclass of int.
+                current_value = node.get_value()
+                if isinstance(current_value, bool):
+                    converted_value = str(value).lower() in ["true", "1", "yes", "on"]
+                elif isinstance(current_value, (int, float)):
+                    converted_value = float(value)
+                else:
+                    converted_value = str(value)
+
+                node.set_value(converted_value)
+                results.append({"node_id": node_id, "status": "Success"})
+
+            except Exception as e:
+                results.append({"node_id": node_id, "status": f"Error: {e!s}"})
+
+        return f"Write operation results: {results!r}"
+
+    except Exception as e:
+        return f"Error writing multiple nodes: {e!s}"
+
+
+# Tool: Get all variables information
+@mcp.tool(description=DESC["get_all_variables"])
+def get_all_variables(ctx: Context) -> str:
+    """
+    Get all available variables from the OPC UA server, excluding those under
+    the built-in 'Server' object.
+
+    Returns:
+        str: A string representation of all variables with their name, nodeid, object_id, value,
+             data_type, and description.
+    """
+    client = ctx.request_context.lifespan_context["opcua_client"]
+    variables_info = []
+
+    try:
+        objects_node = client.get_objects_node()
+
+        def search_variables(node):
+            try:
+                children = node.get_children()
+            except Exception:
+                return
+
+            for child in children:
+                try:
+                    node_class = child.get_node_class()
+                except Exception:
+                    continue
+
+                # Skip the entire "Server" subtree
+                try:
+                    child_browse_name = child.get_browse_name().Name
+                    if child_browse_name == "Server":
+                        continue
+                except Exception:
+                    continue
+
+                if node_class == NodeClass.Variable:
+                    browse_name = child_browse_name
+                    node_id = child.nodeid.to_string()
+
+                    try:
+                        parent_node = child.get_parent()
+                        object_id = parent_node.nodeid.to_string() if parent_node else "N/A"
+                    except Exception:
+                        object_id = "N/A"
+
+                    try:
+                        value = child.get_value()
+                    except Exception:
+                        value = None
+
+                    try:
+                        data_type = child.get_data_type().to_string()
+                    except Exception:
+                        data_type = ""
+
+                    try:
+                        desc = child.get_description().Text
+                    except Exception:
+                        desc = ""
+
+                    variables_info.append(
+                        {
+                            "name": browse_name,
+                            "nodeid": node_id,
+                            "object_id": object_id,
+                            "value": value,
+                            "data_type": data_type,
+                            "description": desc,
+                        }
+                    )
+                elif node_class == NodeClass.Object:
+                    # Recursively search children of this object,
+                    # unless it is the "Server" object
+                    search_variables(child)
+
+        search_variables(objects_node)
+
+        if variables_info:
+            result = f"Found {len(variables_info)} variables:\n"
+            for var in variables_info:
+                result += f"\n- Name: {var['name']}\n"
+                result += f"  NodeID: {var['nodeid']}\n"
+                result += f"  Object ID: {var['object_id']}\n"
+                result += f"  Value: {var['value']}\n"
+                result += f"  Data Type: {var['data_type']}\n"
+                result += f"  Description: {var['description']}\n"
+            return result
+        else:
+            return "No variables found in the OPC UA server."
+
+    except Exception as e:
+        return f"Error while finding variables: {e!s}"
+
+
+# Run the server
+def main() -> None:
+    """Entry point for the `opcua-mcp-server` console script."""
+    mcp.run(transport="stdio")