plctap

中文 | English

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

状态: v0.5.3 (协议自动识别 + 透明代理 + 故障注入监听 + 七协议端点读写; IEC 104 经 lib60870、EtherNet/IP 经 pycomm3 官方实现交叉验证)。

工具

写能力

PLCTAP_ALLOW_WRITE=true 后四协议能力:

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

质量保障

• 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 用例)

* 基线方法: 同一批语料, 裸模型 (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=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