plctap

中文 | English

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

CI PyPI MCP Registry License: MIT

demo

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

工具

层 工具 说明
连接 detect_device 协议自动识别: 给 IP 并发探测标准端口, 按响应指纹判定协议/端口/置信度, deep 模式验证读并生成可执行的 plc_read 建议; 全程只读
连接 probe_device 连通性探测 + 四类失败分层归因 (MELSEC 支持 3E binary/ASCII 自动回退)
连接 plc_read 读数据区并按 datatype/字节序解释 (六个协议端点: modbus / modbus_rtu / fins / melsec / s7 / iec104); datatype 缺省返回 uint16/int16/float32 四种字序 (abcd/cdab/badc/dcba)/int32 多解释
诊断 parse_frame / validate_frame 单帧结构化解析 / 规范校验清单
诊断 diagnose 规则引擎 + 故障知识库 → 结构化候选报告
诊断 parse_pcap 解析 Wireshark 导出 pcap, 逐流逐帧 (每条 TCP 流独立判别协议, 需 uv sync --extra eval)
监听 start_listener / stop_listener / get_listener_frames 钓鱼模式: 设备只能当 client 时立假 server 收帧分析 (三档: record_only / respond_normal / inject_errors 故障注入轮转; MELSEC 回帧支持全部 4 种帧格式; IEC 104 回 STARTDT/TESTFR CON 与总召罐头帧)
监听 start_proxy / stop_proxy / get_proxy_frames 透明代理: 上位机 → 代理 → 真实 PLC, 透传同时分帧录制双向帧, 在线联调免 Wireshark (modbus/fins/melsec)
执行 plc_write / send_frame 默认不注册, PLCTAP_ALLOW_WRITE=true 才启用 (闸门)

写能力

PLCTAP_ALLOW_WRITE=true 后四协议能力:

协议 写语义 options
Modbus fc16 批量写寄存器 (默认) / fc05 线圈 / fc06 单寄存器 point_type, options.function_code, options.values
S7 16 位字写入 DB/M/I/Q 区 options.area, options.db_number
FINS 0102 存储区写字 (CIO/W/H/A/DM/EM) options.area
MELSEC 1401 批量写字, 全部 4 种帧格式 options.device, options.frame_format

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

质量保障

  • 461 项单测（codec 纯函数 + 适配器（含 Modbus RTU）+ 诊断引擎 + 监听器 + 透明代理 + detect_device），CI 每次推送回归。
  • 跨厂商 e2e（tests/e2e）：plctap 与 pymodbus、python-snap7、 pymcprotocol、pypi fins 四个第三方权威实现做真实 socket 交叉验证 （读写闭环、读数逐值比对、钓鱼监听互通），CI 随行（uv sync --group e2e）。
  • 六档评测 39/39：单帧 / RTU 完整性 / 批量日志 / FINS·MELSEC 专项 / 主动探测归因 / 协议自动识别 （detect 档含"回显服务器欺骗"与"证据压过端口先验"两类反例）。

评测对比 (裸模型基线双跑: 五档 35 用例)

档位 plctap 工具链 裸模型直接问答*
单帧 Modbus TCP 8/8 8/8
RTU 完整性/CRC 5/5 4/5
批量日志 (混排) 5/5 4/5
FINS/MELSEC 专项 12/12 5/12
主动探测归因 5/5 5/5
合计 35/35 (100%) 24/35 (68.6%)

* 基线方法: 同一批语料, 裸模型 (glm-5.3-flash, 无工具, temperature=0) 直接问答; 确定性关键词判分 (事实等价集, 双模式共用); 6 例因推理端点超时未获有效答案计 FAIL (排除超时后 24/29 = 82.8%)。跑分日期 2026-09-04, 语料版本见 git。 结论: 单帧翻译裸模型已能胜任, 价值差距集中在冷门协议语义与多故障混排场景 —— 这正是确定性解析 + 结构化知识库的所在。 上表为可双跑的五档基线对比; detect 档 (协议自动识别, 4 用例, v0.4 新增) 需要起 真实网络服务做主动探测, 不适合裸问答形式, 故未纳入基线 —— 工具模式六档合计 39/39 (见「质量保障」)。

快速开始

uvx plctap          # 或 pipx install plctap

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

Claude Desktop 接入 (claude_desktop_config.json)

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

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

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

Codex 接入 (~/.codex/config.toml)

[mcp_servers.plctap]
command = "uvx"
args = ["plctap"]

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

配置 (环境变量, 均有默认值)

变量 默认 说明
PLCTAP_ALLOW_WRITE false 写类工具默认不注册 (安全闸门)
PLCTAP_POOL_MAX_PER_TARGET 2 每目标连接池上限
PLCTAP_IDLE_TIMEOUT_SEC 30 空闲连接回收秒数
PLCTAP_DEFAULT_TIMEOUT_MS 2000 网络超时
PLCTAP_AUDIT_LOG ~/.plctap/audit.jsonl 审计日志路径 (写/发送动作逐帧留痕)

安全

  • 写操作默认完全不注册; 显式 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

License

MIT

Project links

Data verified by PyPI on Sep 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ymxc152 from gravatar.com ymxc152

GitHub Statistics

Data verified by PyPI on Sep 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

eval

Tags

fins industrial mcp melsec modbus plc s7 s7comm scada siemens

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plctap-0.5.2.tar.gz (1.5 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

plctap-0.5.2-py3-none-any.whl (129.9 kB view details)

Uploaded Python 3

File details

Details for the file plctap-0.5.2.tar.gz.

File metadata

  • Download URL: plctap-0.5.2.tar.gz
  • Upload date:
  • Size: 1.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for plctap-0.5.2.tar.gz
Algorithm Hash digest
SHA256 e63e592f76257f76aef04c34b20522741ced47e7a04d5b1923149af66af0d01d
MD5 54634e041976ad0eed24e7488b83edbb
BLAKE2b-256 8f0f49a14e8f48e9ff8c4f114f6ad4fed6f2137ea927455e98ab6e421dee4e44

See more details on using hashes here.

Provenance

The following attestation bundles were made for plctap-0.5.2.tar.gz:

Publisher: publish.yml on ymxc152/plctap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file plctap-0.5.2-py3-none-any.whl.

File metadata

  • Download URL: plctap-0.5.2-py3-none-any.whl
  • Upload date:
  • Size: 129.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for plctap-0.5.2-py3-none-any.whl
Algorithm Hash digest
SHA256 358c5ac3cf226f730fb6f18d25a923fa9474d32be5270d6946fd2d7e6431e7f1
MD5 c764fbaa8703dddd84edfec515e259e5
BLAKE2b-256 c314cd1779bed9e0df078b77c387f68a10d1db37e2edaf0f13a984178caf3e48

See more details on using hashes here.

Provenance

The following attestation bundles were made for plctap-0.5.2-py3-none-any.whl:

Publisher: publish.yml on ymxc152/plctap

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.5.2 This release

2 files

0.5.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page