deltav-edge-mcp-server

Safety-conscious TypeScript MCP server for Emerson DeltaV Edge read access, engineering investigation workflows, and offline engineering artifact generation.

Safety First

This repository does not support autonomous live control of a DeltaV system.

Prohibited actions include:

• writing values to live controllers
• changing live setpoints
• forcing I/O
• acknowledging or disabling alarms
• bypassing interlocks
• downloading modules to production
• modifying SIS logic
• pushing generated logic to production

Supported operating modes:

• READ_ONLY
• SANDBOX_ENGINEERING

SANDBOX_ENGINEERING enables offline artifact generation only. It is not a production write mode.

Supported data sources:

• EDGE_REST
• MOCK_EDGE_REST
• OPCUA

What The Server Includes

• DeltaV Edge authentication status checks
• hierarchy and graph search
• node context lookup
• history retrieval with summary statistics
• alarms and events retrieval
• batch event retrieval and batch-analysis helpers
• abnormal-event investigation helpers
• offline engineering generation tools
• offline review and validation tools
• Mermaid diagram generators
• local engineering package generation
• registered MCP prompts for engineering workflows
• registered MCP resources for site standards and templates
• a development-only mock DeltaV Edge REST API and browser UI
• datasource abstraction for Edge REST, mock REST, and OPC UA selection
• read-only node-opcua integration plus a development-only mock OPC UA server

Architecture

AI Client -> MCP Server -> DeltaV Edge REST API -> DeltaV Edge Environment -> DeltaV system replica/context
                                  |
                                  +-> Local site standards, prompts, resources, generated packages, and pattern library

The server talks to the DeltaV Edge REST boundary, not directly to live controllers.

Repository Layout

src/
  audit/
  config/
  deltav/
  engineering/
  prompts/
  resources/
  safety/
  server/
  tools/
  utils/
mock-deltav-edge/
  src/
  ui/
site-standards/
mock-opcua-server/
tests/
docs/

Requirements

• Node.js >=20.11.0
• npm

Install

npm install

Running The Server

Stdio transport

Default MCP mode:

npm run dev

Production-style local run from compiled output:

npm run build
npm start

Streamable HTTP transport

Set:

DELTAV_HTTP_ENABLED=true
DELTAV_HTTP_HOST=0.0.0.0
DELTAV_HTTP_PORT=3000
DELTAV_HTTP_PATH=/mcp
DELTAV_HTTP_STATELESS=true

Then run the server and use:

• MCP endpoint: http://localhost:3000/mcp
• health endpoint: http://localhost:3000/healthz

DELTAV_HTTP_STATELESS=false enables session IDs via the SDK transport.

Mock DeltaV Edge

Run the local simulated API and UI:

npm run dev:mock

Endpoints:

• mock API health: http://localhost:8080/health
• mock UI: http://localhost:8080/
• default mock API base path: http://localhost:8080/edge/api/v1

The mock is for development, testing, demos, and CI only. It is not a certified DeltaV Edge emulator.

Mock OPC UA

Run the local simulated OPC UA server:

npm run dev:mock-opcua

Default endpoint:

• opc.tcp://localhost:4840/UA/DeltaVMock

The mock server supports local endpoint discovery, browse, reads, and bounded monitored-item capture windows. It is for development, testing, demos, and CI only.

Quick Start For Mock-Backed MCP

Use mock-oriented settings like:

