rei-lads-mcp

⚠️ v0.1.0-preview — 早期反馈版本。不适用于生产环境。 v1.0.0 之前 API 不稳定。任何 0.x 版本都可能引入破坏性变更。 0.1.x 系列不支持 X.509 证书认证 （仅支持用户名/密码）。Phase 5 事项请参见 ROADMAP.md。

一个将 OPC UA LADS（Laboratory Agnostic Device Standard，实验室无关设备标准）仪器暴露给 LLM 代理的 MCP 服务器，内置了两项 Rei 原生规范：

1. 审批门控执行 — 每个改变状态的工具都会根据服务器声明的枚举（LADS 状态机方法、程序模板）校验其操作名称。任意字符串都会在 MCP 边界被拒绝，不会触发任何网络调用。

2. 见证溯源 — 每次改变状态的调用都会生成一条 SHA-256 记录（发起者、节点、操作、参数、样本、时间戳），该记录持久化到本地追加式 JSONL 文件中，并可通过前缀检索。

以 opcua-lads 的 LADS 参考实现为模型，并基于 Rei / D-FUMT 的审批门控 + witnessed by 设计。

安装

需要 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: opcua-mcp

快速开始

启动一个 LADS 参考服务器（例如来自 opcua-lads/lads-server-collection 的 lads-viscometer），然后运行：

python server.py

这将启动一个 stdio MCP 服务器。将任意 MCP 客户端指向它即可。

编程式健全性检查（无需 MCP 客户端）：

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

工具（15 个）

连接

• 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?)

发现（只读）

• 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)

状态改变（生成见证记录）

• lads_call_state_machine_method(alias, device_index, unit_index, method_name) — 根据服务器声明的清单校验 method_name

• lads_start_program(alias, device_index, unit_index, template_name, properties?, samples?, supervisory_job_id?, supervisory_task_id?) — 根据 ProgramManager 模板校验 template_name

见证检索

• lads_list_witness_recent(limit?)

• lads_show_witness(sha256_prefix) — 最少 4 个字符

审批门控演示

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"]}

拒绝发生在 MCP 工具边界 — 对于 LADS 服务器未声明的操作名称，不会发出任何 OPC UA 调用。lads_start_program(template_name=...) 采用相同的模式。

见证溯源

每次改变状态的工具调用都会生成如下记录：

{
  "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"
}

持久化到 ~/.rei-lads/witness/YYYY-MM.jsonl（可通过环境变量 REI_LADS_WITNESS_DIR 覆盖）。可通过两个 lads_*_witness_* 工具按 SHA-256 前缀检索。

相关工作

• opcua-lads/lads-server-collection — LADS 参考 OPC UA 服务器（Viscometer / pH-Meter / Balance / Freezer / FT-NIR）

• opcua-lads/lads-client-py — 本桥接所封装的 Python 客户端

• TECTOS-JP/lab-visa-mcp — 面向 PyVISA 控制仪器的姊妹 MCP

• fc0web/rei-lang — 本桥接所实现其规范体系的 Rei 语言项目

• Rei-Certified 计划（草案）— 本桥接作为 G1 试点候选所面向的合规面

预览状态

• Phase 1-4 技术预研完成 — 15 个工具，L2 和 L3 均针对实时 LADS 粘度计模拟器通过

• 已在代码中的 Phase 4 修复：导入时横幅静默、Connection.initialized 轮询、QualifiedName 解包

• Phase 5 尚未实现 — 参见 ROADMAP.md

• API 稳定性：v1.0.0 之前不稳定 — 0.x 版本中预计会有破坏性变更

完整的技术预研历史保留在 SPIKE-HISTORY.md 中，以备查证。

许可证

MIT — 参见 LICENSE。LADS 生态系统的惯例。

贡献

参见 CONTRIBUTING.md。一旦 Rei 项目的 CLA 最终确定，外部贡献者将需要签署 CLA。