plctap
Agent 的 PLC 驱动层 — 让 Claude / Codex / Cursor 直接连接、读写、诊断 Modbus TCP / FINS / MELSEC PLC 的 MCP Server。
状态: 开发中 (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 才启用 (闸门) |
快速开始
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
1 maintainer
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.0.tar.gz
(339.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
plctap-0.1.0-py3-none-any.whl
(72.6 kB
view details)
File details
Details for the file plctap-0.1.0.tar.gz.
File metadata
- Download URL: plctap-0.1.0.tar.gz
- Upload date:
- Size: 339.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fc312498fac5de7ea8eb72b0453e66c46afbe96c5b2f70642f637c9701c1fee2
|
|
| MD5 |
529a968e1ea02bcb79700b8be04045ae
|
|
| BLAKE2b-256 |
2b71eadca8c4c965de6eb0fabd732e4af1f597469a70092c84042096bb6698c9
|
Provenance
The following attestation bundles were made for plctap-0.1.0.tar.gz:
Publisher:
publish.yml on ymxc152/plctap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
plctap-0.1.0.tar.gz -
Subject digest:
fc312498fac5de7ea8eb72b0453e66c46afbe96c5b2f70642f637c9701c1fee2 - Sigstore transparency entry: 2708408576
- Sigstore integration time:
-
Permalink:
ymxc152/plctap@a7597ea0b16a996d9c1830ec5952665b8e676359 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/ymxc152
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a7597ea0b16a996d9c1830ec5952665b8e676359 -
Trigger Event:
push
-
Statement type:
File details
Details for the file plctap-0.1.0-py3-none-any.whl.
File metadata
- Download URL: plctap-0.1.0-py3-none-any.whl
- Upload date:
- Size: 72.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
881e780151465b3ca9033f9ba4e24b1c61a146bb80362826217f6a42ad026c0b
|
|
| MD5 |
53645d84a783a4f62013ef0846f5bd33
|
|
| BLAKE2b-256 |
f9dd8128468504d6e53486658dc3771c3e444967794ff3ef485ce4eca1887806
|
Provenance
The following attestation bundles were made for plctap-0.1.0-py3-none-any.whl:
Publisher:
publish.yml on ymxc152/plctap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
plctap-0.1.0-py3-none-any.whl -
Subject digest:
881e780151465b3ca9033f9ba4e24b1c61a146bb80362826217f6a42ad026c0b - Sigstore transparency entry: 2708408598
- Sigstore integration time:
-
Permalink:
ymxc152/plctap@a7597ea0b16a996d9c1830ec5952665b8e676359 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/ymxc152
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a7597ea0b16a996d9c1830ec5952665b8e676359 -
Trigger Event:
push
-
Statement type:
