# opcua-twin-gateway

> 数字管道的建筑师 · 第六块积木：把**标准 OPC UA 工业协议**接入 MCP 生态
> 前五块：workflow-templates / digital-twin-mcp / factory-twin-viz / workflow-mcp / pdf2voice

OPC UA（IEC 62541）是工业 4.0 的事实标准协议。本项目用**真实 OPC UA 协议**（asyncua）搭了一条完整的"模拟 PLC → 标准协议 → MCP 工具"数据管道：

```
[OPC UA 模拟服务器] ──OPC UA 协议──▶ [opcua-twin-gateway MCP] ──MCP──▶ [WorkBuddy / Claude Desktop / Cursor]
```

> 为什么真实协议：digital-twin-mcp 用的是"模拟 PLC 接口"，而本项目直接走 OPC UA 标准——
> 换掉 `ots_server.py` 指向任何真实 OPC UA 服务器（西门子/倍福/OPC UA 网关），网关零改动。

## 组件

| 文件 | 作用 |
|------|------|
| `ots_server.py` | OPC UA 工厂模拟服务器：6 台设备、随机游走漂移、节点可写 |
| `gateway.py` | MCP Server：asyncua Client 通过标准协议读写节点 |
| `demo_client.py` | 直连演示：不经过 MCP，用原生 OPC UA 协议读数据 |

## MCP 工具

| 工具 | 说明 |
|------|------|
| `list_nodes` | 列出全部设备节点（设备/指标/node_id/是否可写） |
| `read_node` | 读单个节点实时值 |
| `read_all` | 读全量快照（类比 digital-twin-mcp 的 get_scene_snapshot） |
| `set_node_value` | 写入控制值（仅可写节点，为控制闭环铺路） |

## 快速开始

```bash
pip install -r requirements.txt        # asyncua + fastmcp

# 终端 1：启动 OPC UA 模拟服务器
python ots_server.py

# 终端 2：原生 OPC UA 直连演示（不经过 MCP）
python demo_client.py
python demo_client.py im-01 temperature
python demo_client.py --write im-01 temperature 300

# 终端 2：MCP 自检（进程内）
python examples/check_gateway.py

# MCP Server（stdio，供 WorkBuddy 等客户端接入）
python gateway.py
```

## 与 digital-twin-mcp 的衔接

`digital-twin-mcp` 的 `BasePLCDriver` 是模拟驱动；本项目的 `gateway.py` 是**真实 OPC UA 驱动**的实现示例。
把网关的 `read_all()` 输出映射到 digital-twin-mcp 的 `get_scene_snapshot` 格式，
factory-twin-viz 就能直接渲染真实协议数据——模拟与真实协议平滑切换。

## 接入 WorkBuddy

合并 `examples/workbuddy_mcp.json` 到 `~/.workbuddy/mcp.json`，在连接器管理页「信任」后，
对话中可直接说"读一下注塑机温度"。

## 许可

MIT License