DELTAV_DATA_SOURCE=MOCK_EDGE_REST
DELTAV_EDGE_BASE_URL=http://localhost:8080/edge/
DELTAV_EDGE_USERNAME=demo
DELTAV_EDGE_PASSWORD=demo
DELTAV_EDGE_VERIFY_TLS=false
DELTAV_MCP_MODE=READ_ONLY
DELTAV_USE_MOCK=true
DELTAV_EDGE_ENDPOINT_AUTH_TOKEN=/api/v1/Login/GetAuthToken/profile
DELTAV_EDGE_ENDPOINT_GRAPH_COLLECTION=/api/v1/graph
DELTAV_EDGE_ENDPOINT_GRAPH_ENTITY=/api/v1/graph/{entityId}
DELTAV_EDGE_ENDPOINT_HISTORY_COLLECTION=/api/v1/history
DELTAV_EDGE_ENDPOINT_HISTORY_BY_ID=/api/v1/history/{entityId}
DELTAV_EDGE_ENDPOINT_ALARMS_EVENTS=/api/v1/ae
DELTAV_EDGE_ENDPOINT_BATCH_EVENTS=/api/v1/batchevent
DELTAV_AUDIT_LOG_PATH=./logs/audit.log
DELTAV_PACKAGE_OUTPUT_DIR=./generated-packages
DELTAV_HTTP_ENABLED=false

The checked-in .env.example shows the full variable set. For mock mode, DELTAV_USE_MOCK=true and the endpoint overrides are the important switches.

Environment Variables

Core connection and mode settings:

DELTAV_DATA_SOURCE=MOCK_EDGE_REST
DELTAV_EDGE_BASE_URL=http://localhost:8080/edge/
DELTAV_EDGE_USERNAME=
DELTAV_EDGE_PASSWORD=
DELTAV_EDGE_VERIFY_TLS=true
DELTAV_USE_MOCK=false
DELTAV_MCP_MODE=READ_ONLY
DELTAV_ALLOWED_AREAS=
DELTAV_ALLOWED_ENTITIES=
DELTAV_AUDIT_LOG_PATH=./logs/audit.log
DELTAV_PACKAGE_OUTPUT_DIR=./generated-packages

Endpoint-path overrides:

DELTAV_EDGE_ENDPOINT_AUTH_TOKEN=/connect/token
DELTAV_EDGE_ENDPOINT_GRAPH_COLLECTION=/api/graph/search
DELTAV_EDGE_ENDPOINT_GRAPH_ENTITY=/api/graph/entities/{entityId}
DELTAV_EDGE_ENDPOINT_HISTORY_COLLECTION=/api/history
DELTAV_EDGE_ENDPOINT_HISTORY_BY_ID=/api/history/{entityId}
DELTAV_EDGE_ENDPOINT_ALARMS_EVENTS=/api/ae
DELTAV_EDGE_ENDPOINT_BATCH_EVENTS=/api/batchevent

HTTP transport:

DELTAV_HTTP_ENABLED=false
DELTAV_HTTP_HOST=0.0.0.0
DELTAV_HTTP_PORT=3000
DELTAV_HTTP_PATH=/mcp
DELTAV_HTTP_STATELESS=true

Mock service settings:

MOCK_DELTAV_EDGE_HOST=0.0.0.0
MOCK_DELTAV_EDGE_PORT=8080
MOCK_DELTAV_EDGE_BASE_PATH=/edge/api/v1

OPC UA settings:

DELTAV_OPCUA_ENDPOINT_URL=opc.tcp://localhost:4840
DELTAV_OPCUA_SECURITY_MODE=None
DELTAV_OPCUA_SECURITY_POLICY=None
DELTAV_OPCUA_USERNAME=
DELTAV_OPCUA_PASSWORD=
DELTAV_OPCUA_APPLICATION_NAME=deltav-engineering-mcp-server
DELTAV_OPCUA_CERT_DIR=./certs/opcua
DELTAV_OPCUA_TRUST_UNKNOWN_CERTIFICATES=false
DELTAV_OPCUA_SESSION_TIMEOUT_MS=60000
DELTAV_OPCUA_REQUEST_TIMEOUT_MS=30000
DELTAV_OPCUA_MAX_NODES_PER_READ=100
DELTAV_OPCUA_ENABLE_SUBSCRIPTIONS=true
DELTAV_OPCUA_ENABLE_WRITES=false
DELTAV_OPCUA_NODE_MAP_PATH=./config/opcua-node-map.json

