@codesys/mcp-toolkit 2.1.2 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,106 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.3.0] - 2026-11-14
+
+Several of the new actions use CODESYS's own services inside the IDE, beyond
+what its scripting API documents: `get_signature`, `find_references`,
+`rename_symbol`, `trace_setup`, `trace_record`, the debug actions,
+`hmi_export_codesys` and `--show-window`. They are experimental and checked on
+the versions noted below.
+
+### Added
+- HMI screens: Claude designs live operator screens for the program
+  (`hmi_save_screen`): a process diagram with tanks, pumps, fans, valves and
+  animated pipes, plus gauges, values with sparklines, bars, status lights,
+  buttons, switches, setpoints, trends and alarms, bound to PLC variables, in a
+  dark or light theme. `hmi_screenshot` returns the screen as an image so the
+  model can check and polish its layout. `open_hmi` opens it in the browser
+  (127.0.0.1 with a token), live while the simulation runs; buttons, switches
+  and setpoints write to the simulation only. Screens are stored next to the
+  project as `<project>.hmi.json`.
+- `hmi_export_codesys`: the same screen as a native CODESYS visualization,
+  with cards, gradients, SVG pump, fan and valve symbols in an embedded image
+  pool, live values, bars, tank levels, colour states, buttons, switches,
+  setpoints and alarm rows; a generated program scales values for bars and
+  levels. Built through CODESYS's visualization scripting and its element
+  creators. Returns a picture of the visualization. Checked on SP21.
+- HMI projects with several pages: a shared header with links to every page and
+  the count of active alarms across all pages; page templates (`hmi_template`:
+  overview, unit, alarms, trends, settings); faceplate popups on pumps, fans
+  and valves; panel sizes 1280x720, 1920x1080, 1024x768 and 800x480; warnings
+  for overlapping symbols. Trend history survives page changes.
+- HMI pipes connect to named ports on tanks, pumps, fans, valves and junctions
+  and are routed with right angles, so they meet the symbols exactly in the
+  browser and in CODESYS.
+- `get_signature`: the interface of any POU or type from CODESYS's compiler,
+  including FBs in compiled libraries (TON, CTU, MC_...), with doc comments.
+- `find_references`: where a variable, POU or type is declared, read, written
+  or called, with line and column. Both checked on SP21 and SP22.
+- `trace_setup` and `trace_record`: CODESYS Trace in the simulation, returned
+  as a summary (BOOL edges and extremes with their times), a table and a
+  chart image. Checked on SP22 without a window.
+- `create_graphical`: ladder, FBD and SFC programs and function blocks from a
+  structured description, generated as PLCopenXML. Checked on SP22: a ladder
+  latch, an AND into a TON and a three-step SFC compile and behave correctly
+  in the simulation.
+- Debugging in the simulation: `breakpoint_set` (by line), `debug_status`,
+  `debug_step` (over, into, out), `debug_continue`, `breakpoint_clear`.
+  Checked on SP22 without a window.
+- `rename_symbol`: rename a variable or POU everywhere it is used, from
+  CODESYS's cross-references (works without a window; CODESYS's own
+  refactoring needs one). Checked on SP22: 0 build errors after.
+- `codesys_sim_test`: test cases in the simulation (write or force, cycles or
+  real time, expected values with comparisons and tolerances), reported as a
+  pass/fail table. Checked on SP22.
+- `find_device` and `add_device`: search CODESYS's device repository and add
+  devices to the tree. Checked on SP22: Ethernet, a Modbus TCP Client and a
+  Modbus TCP Server device compile with 0 errors.
+- `create_object` creates persistent variable lists (`persistent_vars`).
+- `hmi_export_codesys` builds every page: page buttons in each header
+  (change shown visualization), the start page and client size of
+  TargetVisu and WebVisu, turning pumps and fans (8 frames chosen by the
+  clock), faceplates as CODESYS dialog visualizations, the pages' alarms in
+  CODESYS alarm management (an alarm group with Error/Warning/Info classes
+  and message texts), and visualization user groups with a Login button.
+  Checked on SP21: three pages and two dialogs compile with 0 errors; the
+  alarms show in CODESYS's alarm group editor with their messages after the
+  project is reopened, and in the simulation CODESYS's alarm manager reports
+  the raised fault as an active alarm.
+- Input actions only go on shapes: CODESYS raises an assertion dialog when
+  an image element gets one.
+- The browser viewer closes open connections when it stops, so an open HMI
+  tab no longer keeps the server from exiting. Screenshots retry once when
+  the headless browser hangs at start.
+- Actions can return images.
+- `--show-window` opens every object the model creates or writes in its editor
+  tab, so the CODESYS window shows the code as it is written, and, while the
+  simulation runs, its live values. CODESYS's scripting API has no call for
+  this, so it uses CODESYS's own frame (checked on SP21 and SP22); where that
+  isn't available, nothing opens and the call works as before.
+
+### Changed
+- The Chinese README states model support directly and lists the models
+  tested with OpenCode, as suggested by Zhen Yang (Alfabete-spec), who
+  reviews the Chinese documentation.
+
+## [2.2.0] - 2026-11-14
+
+### Added
+- `--show-window`: start CODESYS with its window instead of headless, to watch
+  the work in clients without the live panel (such as OpenCode). Prompts are
+  answered as when headless, and the toolkit never closes the window: not on a
+  hang, not when the server stops.
+- README: setup for OpenCode and other MCP clients, and the models tested with
+  OpenCode 1.19.5 on CODESYS SP22 (DeepSeek V4.1 Flash, Qwen 3.6 Plus, GLM 5.3,
+  MiniMax M3: all passed). New screenshots: Claude building and testing a
+  tank level controller next to the workspace (top of the README), an OpenCode
+  session, the browser workspace and the CODESYS window.
+- A Simplified Chinese README (`README.zh-CN.md`): setup for OpenCode and other
+  clients that work in China, an npmmirror install line, and the tested models.
+
 ## [2.1.2] - 2026-11-13
 
 ### Fixed

