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

Related MCP server: mcp-sqlserver-readonly

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.