rei-lads-mcp

⚠️ v0.1.0-preview — early-feedback release. NOT for production use. API is not stable before v1.0.0. Breaking changes may land in any 0.x version. X.509 certificate authentication is not supported in the 0.1.x line (username/password only). See ROADMAP.md for Phase 5 items.

An MCP server that exposes OPC UA LADS (Laboratory Agnostic Device Standard) instruments to LLM agents with two Rei-native disciplines baked in:

1. Approval-gated execution — every state-changing tool validates its operation name against a server-declared enum (LADS state-machine methods, program templates). Arbitrary strings are rejected at the MCP boundary, before any network call fires.

2. Witnessed provenance — every state-changing call emits a SHA-256 record (initiator, node, operation, params, samples, timestamp) that is persisted to a local append-only JSONL and retrievable by prefix.

Modeled on the LADS reference implementations at opcua-lads and grounded in the Rei / D-FUMT approval-gate + witnessed by design.

Install

Requires Python 3.12+.

python -m venv .venv
./.venv/bin/pip install -r requirements.txt   # Linux/macOS
./.venv/Scripts/pip install -r requirements.txt   # Windows

Related MCP server: SiLA MCP Server

Quick start

Boot a LADS reference server (for example, lads-viscometer from opcua-lads/lads-server-collection), then run:

python server.py

This starts a stdio MCP server. Point any MCP client at it.

Programmatic sanity check (no MCP client required):

python test_tools_list.py    # 15 tools registered, schemas generated
python test_live_phase4.py   # end-to-end against a running LADS server on
                             # opc.tcp://localhost:4840

Tools (15)

Connection

• lads_connect(alias, server_url, user?, password?, wait_timeout_s?, cert_path?, key_path?)

• lads_register_alias(alias, server_url, description?, user?, password?)

• lads_list_aliases()

• lads_connect_by_alias(alias, wait_timeout_s?)

Discovery (read-only)

• lads_list_devices(alias)

• lads_get_functional_units(alias, device_index)

• lads_get_sensor_value(alias, device_index, unit_index, function_index)

• lads_get_state(alias, device_index, unit_index)

• lads_get_state_machine_methods(alias, device_index, unit_index)

• lads_list_program_templates(alias, device_index, unit_index)

• lads_list_results(alias, device_index, unit_index)

State-changing (emit witness records)

• lads_call_state_machine_method(alias, device_index, unit_index, method_name) — validates method_name against server-declared inventory

• lads_start_program(alias, device_index, unit_index, template_name, properties?, samples?, supervisory_job_id?, supervisory_task_id?) — validates template_name against ProgramManager templates

Witness retrieval

• lads_list_witness_recent(limit?)

• lads_show_witness(sha256_prefix) — min 4 characters

Approval-gate demo

lads_call_state_machine_method(alias, 0, 0, "Start")
# -> {invocation: "queued (async)", witness_hash: "..."}

lads_call_state_machine_method(alias, 0, 0, "ArbitraryExec")
# -> {error: "method 'ArbitraryExec' not declared by this state machine",
#     valid_methods: ["Start", "StartProgram", "Stop"]}

The rejection happens at the MCP tool boundary — no OPC UA call is fired for an operation name that the LADS server did not declare. Same pattern for lads_start_program(template_name=...).

Witnessed provenance

Every state-changing tool call emits a record like:

{
  "initiator": "mcp-caller",
  "node_alias": "viscometer",
  "server_url": "opc.tcp://localhost:4840",
  "device_browse_name": "myViscometer",
  "unit_browse_name": "ViscometerUnit",
  "operation": "StartProgram",
  "template_name": "Analytical Method A (30rpm)",
  "params": {"Speed": "30", "Duration": "60"},
  "sample_context": [{"ContainerId": "vial-01", "SampleId": "sample-a",
                      "Position": "A1", "CustomData": "phase4-test"}],
  "timestamp_utc": "2026-08-26T00:23:54.333266+00:00",
  "phase": "accepted",
  "sha256_hex": "174b5e1498a5d0cca55ce9291adf95f612161ed590b839258e700e994cba25ae"
}

Persisted to ~/.rei-lads/witness/YYYY-MM.jsonl (env override REI_LADS_WITNESS_DIR). Retrievable via the two lads_*_witness_* tools by SHA-256 prefix.

Related work

• opcua-lads/lads-server-collection — LADS reference OPC UA servers (Viscometer / pH-Meter / Balance / Freezer / FT-NIR)

• opcua-lads/lads-client-py — the Python client this bridge wraps

• TECTOS-JP/lab-visa-mcp — sibling MCP for PyVISA-controlled instruments

• fc0web/rei-lang — the Rei language project this bridge implements the discipline of

• Rei-Certified program (draft) — the compliance surface this bridge is a candidate G1 pilot for

Preview status

• Phase 1-4 spike complete — 15 tools, L2 and L3 both green against a live LADS viscometer sim

• Phase 4 fixes that are already in code: banner silencing at import, Connection.initialized polling, QualifiedName unwrap

• Phase 5 is not yet implemented — see ROADMAP.md

• API stability: not before v1.0.0 — expect breaking changes in 0.x

Full spike history is preserved in SPIKE-HISTORY.md for the record.

License

MIT — see LICENSE. LADS ecosystem convention.

Contributing

See CONTRIBUTING.md. External contributors will require a signed CLA once the Rei-project CLA is finalized.