package/README.md

@@ -2,7 +2,9 @@
 
 # CODESYS MCP Toolkit
 
-**Let Claude read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
+**Let Claude, or any MCP client, read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
+
+English | [简体中文](README.zh-CN.md)
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)](https://www.npmjs.com/package/@codesys/mcp-toolkit)
@@ -18,7 +20,7 @@ open in the background and gives Claude, or any MCP client, direct access to
 it. Claude works on your real project with the real CODESYS compiler, and you
 can watch the code change as it happens.
 
-![The live workspace, showing a sample project with a change waiting for review](docs/images/workspace.png)
+![Claude builds a tank level controller in CODESYS: the live panel in the chat, the code compiled with 0 errors and five simulation tests passed, and the same function block in the CODESYS-style workspace, ready to review](docs/images/claude-and-codesys.png)
 
 ## Highlights
 
@@ -32,6 +34,9 @@ can watch the code change as it happens.
   interfaces, without reading every object.
 - **Shows its work.** A live panel with the project tree, the code as it is
   written, compile results, and Accept or Revert for each change.
+- **Designs operator screens.** Claude builds a live HMI for your program,
+  with tanks, pumps, valves, gauges, trends and alarms, looks at it, and
+  polishes it. You operate it in the browser against the simulation.
 - **Never touches a real controller.** The only online connection is to
   CODESYS's own simulation, and every online call checks for it first.
 
@@ -79,6 +84,9 @@ Claude Desktop:
 `--codesys-path` and `--codesys-profile` are optional. Without them the server
 uses the newest CODESYS install under Program Files and its newest profile.
 
+Using OpenCode, Cursor, Cline or another client, or a model such as DeepSeek or
+Qwen? See [Other clients and models](#other-clients-and-models).
+
 ### Try it
 
 > Create a project called `BlinkDemo.project`. Add a function block that toggles
@@ -101,19 +109,33 @@ operation. [The reference](docs/reference.md) describes each one.
 | --- | --- |
 | **Projects** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
 | **Read code** | `get_project_tree` `read_objects` `search_code` `get_outline` |
-| **Change code** | `write_object` `create_object` `delete_object` `rename_object` |
+| **Change code** | `write_object` `create_object` `create_graphical` `delete_object` `rename_object` |
 | **Build** | `compile` |
-| **Libraries** | `list_libraries` `add_library` `remove_library` `get_library_api` |
-| **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` |
+| **Libraries** | `list_libraries` `add_library` `remove_library` `get_library_api` `get_signature` |
+| **Navigate code** | `find_references` `rename_symbol` |
+| **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` `find_device` `add_device` |
 | **Change tracking** | `checkpoint` `get_changes` `revert_object` |
-| **Simulation** | `codesys_sim_start` `codesys_sim_stop` `codesys_sim_status` `codesys_sim_control` `codesys_sim_cycle` `codesys_sim_read` `codesys_sim_write` `codesys_sim_force` `codesys_sim_unforce` |
+| **Simulation** | `codesys_sim_start` `codesys_sim_stop` `codesys_sim_status` `codesys_sim_control` `codesys_sim_cycle` `codesys_sim_read` `codesys_sim_write` `codesys_sim_force` `codesys_sim_unforce` `codesys_sim_test` |
+| **Trace** | `trace_setup` `trace_record` |
+| **Debug** | `breakpoint_set` `breakpoint_clear` `debug_status` `debug_step` `debug_continue` |
+| **HMI screens** | `hmi_save_screen` `hmi_template` `hmi_screenshot` `hmi_export_codesys` `hmi_list` `hmi_delete_screen` `open_hmi` |
 | **Helpers** | `batch` `wait` `help` `open_workspace` |
 
 `batch` runs up to 50 actions in one call, which is much faster than separate
 calls.
 
-Version 2 edits Structured Text only. Objects with graphical bodies (SFC, CFC,
-LD, FBD) appear in the tree and can be read as PLCopenXML, but not edited.
+Some actions go beyond what CODESYS's scripting API documents and use CODESYS's
+own services inside the IDE: `get_signature`, `find_references`,
+`rename_symbol`, `trace_setup`, `trace_record`, the debug actions,
+`hmi_export_codesys` (with its alarms and user groups) and `--show-window`.
+They are **experimental**: checked on CODESYS V3.5 SP21 and SP22 as noted in
+the [changelog](CHANGELOG.md). On another version they may report that the
+feature isn't available, or not work.
+
+Claude writes Structured Text, and creates ladder (LD), FBD and SFC programs
+and function blocks with `create_graphical` from a simple description of rungs,
+networks or steps; CODESYS draws them. Existing graphical bodies can be read as
+PLCopenXML but not edited in place yet. CFC isn't supported.
 
 ## Live panel
 
@@ -125,6 +147,8 @@ the project tree, editor tabs, compile problems and a review list.
 From the panel you can **Accept** or **Revert** each change, compare it with
 the version you last reviewed, and **Pause Claude** while you look around.
 
+![The workspace: a PI controller function block with properties and an interface, changed by Claude and waiting for review](docs/images/workspace.png)
+
 The card needs a client that supports
 [MCP Apps](https://modelcontextprotocol.io/extensions/apps). In our testing
 Claude Desktop draws it in the Code tab but not in a normal chat
@@ -134,6 +158,128 @@ the browser never opens by itself.
 
 [More about the panel](docs/reference.md#live-panel)
 
+## HMI screens
+
+Ask Claude for an operator screen and it designs one for your program: a
+process diagram with tanks, pumps, fans, valves and flowing pipes, and gauges,
+values, trends, status lights, alarms, buttons, switches and setpoints, all
+bound to your PLC variables.
+
+![The live HMI Claude designed for a pump station, running against CODESYS's simulation: the pump's faceplate switched to manual and started, the pump turning and the pipes flowing, a fault raised on the alarm page, the trend page, and the alarm on the overview](docs/images/hmi-live.gif)
+
+- **A whole HMI, not one screen.** Pages (overview, unit, alarms, trends,
+  settings) share a header that links to every page and counts the active
+  alarms of all pages. `hmi_template` gives Claude a good layout for each kind
+  of page to adapt. Panels: 1280x720, 1920x1080, 1024x768 or 800x480.
+- **Faceplates.** Clicking a pump, fan or valve opens its popup: mode switch,
+  Start/Stop or Open/Close, Reset, live values and a setpoint.
+- **Pipes connect themselves.** Tanks, pumps, fans, valves and junctions have
+  named ports (`T-101.right`, `P-101.in`, `V-102.out`). Claude says what a pipe
+  connects, and the toolkit routes it with right angles to meet each symbol
+  exactly, in the browser and in CODESYS alike. Unknown symbols or ports are
+  refused with the list of valid ones.
+- **Claude checks its own work.** `hmi_screenshot` returns the screen as an
+  image, so Claude can see overlaps, empty space or unclear labels and fix
+  them before you look.
+- **Live in your browser.** Ask Claude to open the HMI (`open_hmi`). The page
+  is served by the toolkit on 127.0.0.1 with a token, like the workspace. While
+  CODESYS's simulation runs, it shows live values, pumps spin, pipes flow and
+  trends draw. Buttons, switches and setpoints write to the simulation, so you
+  can operate your program before any hardware exists.
+- **Stored with the project.** Screens are saved next to the project file as
+  `<project>.hmi.json`, so they travel with it and can go into version control.
+- **Dark and light themes,** on a 1280x720 canvas that scales to any window.
+
+The HMI writes only into CODESYS's own simulation, like the rest of the
+toolkit. Screenshots use Microsoft Edge or Google Chrome, whichever is
+installed.
+
+### As a native CODESYS visualization
+
+`hmi_export_codesys` builds the same screen as a real CODESYS visualization in
+your project. It is an ordinary visualization object, so it goes with the
+application like one you drew yourself (we checked it in CODESYS's simulation,
+not on a controller). It doesn't use CODESYS's stock lamps: cards with gradients, SVG
+pump, fan and valve symbols in an embedded image pool, live values, bars and
+tank levels, colour states, buttons, switches, setpoints and alarm rows that
+appear only while active. A generated program, `PRG_HMI_<screen>`, scales
+values for the bars and levels. Claude gets a picture of the result.
+
+A multi-page HMI comes out as one visualization per page with page buttons in
+the header, the first page as the start page of TargetVisu and WebVisu at the
+panel size, pumps and fans that turn while running, faceplates as CODESYS
+dialogs, the pages' alarms in CODESYS's alarm management (Alarm Configuration,
+with timestamps and acknowledge in the PLC), and user groups (Operator,
+Maintenance, Admin) behind a Login button. Users and passwords are yours to add
+in the Visualization Manager.
+
+![The same pump station as a native CODESYS visualization, running in CODESYS's simulation](docs/images/hmi-codesys.png)
+
+The alarms are CODESYS's own, not a copy in the HMI: an alarm group with its
+observations, classes and messages, which CODESYS's alarm manager evaluates in
+the PLC. In the simulation, raising the fault made the group report an active
+alarm, and it stayed pending after the fault cleared, until acknowledged, as an
+Error-class alarm should.
+
+![The exported alarms in CODESYS's alarm group editor: a digital observation on PLC_PRG.xHighLevel with class Warning and message "High level T-101 (above 90 %)", and one on PLC_PRG.xFault with class Error and message "Pump P-101 fault"](docs/images/codesys-alarms.png)
+
+CODESYS's scripting can't create trend, meter or alarm-table elements, so
+trends show their current values, gauges show a bar, and the alarm page shows a
+row per alarm while it is active (acknowledge it in CODESYS's own alarm table,
+which you can add from the toolbox). Checked on CODESYS V3.5 SP21 in the
+simulation. A visualization needs the `FloatingPointUtils` library in CODESYS's
+library repository; if it's missing, the export says so.
+
+## Other clients and models
+
+The server works with any MCP client, not only Claude. For
+[OpenCode](https://opencode.ai), put this in `opencode.json` in your project
+folder (or in `~/.config/opencode/opencode.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "codesys": {
+      "type": "local",
+      "command": [
+        "codesys-mcp-tool",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.22.40\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP22 Patch 4",
+        "--workspace", "C:\\PLC\\Projects"
+      ],
+      "enabled": true
+    }
+  }
+}
+```
+
+`opencode mcp list` should then show `codesys` as connected. Clients that read
+an `mcpServers` file (Cursor, Cline, VS Code and others) take the same
+`command` and `args` as the Claude Desktop example above.
+
+Tested on 13 November 2026 with OpenCode 1.19.5 and CODESYS V3.5 SP22: each of
+these models created a project, read and changed `PLC_PRG`, compiled, listed
+libraries and devices, and ran the simulation, without help.
+
+| Model | Result |
+| --- | --- |
+| DeepSeek V4.1 Flash | All steps passed |
+| Qwen 3.6 Plus | All steps passed |
+| GLM 5.3 | All steps passed |
+| MiniMax M3 | All steps passed |
+
+![OpenCode with DeepSeek V4.1 Flash: a pump function block written, compiled and tested in CODESYS's simulation](docs/images/opencode-session.png)
+
+The live panel needs a client that shows MCP Apps cards (see
+[Live panel](#live-panel)). In other clients `open_sim_panel` does nothing
+visible; ask the model to open the workspace (`open_workspace`) to get the same
+view in your browser, or start the server with
+[`--show-window`](#watch-it-in-the-codesys-window) to watch the CODESYS window
+itself.
+
+![The workspace in the browser after the OpenCode session: PLC_PRG's changes, and the review list with Accept and Revert for each object](docs/images/workspace-review.png)
+
 ## Safety
 
 - **No real controller.** The toolkit doesn't log in or download to a
@@ -166,6 +312,36 @@ the browser never opens by itself.
 | `--no-viewer` | Don't serve the browser workspace |
 | `--no-shared` | Run CODESYS in this process instead of the shared session |
 | `--attach <dir>` | Experimental: work in a CODESYS / Machine Expert window you already have open, instead of starting one. See [Working in an open window](#work-in-a-window-you-already-have-open-experimental) |
+| `--show-window` | Start CODESYS with its window instead of headless. See [Watch it in the CODESYS window](#watch-it-in-the-codesys-window) |
+
+### Watch it in the CODESYS window
+
+By default CODESYS runs headless. With `--show-window` the server starts it with
+its normal window, so you can watch the work in any MCP client: every object the
+model creates or writes opens in its editor tab, with the new code in it.
+
+![CODESYS started with --show-window: the model just created FB_Blink, and it opened in its editor](docs/images/codesys-window.png)
+
+While the simulation runs, the open editors show live values, as in CODESYS's own
+online mode:
+
+![The same window during the simulation: PLC_PRG shows xEnable and xOn as TRUE](docs/images/codesys-window-sim.png)
+
+CODESYS's scripting API has no call for opening an editor, so the toolkit uses
+CODESYS's own (undocumented) frame for it, checked on SP21 and SP22. If a CODESYS
+version doesn't have it, nothing opens and everything else works as before.
+
+While the server is connected, the window is for watching: the toolkit's script
+keeps running in it (that is what lets it answer CODESYS's prompts, such as a
+storage-format upgrade, the same way as headless), so CODESYS treats it as one
+long operation. The status bar says "Executing script"; its **Click here to
+CANCEL** link stops the toolkit's script, so leave it alone while you work with
+the model. When the server stops, the script ends and the window is yours to
+work in.
+
+The toolkit never closes the window: not when a call hangs or a dialog waits
+for an answer (answer it in the window), and not when the server stops. Close it
+yourself when you're done; the next call then starts a new one.
 
 ### Several CODESYS versions
 
@@ -221,6 +397,8 @@ MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
                             └─ fixed operation handlers (IronPython 2.7)
 ```
 
+With `--show-window`, CODESYS starts without `--noUI` and runs the same watcher.
+
 - **No generated code.** Requests are an operation name plus JSON arguments,
   handled by fixed functions in `watcher/mcp_ops.py`.
 - **Hang detection.** The watcher reports `busy` with a deadline. If CODESYS
@@ -238,8 +416,8 @@ MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
 | **CODESYS is still starting** | The first start after boot can take minutes. Check `codesys_status`, then try again. |
 | **`startup_failed`** or **`startup_timeout`** | Check the profile name and that CODESYS starts by hand. The error includes the last lines of `watcher.log`. |
 | **Library errors after `create_project`** ([#4](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/4)) | The default template is brought up to the running CODESYS, so its libraries should resolve. A template you pass yourself is used as it is. If libraries are still missing, install them with the CODESYS Library Repository. |
-| **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. |
-| **`dialog`** | CODESYS opened a dialog, named in the error, that a session without a window can't answer. CODESYS was stopped and restarts on the next call. Do the same step once in the CODESYS window, answer the dialog there, and try again. |
+| **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. With `--show-window` nothing is closed: check the window. |
+| **`dialog`** | CODESYS opened a dialog, named in the error, that a session without a window can't answer. CODESYS was stopped and restarts on the next call. Do the same step once in the CODESYS window, answer the dialog there, and try again. With `--show-window`, answer it in the window. |
 
 Each session folder keeps a `watcher.log`.
 
@@ -285,6 +463,8 @@ The persistent-watcher design borrows ideas from
 [phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
 (file-queue IPC, version-safe opening). Both are MIT-licensed.
 
+The [Chinese README](README.zh-CN.md) was reviewed by Zhen Yang (Alfabete-spec).
+
 ## License
 
 [MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,254 @@
+<div align="center">
+
+# CODESYS MCP 工具包
+
+**让 Claude 或任何 MCP 客户端，在你的 CODESYS V3.5 项目中读取、编写、编译并仿真结构化文本（ST）代码。**
+
+[English](README.md) | 简体中文
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)](https://www.npmjs.com/package/@codesys/mcp-toolkit)
+![CODESYS V3.5](https://img.shields.io/badge/CODESYS-V3.5-c8102e)
+![Node.js 20 or later](https://img.shields.io/badge/node-%E2%89%A520-339933)
+![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078d4)
+[![Model Context Protocol](https://img.shields.io/badge/MCP-server-6e56cf)](https://modelcontextprotocol.io)
+
+</div>
+
+这是一个 [MCP](https://modelcontextprotocol.io)（模型上下文协议）服务器。它在后台保持一个
+CODESYS 会话，让 AI 助手直接操作你的真实项目：用真正的 CODESYS 编译器编译，在 CODESYS
+自带的仿真中测试，而你可以实时看到代码的变化。
+
+工具包支持任何能够通过 MCP 客户端调用工具的 AI 模型。我们用 OpenCode 测试了 DeepSeek V4.1 Flash、
+通义千问 Qwen 3.6 Plus、GLM 5.3 和 MiniMax M3，均完成了全部步骤（见[已测试的模型](#已测试的模型)）。
+
+![Claude 在 CODESYS 中编写液位控制功能块：对话中的实时面板、0 错误编译和 5 项仿真测试全部通过，右侧是同一功能块在工作区中的代码](docs/images/claude-and-codesys.png)
+
+## 主要功能
+
+- **直接修改真实项目。** 以结构化文本编写 POU、方法、属性、接口、DUT 和 GVL。
+- **用真正的编译器编译。** 错误会带上对象、行号和错误代码返回，包括还没有被任何任务调用的代码。
+- **在仿真中测试。** 在 CODESYS 自带的仿真中运行、按周期单步执行、读取、写入和强制变量，
+  无需安装其他软件，也不需要 PLC 硬件。
+- **理解整个项目。** 提供项目大纲、I/O 列表、设备树和库接口，无需逐个读取对象。
+- **过程可见。** 实时面板显示项目树、正在编写的代码和编译结果，每个改动都可以接受或还原。
+- **绝不连接真实控制器。** 唯一的在线连接是 CODESYS 自带的仿真，每次在线操作前都会先检查。
+
+## 快速开始
+
+### 环境要求
+
+- Windows，安装 **CODESYS V3.5** 及其 **Scripting**（脚本）插件。已在 SP21 和 SP22
+  上测试，SP16 及以上版本应该都可以使用。
+- **Node.js 20** 或更高版本。
+
+施耐德 EcoStruxure Machine Expert V2.3（`LogicBuilder.exe`）同样可用：只设置
+`--codesys-path`，不要设置 `--codesys-profile`，因为 Machine Expert 没有配置文件。
+详见 [Machine Expert 说明](docs/machine-expert-testing.md)（英文）。
+
+### 安装
+
+```bash
+npm install -g @codesys/mcp-toolkit
+```
+
+如果从 npm 下载很慢，可以使用 npmmirror 镜像：
+
+```bash
+npm install -g @codesys/mcp-toolkit --registry=https://registry.npmmirror.com
+```
+
+### 在 OpenCode 中使用
+
+在项目文件夹的 `opencode.json` 中（或 `~/.config/opencode/opencode.json`）加入：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "codesys": {
+      "type": "local",
+      "command": [
+        "codesys-mcp-tool",
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.22.40\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP22 Patch 4",
+        "--workspace", "C:\\PLC\\Projects"
+      ],
+      "enabled": true
+    }
+  }
+}
+```
+
+运行 `opencode mcp list`，应能看到 `codesys` 显示为已连接（connected）。
+
+### 其他客户端
+
+Cline、Trae、通义灵码、Cursor、Claude Desktop 等使用 `mcpServers` 配置的客户端，
+一般都采用下面的格式（具体位置见各客户端的 MCP 设置）：
+
+```json
+{
+  "mcpServers": {
+    "codesys": {
+      "command": "codesys-mcp-tool",
+      "args": [
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21",
+        "--workspace", "C:\\PLC\\Projects"
+      ]
+    }
+  }
+}
+```
+
+`--codesys-path` 和 `--codesys-profile` 可以省略，省略时服务器会使用 Program Files 下
+最新安装的 CODESYS 及其最新的配置文件。
+
+### 试一试
+
+> 创建一个名为 `BlinkDemo.project` 的项目。添加一个每秒翻转一次输出的功能块，在 `PLC_PRG`
+> 中调用它，编译，并在仿真中证明输出确实在翻转。
+
+服务器启动时，CODESYS 会在后台启动。首次冷启动需要 1 到 3 分钟，之后大约 10 秒。
+
+## 已测试的模型
+
+2026 年 11 月 13 日，使用 OpenCode 1.19.5 和 CODESYS V3.5 SP22 测试：每个模型都在没有人工
+帮助的情况下完成了创建项目、读取并修改 `PLC_PRG`、编译、列出库和设备，以及运行仿真。
+
+| 模型 | 结果 |
+| --- | --- |
+| DeepSeek V4.1 Flash | 全部通过 |
+| Qwen 3.6 Plus | 全部通过 |
+| GLM 5.3 | 全部通过 |
+| MiniMax M3 | 全部通过 |
+
+![OpenCode 与 DeepSeek V4.1 Flash：编写水泵功能块，编译，并在 CODESYS 仿真中测试](docs/images/opencode-session.png)
+
+## 实时查看 AI 的工作
+
+有三种方式：
+
+- **实时面板（MCP Apps 卡片）。** 在支持 [MCP Apps](https://modelcontextprotocol.io/extensions/apps)
+  的客户端中，打开或创建项目后，面板会以卡片形式显示在对话中：项目树、正在编写的代码、
+  编译问题，以及每个改动的“接受”和“还原”。
+- **浏览器中的工作区。** 在其他客户端中，让模型“打开 CODESYS 工作区”（`open_workspace`），
+  同样的界面会在浏览器中打开，只监听本机 127.0.0.1，并带有访问令牌。浏览器不会自动打开。
+- **CODESYS 窗口。** 启动参数加上 `--show-window`，CODESYS 会以正常窗口运行，而不是在后台
+  无界面运行。模型创建或修改的每个对象都会在编辑器标签页中打开，可以直接看到新写的代码；
+  仿真运行时，打开的编辑器会显示变量的实时值。工具包不会自动关闭这个窗口。
+
+![使用 --show-window 启动的 CODESYS：模型刚创建的 FB_Blink 已在编辑器中打开](docs/images/codesys-window.png)
+
+![OpenCode 会话结束后在浏览器中打开的工作区：PLC_PRG 的改动，以及每个对象的接受和还原按钮](docs/images/workspace-review.png)
+
+## HMI 操作画面
+
+让 Claude 为你的程序设计操作画面：带储罐、泵、风机、阀门和流动管道的工艺流程图，以及仪表盘、
+数值、趋势图、状态灯、报警、按钮、开关和设定值，全部绑定到 PLC 变量。
+
+![Claude 为泵站设计的实时 HMI，连接 CODESYS 仿真运行：打开泵的面板切换到手动并启动，泵转动、管道流动，在报警页触发故障，趋势页，以及总览页上的报警](docs/images/hmi-live.gif)
+
+- **完整的 HMI，而不只是一个画面。** 多个页面（总览、单元、报警、趋势、设置）共用一个页眉，
+  页眉链接到每个页面并统计所有页面的活动报警。`hmi_template` 为每种页面提供良好的布局。
+  面板尺寸：1280x720、1920x1080、1024x768 或 800x480。
+- **操作面板（faceplate）。** 点击泵、风机或阀门会弹出面板：模式开关、启动/停止或开/关、复位、
+  实时数值和设定值。
+- **Claude 会检查自己的设计。** `hmi_screenshot` 把画面作为图片返回给 Claude，它能发现重叠、
+  空白或不清楚的标签并自行修正。
+- **在浏览器中实时运行。** 让 Claude 打开 HMI（`open_hmi`）。页面由工具包在 127.0.0.1 上提供，
+  并带有访问令牌。CODESYS 仿真运行时显示实时数值，泵会转动，管道会流动；按钮、开关和设定值
+  写入仿真，在没有硬件之前就能操作你的程序。
+- **管道自动连接。** 储罐、泵、风机、阀门和三通都有命名接口（如 `T-101.right`、`P-101.in`），Claude 只需说明管道连接哪两个接口，
+  工具包会以直角自动布线，在浏览器和 CODESYS 中都能精确对接。
+- **与项目一起保存。** 画面保存在项目文件旁边的 `<项目名>.hmi.json` 中。
+
+HMI 只写入 CODESYS 自带的仿真，不会连接真实控制器。
+
+`hmi_export_codesys` 还能把同一个画面生成为项目中的原生 CODESYS 可视化（不用 CODESYS 自带的灯和按钮样式）：
+渐变卡片、嵌入图片池的 SVG 泵/风机/阀门符号、实时数值、液位和棒图、按钮、开关、设定值和报警行，
+它是普通的可视化对象，随应用程序一起使用（我们在 CODESYS 仿真中验证过，未在真实控制器上测试）。
+
+多页 HMI 会生成为每页一个可视化，页眉中有页面按钮；第一页设为 TargetVisu 和 WebVisu 的起始页；
+运行中的泵和风机会转动；操作面板生成为 CODESYS 对话框；用户组（Operator、Maintenance、Admin）
+配有登录按钮（用户和密码由你在 Visualization Manager 中添加）。
+
+![同一个泵站画面，作为原生 CODESYS 可视化在仿真中运行](docs/images/hmi-codesys.png)
+
+报警是 CODESYS 自己的报警，而不是 HMI 中的副本：导出会创建报警配置（Alarm Configuration）中的
+报警组，包括观察条件、报警类别和报警消息，由 CODESYS 的报警管理器在 PLC 中计算。在仿真中触发
+故障后，报警组报告一个活动报警；故障消失后它仍保持待确认状态，直到被确认，这正是 Error 类报警
+应有的行为。
+
+![导出的报警在 CODESYS 报警组编辑器中：PLC_PRG.xHighLevel 的数字观察，类别 Warning，消息 "High level T-101 (above 90 %)"；PLC_PRG.xFault 的数字观察，类别 Error，消息 "Pump P-101 fault"](docs/images/codesys-alarms.png)
+
+CODESYS 的脚本无法创建趋势、仪表或报警表元素，所以趋势显示当前值，仪表显示为棒图，报警页在
+报警活动时显示一行（可在 CODESYS 自带的报警表中确认报警，报警表可从工具箱添加）。已在 CODESYS
+V3.5 SP21 的仿真中验证。可视化需要 CODESYS 库存储库中有 `FloatingPointUtils` 库；如果缺少，导出会提示。
+
+## 可用操作
+
+所有操作都通过一个 MCP 工具 `codesys` 完成，每个操作对应一个 action。
+[参考文档](docs/reference.md)（英文）详细说明了每一个操作。
+
+| 类别 | 操作 |
+| --- | --- |
+| **项目** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
+| **读取代码** | `get_project_tree` `read_objects` `search_code` `get_outline` |
+| **修改代码** | `write_object` `create_object` `create_graphical` `delete_object` `rename_object` |
+| **编译** | `compile` |
+| **库** | `list_libraries` `add_library` `remove_library` `get_library_api` `get_signature` |
+| **代码导航** | `find_references` `rename_symbol` |
+| **任务与 I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` `find_device` `add_device` |
+| **改动跟踪** | `checkpoint` `get_changes` `revert_object` |
+| **仿真** | `codesys_sim_start` `codesys_sim_stop` `codesys_sim_status` `codesys_sim_control` `codesys_sim_cycle` `codesys_sim_read` `codesys_sim_write` `codesys_sim_force` `codesys_sim_unforce` `codesys_sim_test` |
+| **跟踪（Trace）** | `trace_setup` `trace_record` |
+| **调试** | `breakpoint_set` `breakpoint_clear` `debug_status` `debug_step` `debug_continue` |
+| **HMI 画面** | `hmi_save_screen` `hmi_template` `hmi_screenshot` `hmi_export_codesys` `hmi_list` `hmi_delete_screen` `open_hmi` |
+| **辅助** | `batch` `wait` `help` `open_workspace` |
+
+`batch` 可以在一次调用中执行最多 50 个操作，比逐个调用快得多。
+
+有些操作超出了 CODESYS 脚本 API 文档的范围，使用 IDE 内部的 CODESYS 服务：`get_signature`、
+`find_references`、`rename_symbol`、`trace_setup`、`trace_record`、调试操作、`hmi_export_codesys`
+（包括报警和用户组）以及 `--show-window`。它们属于**实验性功能**：已在 CODESYS V3.5 SP21 和 SP22 上
+验证（见[更新日志](CHANGELOG.md)），在其他版本上可能提示功能不可用，或无法正常工作。
+
+Claude 编写结构化文本，并可用 `create_graphical` 根据梯级、网络或步骤的简单描述创建梯形图（LD）、
+FBD 和 SFC 程序及功能块，由 CODESYS 绘制。已有的图形化代码可以以 PLCopenXML 形式读取，但还不能
+就地编辑。不支持 CFC。
+
+## 安全
+
+- **不连接真实控制器。** 工具包不会登录或下载到控制器，只会连接 CODESYS 自带的仿真，
+  每次在线操作前都会检查仿真模式是否开启。
+- **一次授权涵盖所有操作，** 包括修改或删除项目代码的操作。请在副本上工作，或使用版本控制。
+- **改动可以撤销。** 打开项目时会自动创建检查点，`revert_object` 可以把对象（包括其方法和
+  属性）恢复到检查点时的状态。
+- **自动保存。** 默认每次改动后都会保存项目；使用 `--no-autosave` 只在需要时保存。
+- **仿真不会改动项目。** 仿真运行时禁止编辑，设备上的仿真设置也不会被保存。
+
+## 更多内容（英文）
+
+- [全部启动参数](README.md#configuration)
+- [故障排除](README.md#troubleshooting)
+- [工作原理](README.md#how-it-works)
+- [开发与测试](README.md#development)
+- [参与贡献](CONTRIBUTING.md)
+
+欢迎提交 Issue 和 Pull Request，中文或英文均可。
+
+## 致谢
+
+感谢 Zhen Yang（Alfabete-spec）审阅本中文文档。
+
+## 许可证
+
+[MIT](LICENSE)
+
+CODESYS 是 CODESYS GmbH 的商标。本项目为独立项目，与 CODESYS GmbH 无关联，也未获其认可。
+
+---
+
+本文档对应 2026 年 11 月 14 日的英文 README。如有出入，以[英文版](README.md)为准。

package/dist/actions.d.ts

@@ -8,11 +8,16 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
 export declare const TOOL_NAME = "codesys";
+export type ActionContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
 export type ActionResult = {
-    content: {
-        type: "text";
-        text: string;
-    }[];
+    content: ActionContent[];
     isError?: boolean;
 };
 export interface ActionConfig<S extends z.ZodObject = z.ZodObject> {