digital-twin-mcp

把数字孪生场景中的设备数据能力打包成 MCP 工具——任何 MCP 客户端（WorkBuddy、Claude Desktop、Cursor 等）都能直接查询设备状态、读取实时指标、拉取时序数据、检查告警。

数字管道的建筑师 · 第二块积木：设备监控管道 第一块积木：https://github.com/xici001/workflow-templates（AI 自动化工作流模板）

它能做什么

工具	说明
list_devices	列出场景内所有设备（类型 / 位置）
get_device_metrics	读取设备实时指标（模拟 PLC 轮询）
get_metric_history	读取某指标最近时序数据（供趋势图 / 3D 可视化）
set_device_value	写入设备参数（模拟 PLC 写值 / 故障注入测试）
check_alerts	阈值告警检查（warning / critical 分级）

资源	说明
device://{id}/profile	设备台账：元数据 + 指标量程与告警阈值
scene://layout	3D 场景布局：设备世界坐标（Three.js / Unity 直接叠加）

提示词	说明
device_health_report	生成指定设备的健康报告

架构

MCP 客户端（WorkBuddy / Claude Desktop / ...）
        │  stdio 或 streamable-http
┌───────▼───────────────┐
│  server.py (FastMCP)  │  ← 工具 / 资源 / 提示词定义
└───────┬───────────────┘
        │
┌───────▼───────────────┐
│  alerts.py             │  告警规则引擎（阈值分级）
│  device_registry.py    │  设备台账 + 指标配置 + 3D 坐标
│  simulator.py          │  PLC 数据驱动（BasePLCDriver 接口）
└───────────────────────┘

• v0 数据源为模拟 PLC 驱动（固定随机种子、可复现；注塑机温度故意贴近阈值上漂，方便演示告警升级）。
• 接真实设备时继承 BasePLCDriver 实现 read_metrics / write_value（OPC-UA / Modbus / 网关 API 皆可），Server 层零改动。

快速开始

pip install -e .
# 方式一：stdio 传输（MCP 客户端默认）
python -m digital_twin_mcp.server
# 方式二：streamable-http 传输
python -m digital_twin_mcp.server --transport streamable-http

端到端测试（启动 server 子进程并通过 stdio 协议调用）：

python examples/client_test.py

接入 WorkBuddy

把 examples/workbuddy_mcp.json 的内容合并到 C:\Users\33033\.workbuddy\mcp.json 的 mcpServers 中，然后在连接器管理页右上角的自定义连接器入口对 digital-twin-mcp 点击「信任」启用。

与 workflow-templates 的关系

同一个"数字管道"品牌下的两块积木：

• workflow-templates：把脑力劳动（财报分析等）打包成工作流
• digital-twin-mcp：把设备数据能力（数字孪生 / PLC）打包成 MCP 工具

两者未来可组合：工作流模板的「设备健康报告」等模板，可直接调用本 MCP 的工具获取真实数据。

路线图

• v0.1：模拟 PLC + 5 个工具 + 2 个资源 + 1 个提示词（当前）
• v0.2：OPC-UA 真实接入、时序数据落库（SQLite/InfluxDB）、WebSocket 推送
• v0.3：3D 场景联动（场景布局资源对接 Three.js 渲染）、多工厂实例

许可

MIT License