@codesys/mcp-toolkit 1.5.7 → 2.0.0-alpha.0

package/README.md

@@ -1,152 +1,269 @@
+<div align="center">
 
-# @codesys/mcp-toolkit
+# CODESYS MCP Toolkit
 
-![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)
-![License](https://img.shields.io/github/license/johannesPettersson80/codesys-mcp-toolkit)
-![Node Version](https://img.shields.io/node/v/@codesys/mcp-toolkit)
+**Let Claude read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
 
-A Model Context Protocol (MCP) server for CODESYS V3 programming environments. This toolkit enables seamless interaction between MCP clients (like Claude Desktop) and CODESYS, allowing automation of project management, POU creation, code editing, and compilation tasks via the CODESYS Scripting Engine.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Status: 2.0 alpha](https://img.shields.io/badge/status-2.0%20alpha-orange)
+![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)
 
-## 🌟 Features
+</div>
 
-- **Project Management**
-  - Open existing CODESYS projects (`open_project`)
-  - Create new projects from standard templates (`create_project`)
-  - Save project changes (`save_project`)
+An [MCP](https://modelcontextprotocol.io) server that keeps one CODESYS session
+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.
 
-- **POU Management**
-  - Create Programs, Function Blocks, and Functions (`create_pou`)
-  - Set declaration and implementation code (`set_pou_code`)
-  - Create properties for Function Blocks (`create_property`)
-  - Create methods for Function Blocks (`create_method`)
-  - Compile projects (`compile_project`)
+![The live workspace, showing a sample project with a change waiting for review](docs/images/workspace.png)
 
-- **Session Management** (New!)
-  - Start a persistent CODESYS session (`start_session`)
-  - Execute multiple operations without restarting CODESYS
-  - Check session status (`session_status`)
-  - Close the session when finished (`stop_session`)
-  - See [Session Management Documentation](docs/session_management.md) for details
+## Highlights
 
-- **MCP Resources**
-  - `codesys://project/status`: Check scripting status and currently open project state.
-  - `codesys://project/{+project_path}/structure`: Retrieve the object structure of a specified project.
-  - `codesys://project/{+project_path}/pou/{+pou_path}/code`: Read the declaration and implementation code for a specified POU, Method, or Property accessor.
+- **Edits your real project.** POUs, methods, properties, interfaces, DUTs and
+  GVLs, as Structured Text.
+- **Compiles with the real compiler.** Errors come back with object, line and
+  code, including in code that no task calls yet.
+- **Tests in simulation.** Run, step exact cycles, read, write and force values
+  in CODESYS's own simulation, with nothing else to install.
+- **Understands the project.** Outlines, I/O lists, the device tree and library
+  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.
+- **Never touches a real controller.** The only online connection is to
+  CODESYS's own simulation, and every online call checks for it first.
 
-## 📋 Prerequisites
+## Quick start
 
-- **CODESYS V3**: A working CODESYS V3 installation (tested with 3.5 SP21) with the **Scripting Engine** component enabled during installation.
-- **Node.js**: Version 18.0.0 or later is recommended.
-- **MCP Client**: An MCP-enabled application (e.g., Claude Desktop).
+### Requirements
 
-*(Note: CODESYS uses Python 2.7 internally for its scripting engine, but this toolkit handles the interaction; you do not need to manage Python separately.)*
+- Windows with **CODESYS V3.5** and its **Scripting** add-on. Tested with SP21
+  and SP22 on Scripting 4.2, and SP21 on 4.1. SP16 and later should work.
+- **Node.js 20** or later.
 
-## 🚀 Installation
+Schneider EcoStruxure Machine Expert isn't supported yet. If you have it, the
+[testing notes](docs/machine-expert-testing.md) help find out what works.
 
-The recommended way to install is globally using npm:
+### Install
 
 ```bash
-npm install -g @codesys/mcp-toolkit
+npm install -g @codesys/mcp-toolkit@next
 ```
 
-This installs the package globally, making the `codesys-mcp-tool` command available in your system's terminal PATH.
+Version 2 is in alpha, so it's published under the `next` tag. Without `@next`,
+npm installs version 1.
 
-*(Advanced users can also install from source for development - see CONTRIBUTING.md if available).*
+### Connect it to Claude Desktop
 
-## 🔧 Configuration (IMPORTANT!)
-
-This toolkit needs to know where your CODESYS installation is and which profile to use. Configuration is typically done within your MCP Client application (like Claude Desktop).
-
-### Recommended Configuration Method (Direct Command)
-
-Due to potential environment variable issues (especially with `PATH`) when launching Node.js tools via wrappers like `npx` within certain host applications (e.g., Claude Desktop), it is **strongly recommended** to configure your MCP client to run the installed command `codesys-mcp-tool` **directly**.
-
-**Example for Claude Desktop (`settings.json` -> `mcpServers`):**
+Add the server to `%APPDATA%\Claude\claude_desktop_config.json`, then restart
+Claude Desktop:
 
 ```json
 {
   "mcpServers": {
-    // ... other servers ...
-    "codesys_local": {
-      "command": "codesys-mcp-tool", // <<< Use the direct command name
+    "codesys": {
+      "command": "codesys-mcp-tool",
       "args": [
-        // Pass arguments directly to the tool using flags
-        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "Your CODESYS Profile Name"
-        // Optional: Add --workspace "/path/to/your/projects" if needed
+        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
+        "--codesys-profile", "CODESYS V3.5 SP21",
+        "--workspace", "C:\\PLC\\Projects"
       ]
     }
-    // ... other servers ...
   }
 }
 ```
 
-**Key Steps:**
-1.  Replace `"C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe"` with the **full, correct path** to your specific `CODESYS.exe` file.
-2.  Replace `"Your CODESYS Profile Name"` with the **exact name** of the CODESYS profile you want to use (visible in the CODESYS UI).
-3.  Ensure the `codesys-mcp-tool` command is accessible in the system PATH where the MCP Client application runs. Global installation via `npm install -g` usually handles this.
-4.  Restart your MCP Client application (e.g., Claude Desktop) to apply the settings changes.
+`--codesys-path` and `--codesys-profile` are optional. Without them the server
+uses the newest CODESYS install under Program Files and its newest profile.
+
+### Try it
+
+> Create a project called `BlinkDemo.project`. Add a function block that toggles
+> an output once per second, call it from `PLC_PRG`, compile it, and prove in
+> simulation that the output toggles.
+
+CODESYS starts in the background when the server launches. A cold start takes
+1 to 3 minutes; later starts take about 10 seconds.
+
+Claude Desktop asks for approval per tool. Choose **Always allow** the first
+time it asks about `codesys`, and once more for `open_sim_panel`. After that it
+doesn't ask again.
+
+## What Claude can do
+
+Everything goes through one MCP tool, `codesys`, with an action for each
+operation. [The reference](docs/reference.md) describes each one.
+
+| Area | Actions |
+| --- | --- |
+| **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` |
+| **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` |
+| **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` |
+| **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.
+
+## Live panel
+
+Right after opening or creating a project, Claude opens the panel as a card in
+the chat. It shows the status, the object Claude is working on and how many
+objects changed. **Open workspace** expands it into a CODESYS-style view with
+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 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
+([anthropics/claude-ai-mcp#1243](https://github.com/anthropics/claude-ai-mcp/issues/1243)).
+Ask Claude to open the workspace in your browser if you'd rather have it there;
+the browser never opens by itself.
+
+[More about the panel](docs/reference.md#live-panel)
+
+## Safety
+
+- **No real controller.** The toolkit doesn't log in or download to a
+  controller. It goes online only to CODESYS's own simulation, and every online
+  call first checks that simulation mode is on.
+- **One approval covers every action.** That includes the actions that change
+  or delete project code, so work on a copy of any project you can't afford to
+  lose, or keep it in version control.
+- **Changes can be undone.** A checkpoint is taken when a project is opened, and
+  `revert_object` puts an object back to it, including its methods and
+  properties.
+- **Saved as it goes.** The project is saved after every change by default. Use
+  `--no-autosave` to save only on request.
+- **The simulation can't change your project.** Editing is refused while it
+  runs, and the simulation setting on the device is never saved.
+
+## Configuration
+
+| Option | Meaning |
+| --- | --- |
+| `--codesys-path <exe>` | `CODESYS.exe` to run |
+| `--codesys-profile <name>` | Profile, e.g. `"CODESYS V3.5 SP21"` (file name in `CODESYS\Profiles`, without `.profile.xml`). A name that isn't installed is refused at start, with the installed ones listed |
+| `--codesys-additional-folder <dir>` | CODESYS's add-on folder, passed as `--additionalfolder`. SP22 installs add-ons such as Scripting there; the toolkit finds `CODESYS\AdditionalFolders\Default` by itself |
+| `--workspace <dir>` | Base folder for relative project paths (default: the working directory). Created if missing |
+| `--project <file>` | Open this project as soon as CODESYS is up |
+| `--session-dir <dir>` | Where session folders go (default: `%TEMP%\codesys-mcp-toolkit`) |
+| `--no-autostart` | Start CODESYS on the first tool call instead of at launch |
+| `--no-autosave` | Don't save after every change; use `save_project` |
+| `--viewer-port <port>` | Port of the browser workspace on 127.0.0.1 (default 5180, or the next free one) |
+| `--no-viewer` | Don't serve the browser workspace |
+| `--no-shared` | Run CODESYS in this process instead of the shared session |
+
+### Several CODESYS versions
+
+To keep SP21 and SP22 side by side, add one server entry per version, each with
+its own `--codesys-path` and `--codesys-profile`.
+
+The toolkit never updates a project's compiler or library versions, and
+`open_project` says when they differ from the running CODESYS. A project that
+needs a newer compiler opens, but can't compile until you open it in that
+version. Each version keeps its own devices and libraries, so a project from an
+older CODESYS may report missing libraries until you update it in the CODESYS
+window.
+
+### Shared session
+
+Claude Desktop may start the server more than once. All processes started with
+the same options share one background session, so only one CODESYS runs and the
+panel shows the project Claude is working on. The session stops two minutes
+after the last client disconnects. Its log is `daemon-<id>.log` in
+`%LOCALAPPDATA%\codesys-mcp-toolkit`.
+
+## How it works
 
-### Alternative Configuration (Using `npx` - Not Recommended)
+```
+MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
+                            │   requests/<id>.json  ▶  operation name + JSON arguments
+                            │   ◀  results/<id>.json
+                            │   ◀  heartbeat.json      idle or busy, with a deadline
+                            ▼
+                        CODESYS.exe --noUI --runscript=watcher.py
+                            └─ fixed operation handlers (IronPython 2.7)
+```
 
-Launching with `npx` has been observed to cause immediate errors (`'C:\Program' is not recognized...`) in some environments, likely due to how `npx` handles the execution environment. **Use the Direct Command method above if possible.** If you must use `npx`:
+- **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
+  blocks past it, the server kills it and starts a fresh one on the next call.
+- **No orphans.** The watcher exits when the server process goes away.
+- **Modal dialogs** are suppressed and logged, so they can't freeze CODESYS.
+- **UTF-8** from end to end.
+- **Localised names.** Object kinds come from CODESYS type GUIDs, not names, so
+  a German task folder called `Taskkonfiguration` works.
 
-```json
-// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
-{
-  "mcpServers": {
-    "codesys_local": {
-      "command": "npx",
-      "args": [
-        "-y", // Tells npx to install temporarily if not found globally
-        "@codesys/mcp-toolkit",
-        // Arguments for the tool MUST come AFTER the package name
-        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
-        "--codesys-profile", "Your CODESYS Profile Name"
-      ]
-    }
-  }
-}
-```
-*(Note: The `--` separator after the package name might sometimes help `npx` but is not guaranteed to fix the environment issue.)*
+## Troubleshooting
 
-## 🛠️ Command-Line Arguments
+| Message | What to do |
+| --- | --- |
+| **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. |
 
-When running `codesys-mcp-tool` directly or configuring it, you can use these arguments:
+Each session folder keeps a `watcher.log`.
 
-*   `-p, --codesys-path <path>`: Full path to `CODESYS.exe`. (Required, overrides `CODESYS_PATH` env var, has a default but relying on it is not recommended).
-*   `-f, --codesys-profile <profile>`: Name of the CODESYS profile. (Required, overrides `CODESYS_PROFILE` env var, has a default but relying on it is not recommended).
-*   `-w, --workspace <dir>`: Workspace directory for resolving relative project paths passed to tools. Defaults to the directory where the command was launched (which might be unpredictable when run by another application). Setting this explicitly might be needed if using relative paths.
-*   `-h, --help`: Show help message.
-*   `--version`: Show package version.
+## Development
 
-## 🔍 Troubleshooting
+```bash
+npm install
+npm test                                    # unit, bridge and tool tests (no CODESYS needed)
+CODESYS_LIVE=1 npx vitest run test/live     # end-to-end against your CODESYS
+npm run build                               # server and the single-file panel
+```
+
+The normal tests run the real watcher under CPython 3 against a fake
+`scriptengine` (`test/fake/`). Watcher code must stay valid IronPython 2.7:
+ASCII-only, no f-strings.
+
+To work on the panel without Claude Desktop, run the dev host, then open
+http://localhost:5199:
+
+```bash
+npm run build:panel && node scripts/dev-host/run.mjs 5199
+```
 
-*   **`'C:\Program' is not recognized...` error immediately after connection:**
-    *   **Cause:** This typically happens when the tool is launched via `npx` within an environment like Claude Desktop. The execution environment (`PATH` variable) provided to the process likely causes an internal CODESYS command (like running Python) to fail.
-    *   **Solution:** Configure your MCP Client to run the command **directly** (`"command": "codesys-mcp-tool"`) instead of using `"command": "npx"`. See the **Recommended Configuration Method** section above.
+See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.
 
-*   **Tool Fails / Errors in Output:**
-    *   Check the logs from your MCP Client application (e.g., Claude Desktop logs). Look for `INTEROP:` messages or Python `DEBUG:` / `ERROR:` messages printed to stderr from the CODESYS script execution.
-    *   Ensure the `--codesys-path` and `--codesys-profile` arguments passed to the command are correct and point to a valid CODESYS installation with scripting enabled.
-    *   Verify the project paths and object paths you are passing to tools are correct (use forward slashes `/`).
-    *   Make sure no other CODESYS instances are running in conflicting ways (e.g., holding a lock on the profile).
+## Migrating from v1
 
-*   **`command not found: codesys-mcp-tool`:**
-    *   Ensure the package was installed globally (`npm install -g @codesys/mcp-toolkit`).
-    *   Ensure the npm global bin directory is in your system's `PATH` environment variable. Find it with `npm config get prefix` and add the `bin` subdirectory (or the main directory itself on Windows) to your PATH.
+- Everything is now an action of the one `codesys` tool.
+- Actions don't take `projectFilePath`. Call `open_project` once.
+- `create_pou`, `create_method` and `create_property` are now `create_object`
+  with a `kind`.
+- `set_pou_code` is now `write_object`.
+- `compile_project` is now `compile`, and it returns the errors.
+- Read access is through actions (`read_objects`, `get_project_tree`) instead of
+  resources, so it works in Claude Desktop
+  ([#6](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/6)).
 
-*   **Check Logs:**
-    *   Claude Desktop logs: `C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\` (Windows)
+## Acknowledgements
 
-## 🤝 Contributing
-Contributions, issues, and feature requests are welcome! Feel free to check the issues page. (Optionally add a CONTRIBUTING.md file with more details).
+The persistent-watcher design borrows ideas from
+[zbest1000/mcptoolkit-for-codesys](https://github.com/zbest1000/mcptoolkit-for-codesys)
+(op-handler registry, heartbeat, prompt handling) and
+[phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
+(file-queue IPC, version-safe opening). Both are MIT-licensed.
 
-## 📝 License
-This project is licensed under the MIT License - see the LICENSE file for details.
+## License
 
-## 🙏 Acknowledgements
-- The CODESYS GmbH team for the powerful CODESYS platform and its scripting engine.
-- The Model Context Protocol project for defining the interaction standard.
-- All contributors and users who help improve this toolkit.
+[MIT](LICENSE)
 
+CODESYS is a trademark of CODESYS GmbH. This project is independent and isn't
+affiliated with or endorsed by CODESYS GmbH.

package/dist/actions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Every CODESYS action behind one MCP tool, `codesys`.
+ *
+ * Claude Desktop asks for approval per tool, read-only or not, and remembers
+ * "Always allow" per tool. With one tool the user presses once. That press
+ * also covers writes and deletes, so the tool declares itself destructive.
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+export declare const TOOL_NAME = "codesys";
+export type ActionResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export interface ActionConfig<S extends z.ZodObject = z.ZodObject> {
+    description: string;
+    inputSchema: S;
+}
+export interface Action extends ActionConfig {
+    run: (args: unknown) => Promise<ActionResult>;
+}
+export type RegisterAction = <S extends z.ZodObject>(name: string, config: ActionConfig<S>, run: (args: z.infer<S>) => ActionResult | Promise<ActionResult>) => void;
+/** One action's description and arguments, as the model reads them. */
+export declare function usage(name: string, a: ActionConfig): string;
+export declare function registerActionTool(server: McpServer, actions: Map<string, Action>): void;

package/dist/actions.js

@@ -0,0 +1,98 @@
+import * as z from "zod/v4";
+export const TOOL_NAME = "codesys";
+const fields = (s) => {
+    const required = new Set(s.required ?? []);
+    return Object.entries(s.properties ?? {}).map(([k, p]) => [k, p, `${k}${required.has(k) ? "" : "?"}`]);
+};
+function typeName(s) {
+    if (s.enum)
+        return s.enum.map((v) => JSON.stringify(v)).join(" | ");
+    if (s.const !== undefined)
+        return JSON.stringify(s.const);
+    if (s.anyOf)
+        return s.anyOf.map(typeName).join(" | ");
+    if (Array.isArray(s.type))
+        return s.type.join(" | ");
+    if (s.type === "array")
+        return `${s.items ? typeName(s.items) : "any"}[]`;
+    if (s.type === "object" && s.properties)
+        return `{ ${fields(s).map(([, p, label]) => `${label}: ${typeName(p)}`).join(", ")} }`;
+    if (s.type === "object" && typeof s.additionalProperties === "object")
+        return `{ [name]: ${typeName(s.additionalProperties)} }`;
+    return s.type ?? "any";
+}
+/** One action's description and arguments, as the model reads them. */
+export function usage(name, a) {
+    const s = z.toJSONSchema(a.inputSchema, { io: "input" });
+    const params = fields(s).map(([, p, label]) => `  ${label}: ${typeName(p)}${p.description ? ` - ${p.description}` : ""}`);
+    return [`${name}: ${a.description}`, ...params].join("\n");
+}
+const HOW_TO_CALL = `Everything this toolkit does in CODESYS V3.5. Call it as {"action": "<name>", "args": {...}}, with the action's arguments in args. Leave args out when the action takes none. Example: {"action": "read_objects", "args": {"paths": ["PLC_PRG"]}}. Use batch to send several actions in one call: it is much faster than separate calls. Some actions change or delete project code. {"action": "help"} returns this list, and {"action": "help", "args": {"action": "write_object"}} one action, for when a client shortens this text.`;
+const MAX_BATCH = 50;
+const reply = (text, isError = false) => ({ content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) });
+// Strict: nothing else checks the arguments, and a misspelt optional one must not be dropped silently.
+const checkArgs = (a, args) => a.inputSchema.strict().safeParse(args ?? {});
+const batchInput = z.object({
+    calls: z.array(z.object({ action: z.string(), args: z.record(z.string(), z.unknown()).optional() })).min(1).max(MAX_BATCH).describe(`The steps, in order, at most ${MAX_BATCH}`),
+    continueOnError: z.boolean().optional().describe("Run the remaining steps after one fails (default false)"),
+});
+/** Most of a session's time is the round trip between calls, not CODESYS: this saves those. */
+function batchAction(actions) {
+    return {
+        description: "Run several actions in one call, in order, and get all their results back. Use this whenever you already know the next steps, for example several create_object or write_object calls and then compile, or a simulation step (codesys_sim_force, wait, codesys_sim_cycle, codesys_sim_read). Every step is checked first, and nothing runs if one is invalid. It stops at the first step that fails, unless continueOnError is true. A batch can't contain help or another batch.",
+        inputSchema: batchInput,
+        run: async (raw) => {
+            const { calls, continueOnError } = raw;
+            const steps = [];
+            for (const [i, c] of calls.entries()) {
+                const action = actions.get(c.action);
+                if (!action)
+                    return reply(`Step ${i + 1}: '${c.action}' can't run in a batch, so nothing was run. Actions: ${[...actions.keys()].join(", ")}.`, true);
+                const parsed = checkArgs(action, c.args);
+                if (!parsed.success)
+                    return reply(`Step ${i + 1} (${c.action}) has invalid arguments, so nothing was run:\n${z.prettifyError(parsed.error)}\n\n${usage(c.action, action)}`, true);
+                steps.push({ name: c.action, action, args: parsed.data });
+            }
+            const out = [];
+            let failed = false;
+            for (const [i, s] of steps.entries()) {
+                const r = await s.action.run(s.args);
+                out.push(`[${i + 1}/${steps.length}] ${s.name}${r.isError ? " FAILED" : ""}:\n${r.content.map((c) => c.text).join("\n")}`);
+                failed ||= !!r.isError;
+                if (r.isError && !continueOnError) {
+                    if (i + 1 < steps.length)
+                        out.push(`Stopped: the remaining ${steps.length - i - 1} step(s) were not run.`);
+                    break;
+                }
+            }
+            return reply(out.join("\n\n"), failed);
+        },
+    };
+}
+export function registerActionTool(server, actions) {
+    const all = new Map([["batch", batchAction(actions)], ...actions]);
+    const names = [...all.keys()];
+    const catalog = names.map((n) => usage(n, all.get(n))).join("\n\n");
+    server.registerTool(TOOL_NAME, {
+        description: `${HOW_TO_CALL}\n\nActions:\n\n${catalog}`,
+        inputSchema: z.object({
+            action: z.enum(["help", ...names]).describe("The action to run"),
+            args: z.record(z.string(), z.unknown()).optional().describe("The action's arguments, as listed for it in this tool's description"),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ action, args }) => {
+        if (action === "help") {
+            if (args?.action === undefined)
+                return reply(catalog);
+            const wanted = String(args.action);
+            const known = all.get(wanted);
+            return known ? reply(usage(wanted, known)) : reply(`Unknown action '${wanted}'. Actions: ${names.join(", ")}.`, true);
+        }
+        const a = all.get(action);
+        const parsed = checkArgs(a, args);
+        if (!parsed.success)
+            return reply(`Invalid arguments for ${action}:\n${z.prettifyError(parsed.error)}\n\n${usage(action, a)}`, true);
+        return a.run(parsed.data);
+    });
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/bridge/bridge.d.ts

@@ -0,0 +1,105 @@
+export interface BridgeOptions {
+    /** Executable: CODESYS.exe in production, python in tests. */
+    command: string;
+    /** Full argument list; when omitted, CODESYS arguments are built from profile/noUI. */
+    args?: (scriptPath: string) => string[];
+    profile?: string;
+    /** CODESYS's additional folder (SP22 keeps its add-ons there, e.g. Scripting). */
+    additionalFolder?: string;
+    /** Run CODESYS without UI (default true). */
+    noUI?: boolean;
+    /** Folder that holds watcher.py and its modules (copied into the session). */
+    watcherSource: string;
+    /** Base folder for session folders. */
+    sessionRoot: string;
+    /** Extra environment (tests point PYTHONPATH at a fake scriptengine). */
+    env?: Record<string, string>;
+    startupTimeoutMs?: number;
+    defaultTimeoutMs?: number;
+    /** Extra time after a busy op's deadline before the watcher counts as hung. */
+    hungGraceMs?: number;
+    /** An idle heartbeat older than this means the watcher is hung. */
+    staleHeartbeatMs?: number;
+    log?: (msg: string) => void;
+}
+export type BridgeState = "stopped" | "starting" | "ready" | "dead";
+export interface Heartbeat {
+    pid: number;
+    ts: number;
+    state: "idle" | "busy" | "stopped" | "crashed";
+    op?: string | null;
+    id?: string | null;
+    deadline?: number | null;
+    count?: number;
+}
+export interface BridgeHealth {
+    state: BridgeState;
+    pid?: number;
+    sessionDir?: string;
+    startedAt?: string;
+    readyAfterMs?: number;
+    heartbeat?: Heartbeat & {
+        ageMs: number;
+    };
+    verdict: "healthy" | "busy" | "hung" | "dead" | "starting" | "stopped";
+    /** Version of the CODESYS Scripting add-on, once CODESYS has started. */
+    scripting?: string;
+    calls: number;
+    lastError?: string;
+    restarts: number;
+}
+export declare class BridgeError extends Error {
+    code: string;
+    detail?: string | undefined;
+    constructor(code: string, message: string, detail?: string | undefined);
+}
+/** What to do about a start-up failure CODESYS explains in its output. */
+export declare function startupHint(output: string): string;
+export declare class CodesysBridge {
+    private opts;
+    private child?;
+    private state;
+    private startPromise?;
+    private sessionDir?;
+    private queue;
+    private seq;
+    private calls;
+    private restarts;
+    private startedAt?;
+    private readyAt?;
+    private scripting?;
+    private lastError?;
+    private exitInfo?;
+    /** The end of CODESYS's own console output (for start-up errors). */
+    private output;
+    constructor(options: BridgeOptions);
+    get currentState(): BridgeState;
+    /** Start CODESYS + watcher (idempotent). Resolves when the watcher is ready. */
+    start(): Promise<void>;
+    /** Wait at most `ms` for the bridge to be ready; false if still starting. */
+    waitReady(ms: number): Promise<boolean>;
+    private doStart;
+    /** Run one watcher op. Calls are serialised; the watcher is single-threaded. */
+    call<T = unknown>(op: string, args?: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    private exchange;
+    readHeartbeat(): (Heartbeat & {
+        ageMs: number;
+    }) | undefined;
+    /** The end of what the program printed, for error messages. */
+    private consoleTail;
+    /** The title of a dialog the watcher found CODESYS waiting on (dialog.json). */
+    private pendingDialog;
+    private verdict;
+    /** Snapshot that never waits on the watcher. */
+    health(): BridgeHealth;
+    /** Ask the watcher to exit, then make sure the process is gone. */
+    stop(): Promise<void>;
+    private kill;
+    /** Last lines of watcher.log, for error messages. */
+    logTail(lines?: number): string;
+    private log;
+}
+/** Remove session folders older than `maxAgeMs` (our own folders only). */
+export declare function pruneSessions(root: string, maxAgeMs?: number): Promise<void>;