Configuration is validated at startup. Package output and audit log paths must resolve inside the repository working directory.

Codex MCP Configuration

Example stdio registration:

[mcp_servers.deltav_edge]
command = "node"
args = ["dist/index.js", "--transport", "stdio"]
cwd = "/absolute/path/to/deltav-edge-mcp-server"
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

[mcp_servers.deltav_edge.env]
DELTAV_DATA_SOURCE = "MOCK_EDGE_REST"
DELTAV_EDGE_BASE_URL = "http://localhost:8080/edge/"
DELTAV_EDGE_USERNAME = "demo"
DELTAV_EDGE_PASSWORD = "demo"
DELTAV_EDGE_VERIFY_TLS = "false"
DELTAV_USE_MOCK = "true"
DELTAV_MCP_MODE = "READ_ONLY"
DELTAV_AUDIT_LOG_PATH = "./logs/audit.log"
DELTAV_PACKAGE_OUTPUT_DIR = "./generated-packages"

Auth: Unsupported is normal for a local stdio MCP server. If Codex shows Tools: (none), check build output, cwd, stdout logging, and the troubleshooting guide in docs/TROUBLESHOOTING.md.

OPC UA Status

The repository now includes a working read-only OPC UA client path, dedicated OPC UA MCP tools, a checked-in logical NodeId map, and a local mock-opcua-server/ workspace. The implementation remains conservative:

• no OPC UA writes
• no mutating method calls
• no alarm acknowledgement
• bounded sampling and monitoring windows only
• no claim that sampled windows are historian-backed history

Tool Surface

Core DeltaV read tools:

• deltav_auth_status
• deltav_search_graph
• deltav_get_node_context
• deltav_get_history
• deltav_get_alarms_events

Investigation tools:

• deltav_get_trend_pack
• deltav_generate_event_timeline
• deltav_correlate_alarms_with_history
• deltav_find_first_out
• deltav_find_repeating_alarms
• deltav_find_chattering_alarms
• deltav_summarize_abnormal_event
• deltav_compare_before_after_change

Batch tools:

• deltav_search_batches
• deltav_get_batch_timeline
• deltav_compare_batches
• deltav_find_batch_deviation_window
• deltav_summarize_phase_failures
• generate_phase_logic

Engineering generation tools:

• generate_control_narrative
• generate_control_module_design
• generate_alarm_list
• generate_interlock_matrix
• generate_test_protocol
• create_engineering_change_package

Review and validation tools:

• review_control_narrative
• review_module_design
• review_alarm_list
• review_interlock_matrix
• review_test_protocol
• identify_missing_failure_modes
• identify_missing_operator_actions
• identify_unsafe_assumptions
• validate_control_strategy

Pattern and diagram tools:

• engineering_list_patterns
• engineering_get_pattern
• generate_module_relationship_diagram
• generate_cause_effect_diagram
• generate_sequence_logic_diagram
• generate_mode_state_diagram
• generate_batch_phase_diagram
• generate_alarm_response_diagram

OPC UA tools:

• opcua_discover_endpoints
• opcua_test_connection
• opcua_get_namespace_array
• opcua_get_server_status
• opcua_browse_node
• opcua_read_node
• opcua_read_nodes
• opcua_translate_path
• opcua_sample_nodes_for_window
• opcua_monitor_nodes_for_window

See docs/TOOLS.md for details.

Prompts And Resources

Registered prompts:

• investigate_abnormal_event
• review_control_module_design
• generate_pump_control_strategy
• generate_pid_loop_design
• generate_alarm_rationalization
• generate_batch_phase_design
• generate_fat_sat_protocol
• generate_moc_package
• review_interlock_matrix
• compare_strategy_to_site_standard

Registered resources:

