deltav-edge-mcp-server
by smithaldon1
README.md
# 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
```text
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
```text
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
```bash
npm install
```
## Running The Server
### Stdio transport
Default MCP mode:
```bash
npm run dev
```
Production-style local run from compiled output:
```bash
npm run build
npm start
```
### Streamable HTTP transport
Set:
```env
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:
```bash
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:
```bash
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:
```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_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](/Users/aldonsmith/Documents/Programming/deltav-mcp/.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:
```env
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:
```env
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:
```env
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:
```env
MOCK_DELTAV_EDGE_HOST=0.0.0.0
MOCK_DELTAV_EDGE_PORT=8080
MOCK_DELTAV_EDGE_BASE_PATH=/edge/api/v1
```
OPC UA settings:
```env
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:
```toml
[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](/Users/aldonsmith/Documents/Programming/deltav-mcp/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](/Users/aldonsmith/Documents/Programming/deltav-mcp/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:
```bash
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
```bash
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:
```bash
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
```json
{
"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](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/ARCHITECTURE.md)
- [docs/SAFETY_MODEL.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/SAFETY_MODEL.md)
- [docs/TOOLS.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/TOOLS.md)
- [docs/DELTAV_EDGE_SETUP.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/DELTAV_EDGE_SETUP.md)
- [docs/ENGINEERING_WORKFLOWS.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/ENGINEERING_WORKFLOWS.md)
- [docs/MOCK_DELTAV_EDGE.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/MOCK_DELTAV_EDGE.md)
- [docs/DIAGRAMS.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/DIAGRAMS.md)
- [docs/PATTERN_LIBRARY.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/docs/PATTERN_LIBRARY.md)
- [docs/EXAMPLE_PROMPTS.md](/Users/aldonsmith/Documents/Programming/deltav-mcp/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.
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo recent community issues