plctap

中文 | English

Agent 的 PLC 驱动层 — 让 Claude / Codex / Cursor 直接连接、读写、诊断 Modbus TCP / Modbus RTU over TCP / FINS / MELSEC / Siemens S7comm / IEC 60870-5-104 设备的 MCP Server。

CI PyPI MCP Registry License: MIT

demo

状态: v0.5.2 (协议自动识别 + 透明代理 + 故障注入监听 + 六协议端点接入, 五端点可写 (IEC 104 仅读), IEC 104 经 lib60870 官方实现双向交叉验证)。

PLCTAP_ALLOW_WRITE=true 后六端点中五个可写 (modbus_rtu 与 modbus 同轨同语义; iec104 仅读):

所有写/发送动作逐帧写入审计日志 (发送前留痕, 失败也留)。

六个端点的寻址模型与常用参数 (接入前先对表; 工具内 list_protocols 亦可动态获取):

datatype 支持 uint16 / int16 / float32 / int32; byteorder 仅影响 float32 的寄存器对顺序 (big=ABCD, little=DCBA)。datatype 缺省时返回全部常见类型 ×ばつ 字序的多解释, 字序存疑时直接比对。

示例调用 (客户端中按参数填写):

plc_read(protocol="modbus", host="10.0.0.10", port=502, address=0, count=2, datatype="float32", byteorder="big")
plc_read(protocol="modbus_rtu", host="192.168.1.50", port=8899, unit=2, address=100, count=10)
plc_read(protocol="fins", host="10.0.0.30", port=9600, address=100, count=10, options={"area": "DM"})
plc_read(protocol="melsec", host="10.0.0.40", port=44818, address=100, count=10, options={"device": "D"})
plc_read(protocol="s7", host="10.0.0.20", port=102, address=0, count=4, datatype="float32", options={"area": "DB", "db_number": 1})
plc_read(protocol="iec104", host="10.0.0.60", port=2404, address=1, count=5, options={"ca": 1})

modbus 与 modbus_rtu 怎么选: 网关/上位机已封装 MBAP 头 (标准 Modbus TCP) → modbus; 串口服务器或网关工作在 RTU 透传模式 (TCP 上是裸 RTU 帧) → modbus_rtu。

1. detect_device(host=...) — 不知道对面是什么: 并发探测标准端口, 按响应指纹判定协议/端口/置信度, 返回可直接执行的 plc_read 建议 (全程只读)。
2. probe_device(protocol, host, port) — 连通性确认; 失败时四类分层归因 (connection_refused / timeout / connected_but_no_reply / exception_response), 直接告诉您该查网络路由还是查协议配置 (IEC 104 为 STARTDT+TESTFR 握手探测)。
3. plc_read(...) — 按「协议速查」读数, 与上位机显示或预期值比对。
4. 读数不对 / 通信故障 → 抓包帧喂 parse_frame / validate_frame 做结构化解析与规范校验; 日志文本喂 diagnose 得到带证据链的结构化候选结论。
5. 要看上位机 ↔ PLC 全部交互 → start_proxy 透明代理 (上位机改指向代理即可, 免 Wireshark); 设备只能当 client 主动外连 → start_listener 假 server 钓帧, 支持 inject_errors 故障注入档做上位机容错回归。

uvx plctap # 或 pipx install plctap

已收录于 MCP 官方 Registry: io.github.ymxc152/plctap (支持按名称检索与安装的客户端可直接发现本服务)。

{
 "mcpServers": {
 "plctap": {
 "command": "uvx",
 "args": ["plctap"],
 "env": { "PLCTAP_ALLOW_WRITE": "false" }
 }
 }
}

本地开发 (仓库检出路径):

{
 "mcpServers": {
 "plctap": {
 "command": "uv",
 "args": ["--directory", "C:/path/to/plctap", "run", "plctap"]
 }
 }
}

[mcp_servers.plctap]
command = "uvx"
args = ["plctap"]
[mcp_servers.plctap.env]
PLCTAP_ALLOW_WRITE = "false" # 写闸门默认关闭
PLCTAP_DEFAULT_TIMEOUT_MS = "2000"

• 写操作默认完全不注册; 显式 PLCTAP_ALLOW_WRITE=true 才启用。
• 所有写/发送动作逐条写入 JSONL 审计日志 (~/.plctap/audit.jsonl, 不可关)。
• 发送类调用请配合客户端审批弹窗使用 (用户可见目标 IP 与完整帧)。
• 审计日志样例: {"ts":"2026-09-04T01:20:33+0800","tool":"plc_write","target":"modbus://127.0.0.1:15020 unit=1","frame_hex":"0002000000060106000104d2","caller":"mcp"}

uv sync --extra eval --group e2e
uv run pytest -q # 单测 (codec/适配器/诊断/监听) + 跨厂商 e2e + MCP 冒烟
uv run plctap # 本地启动 stdio server

• 482 项单测(codec 纯函数 + 适配器(含 Modbus RTU / IEC 104)+ 诊断引擎 + 监听器 + 透明代理 + detect_device),CI 每次推送回归。
• 跨厂商 e2e(tests/e2e):plctap 与 pymodbus、python-snap7、 pymcprotocol、pypi fins、MZ Automation 官方 lib60870.NET 五个第三方权威实现做真实 socket 交叉验证 (读写闭环、读数逐值比对、钓鱼监听互通),CI 随行(uv sync --group e2e); IEC 104 交叉验证需 .NET 8 SDK(缺省自动跳过)。
• 七档评测 45/45:单帧 / RTU 完整性 / 批量日志 / FINS·MELSEC 专项 / 主动探测归因 / 协议自动识别 / IEC 104 专项 (detect 档含"回显服务器欺骗"与"证据压过端口先验"两类反例);与裸模型的双跑对比见下节。

* 同一批语料双跑, 除工具外一切相同: 裸模型 (glm-5.3-flash, 无工具, temperature=0) 直接问答; 确定性关键词判分 (事实等价集, 双模式共用); 6 例因推理端点超时未获有效答案计 FAIL (排除超时后 24/29 = 82.8%)。裸模型跑分日期 2026年09月04日, 语料版本 7cd6d14 (跑分时点; fins 语料其后于 7608f47 随线上格式修正同步更新, 判分语义不变)。 范围说明: 语料建于 M2 (v0.2 时代), 覆盖帧解析 / CRC 完整性 / 日志混排 / 冷门协议语义 / 主动探测归因; v0.3+ 功能 (plc_write / parse_pcap / 透明代理 / modbus_rtu 端点 / vendor_hints / iec104 端点) 未纳入基线。detect 档 (4 用例, v0.4 新增) 与 iec104 档 (6 用例, v0.5.2 新增) 需起真实网络服务/台架做主动探测与交互, 不适合裸问答形式, 故未纳入对比 —— 工具模式七档合计 45/45 (2026年09月07日 按当前语料复跑, 见「质量保障」)。 结论: 单帧翻译裸模型已能胜任, 价值差距集中在冷门协议语义与多故障混排场景 —— 这正是确定性解析 + 结构化知识库的所在。方法学与复跑步骤见 eval/README.md。

MIT