• deltav://standards/naming-conventions
• deltav://standards/alarm-philosophy
• deltav://standards/module-templates/pid-loop
• deltav://standards/module-templates/motor
• deltav://standards/module-templates/valve
• deltav://templates/control-narrative
• deltav://templates/fat-sat
• deltav://templates/moc
• deltav://templates/validation

Audit, Guardrails, And Access Control

• Every tool call writes an audit record with sanitized input, status, mode, and optional session ID.
• Natural-language live-write requests are refused with a structured safe alternative.
• DELTAV_ALLOWED_AREAS and DELTAV_ALLOWED_ENTITIES enforce fail-closed allowlists when configured.
• Generated packages are written only under DELTAV_PACKAGE_OUTPUT_DIR.

Docker Compose

Start the full local stack:

docker compose up --build

Services:

• REST-backed MCP server on http://localhost:3000/mcp
• OPC UA-backed MCP server on http://localhost:3101/mcp
• mock API on http://localhost:8080/health
• mock UI on http://localhost:8080/
• mock OPC UA server on opc.tcp://localhost:4840/UA/DeltaVMock

The mock UI proxies tool calls explicitly to both MCP services:

• REST proxy: /api/mcp/rest/tools/list and /api/mcp/rest/tools/call
• OPC UA proxy: /api/mcp/opcua/tools/list and /api/mcp/opcua/tools/call

The generic /api/mcp/tools/* routes remain pointed at the OPC UA service for backwards compatibility with the current console defaults.

Development Scripts

npm run dev
npm run dev:mock
npm run build
npm run build:mock
npm run build:mock-ui
npm test
npm run lint

Testing

Primary repo checks:

npm test
npm run build
npm run lint

The test suite covers configuration, client request construction, mock-backed MCP flows, access control, guardrails, validation, package writing, and audit redaction.

Example MCP Client Config

{
  "mcpServers": {
    "deltav-edge": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/deltav-mcp",
      "env": {
        "DELTAV_EDGE_BASE_URL": "http://localhost:8080/edge/",
        "DELTAV_EDGE_USERNAME": "demo",
        "DELTAV_EDGE_PASSWORD": "demo",
        "DELTAV_EDGE_VERIFY_TLS": "false",
        "DELTAV_USE_MOCK": "true",
        "DELTAV_EDGE_ENDPOINT_AUTH_TOKEN": "/api/v1/Login/GetAuthToken/profile",
        "DELTAV_EDGE_ENDPOINT_GRAPH_COLLECTION": "/api/v1/graph",
        "DELTAV_EDGE_ENDPOINT_GRAPH_ENTITY": "/api/v1/graph/{entityId}",
        "DELTAV_EDGE_ENDPOINT_HISTORY_COLLECTION": "/api/v1/history",
        "DELTAV_EDGE_ENDPOINT_HISTORY_BY_ID": "/api/v1/history/{entityId}",
        "DELTAV_EDGE_ENDPOINT_ALARMS_EVENTS": "/api/v1/ae",
        "DELTAV_EDGE_ENDPOINT_BATCH_EVENTS": "/api/v1/batchevent",
        "DELTAV_MCP_MODE": "READ_ONLY"
      }
    }
  }
}

Documentation

• docs/ARCHITECTURE.md
• docs/SAFETY_MODEL.md
• docs/TOOLS.md
• docs/DELTAV_EDGE_SETUP.md
• docs/ENGINEERING_WORKFLOWS.md
• docs/MOCK_DELTAV_EDGE.md
• docs/DIAGRAMS.md
• docs/PATTERN_LIBRARY.md
• docs/EXAMPLE_PROMPTS.md

Known Limitations

• Real DeltaV Edge routes and payloads must be verified against installed site documentation.
• The mock server is a development aid, not a plant-validated emulator.
• Investigation outputs summarize evidence but do not prove causation.
• Generated artifacts, diagrams, reviews, and validation outputs remain proposed engineering material until qualified human review and site change control are complete.