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
