plctap

Agent 的 PLC 驱动层 — 让 Claude / Codex / Cursor 直接连接、读写、诊断 Modbus TCP / FINS / MELSEC PLC 的 MCP Server。

demo

状态: 开发中 (M3: 三协议 + 诊断引擎 + 钓鱼监听)。 本 README 将随里程碑补全: 五档评测对比表 (工具模式 vs 裸模型)、三端接入截图 (待用户环境)。

工具

层 工具 说明
连接 probe_device 连通性探测 + 四类失败分层归因
连接 plc_read 读数据区并按 datatype/字节序解释 (三协议)
诊断 parse_frame / validate_frame 单帧结构化解析 / 规范校验清单
诊断 diagnose 规则引擎 + 故障知识库 → 结构化候选报告
诊断 parse_pcap 解析 Wireshark 导出 pcap, 逐流逐帧 (需 uv sync --extra eval)
监听 start_listener / stop_listener / get_listener_frames 钓鱼模式: 设备只能当 client 时立假 server 收帧分析
执行 plc_write / send_frame 默认不注册, PLCTAP_ALLOW_WRITE=true 才启用 (闸门)

评测对比 (五档, 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。 结论: 单帧翻译裸模型已能胜任, 价值差距集中在冷门协议语义与多故障混排场景 —— 这正是确定性解析 + 结构化知识库的所在。

快速开始

uvx plctap          # 或 pipx install 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_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
uv run pytest -q   # codec 纯函数单测 (毫秒级) + MCP 冒烟测试
uv run plctap      # 本地启动 stdio server

License

MIT

Project links

Data verified by PyPI on Sep 4, 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:
Newer release available (0.5.2)

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 4, 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 scada

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.1.1.tar.gz (350.1 kB view details)

Uploaded Source

Built Distribution

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

plctap-0.1.1-py3-none-any.whl (73.2 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for plctap-0.1.1.tar.gz
Algorithm Hash digest
SHA256 0c9b30f2c4f7b62871db4b47eeceabe3709abdfeafe2aa8bd125a2dc696a9f34
MD5 f3e1bb8ae2298ecb10897a14b72f35b9
BLAKE2b-256 178aa68f1b88f37dbfdea7c9901d4edae71a4d0a4859f38b8422550a3ff7c855

See more details on using hashes here.

Provenance

The following attestation bundles were made for plctap-0.1.1.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.1.1-py3-none-any.whl.

File metadata

  • Download URL: plctap-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 73.2 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.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 65ded987646e8a502659af9eb018ed2074d6fbf94733ab59425c94133c05b875
MD5 b0e9c14e5d374eda03efb414663c9bb7
BLAKE2b-256 8bb7928d26471ec35ee510944e65e04d272d6025945344082de47bbf8b34a1db

See more details on using hashes here.

Provenance

The following attestation bundles were made for plctap-0.1.1-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

0.5.2

2 files

0.5.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

This release

0.1.1 This release

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