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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +1 -1
  2. package/README.md +269 -269
  3. package/dist/server.d.ts +1 -1
  4. package/dist/server.js +1 -1
  5. package/dist/server.js.map +1 -1
  6. package/package.json +66 -67
package/CHANGELOG.md CHANGED
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [2.0.0-alpha.0] - unreleased
8
+ ## [2.0.0] - 2026-11-09
9
9
 
10
10
  Rewrite. See README "Migrating from v1".
11
11
 
package/README.md CHANGED
@@ -1,269 +1,269 @@
1
- <div align="center">
2
-
3
- # CODESYS MCP Toolkit
4
-
5
- **Let Claude read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
6
-
7
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
8
- ![Status: 2.0 alpha](https://img.shields.io/badge/status-2.0%20alpha-orange)
9
- ![CODESYS V3.5](https://img.shields.io/badge/CODESYS-V3.5-c8102e)
10
- ![Node.js 20 or later](https://img.shields.io/badge/node-%E2%89%A520-339933)
11
- ![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078d4)
12
- [![Model Context Protocol](https://img.shields.io/badge/MCP-server-6e56cf)](https://modelcontextprotocol.io)
13
-
14
- </div>
15
-
16
- An [MCP](https://modelcontextprotocol.io) server that keeps one CODESYS session
17
- open in the background and gives Claude, or any MCP client, direct access to
18
- it. Claude works on your real project with the real CODESYS compiler, and you
19
- can watch the code change as it happens.
20
-
21
- ![The live workspace, showing a sample project with a change waiting for review](docs/images/workspace.png)
22
-
23
- ## Highlights
24
-
25
- - **Edits your real project.** POUs, methods, properties, interfaces, DUTs and
26
- GVLs, as Structured Text.
27
- - **Compiles with the real compiler.** Errors come back with object, line and
28
- code, including in code that no task calls yet.
29
- - **Tests in simulation.** Run, step exact cycles, read, write and force values
30
- in CODESYS's own simulation, with nothing else to install.
31
- - **Understands the project.** Outlines, I/O lists, the device tree and library
32
- interfaces, without reading every object.
33
- - **Shows its work.** A live panel with the project tree, the code as it is
34
- written, compile results, and Accept or Revert for each change.
35
- - **Never touches a real controller.** The only online connection is to
36
- CODESYS's own simulation, and every online call checks for it first.
37
-
38
- ## Quick start
39
-
40
- ### Requirements
41
-
42
- - Windows with **CODESYS V3.5** and its **Scripting** add-on. Tested with SP21
43
- and SP22 on Scripting 4.2, and SP21 on 4.1. SP16 and later should work.
44
- - **Node.js 20** or later.
45
-
46
- Schneider EcoStruxure Machine Expert isn't supported yet. If you have it, the
47
- [testing notes](docs/machine-expert-testing.md) help find out what works.
48
-
49
- ### Install
50
-
51
- ```bash
52
- npm install -g @codesys/mcp-toolkit@next
53
- ```
54
-
55
- Version 2 is in alpha, so it's published under the `next` tag. Without `@next`,
56
- npm installs version 1.
57
-
58
- ### Connect it to Claude Desktop
59
-
60
- Add the server to `%APPDATA%\Claude\claude_desktop_config.json`, then restart
61
- Claude Desktop:
62
-
63
- ```json
64
- {
65
- "mcpServers": {
66
- "codesys": {
67
- "command": "codesys-mcp-tool",
68
- "args": [
69
- "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
70
- "--codesys-profile", "CODESYS V3.5 SP21",
71
- "--workspace", "C:\\PLC\\Projects"
72
- ]
73
- }
74
- }
75
- }
76
- ```
77
-
78
- `--codesys-path` and `--codesys-profile` are optional. Without them the server
79
- uses the newest CODESYS install under Program Files and its newest profile.
80
-
81
- ### Try it
82
-
83
- > Create a project called `BlinkDemo.project`. Add a function block that toggles
84
- > an output once per second, call it from `PLC_PRG`, compile it, and prove in
85
- > simulation that the output toggles.
86
-
87
- CODESYS starts in the background when the server launches. A cold start takes
88
- 1 to 3 minutes; later starts take about 10 seconds.
89
-
90
- Claude Desktop asks for approval per tool. Choose **Always allow** the first
91
- time it asks about `codesys`, and once more for `open_sim_panel`. After that it
92
- doesn't ask again.
93
-
94
- ## What Claude can do
95
-
96
- Everything goes through one MCP tool, `codesys`, with an action for each
97
- operation. [The reference](docs/reference.md) describes each one.
98
-
99
- | Area | Actions |
100
- | --- | --- |
101
- | **Projects** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
102
- | **Read code** | `get_project_tree` `read_objects` `search_code` `get_outline` |
103
- | **Change code** | `write_object` `create_object` `delete_object` `rename_object` |
104
- | **Build** | `compile` |
105
- | **Libraries** | `list_libraries` `add_library` `remove_library` `get_library_api` |
106
- | **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` |
107
- | **Change tracking** | `checkpoint` `get_changes` `revert_object` |
108
- | **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` |
109
- | **Helpers** | `batch` `wait` `help` `open_workspace` |
110
-
111
- `batch` runs up to 50 actions in one call, which is much faster than separate
112
- calls.
113
-
114
- Version 2 edits Structured Text only. Objects with graphical bodies (SFC, CFC,
115
- LD, FBD) appear in the tree and can be read as PLCopenXML, but not edited.
116
-
117
- ## Live panel
118
-
119
- Right after opening or creating a project, Claude opens the panel as a card in
120
- the chat. It shows the status, the object Claude is working on and how many
121
- objects changed. **Open workspace** expands it into a CODESYS-style view with
122
- the project tree, editor tabs, compile problems and a review list.
123
-
124
- From the panel you can **Accept** or **Revert** each change, compare it with
125
- the version you last reviewed, and **Pause Claude** while you look around.
126
-
127
- The card needs a client that supports
128
- [MCP Apps](https://modelcontextprotocol.io/extensions/apps). In our testing
129
- Claude Desktop draws it in the Code tab but not in a normal chat
130
- ([anthropics/claude-ai-mcp#1243](https://github.com/anthropics/claude-ai-mcp/issues/1243)).
131
- Ask Claude to open the workspace in your browser if you'd rather have it there;
132
- the browser never opens by itself.
133
-
134
- [More about the panel](docs/reference.md#live-panel)
135
-
136
- ## Safety
137
-
138
- - **No real controller.** The toolkit doesn't log in or download to a
139
- controller. It goes online only to CODESYS's own simulation, and every online
140
- call first checks that simulation mode is on.
141
- - **One approval covers every action.** That includes the actions that change
142
- or delete project code, so work on a copy of any project you can't afford to
143
- lose, or keep it in version control.
144
- - **Changes can be undone.** A checkpoint is taken when a project is opened, and
145
- `revert_object` puts an object back to it, including its methods and
146
- properties.
147
- - **Saved as it goes.** The project is saved after every change by default. Use
148
- `--no-autosave` to save only on request.
149
- - **The simulation can't change your project.** Editing is refused while it
150
- runs, and the simulation setting on the device is never saved.
151
-
152
- ## Configuration
153
-
154
- | Option | Meaning |
155
- | --- | --- |
156
- | `--codesys-path <exe>` | `CODESYS.exe` to run |
157
- | `--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 |
158
- | `--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 |
159
- | `--workspace <dir>` | Base folder for relative project paths (default: the working directory). Created if missing |
160
- | `--project <file>` | Open this project as soon as CODESYS is up |
161
- | `--session-dir <dir>` | Where session folders go (default: `%TEMP%\codesys-mcp-toolkit`) |
162
- | `--no-autostart` | Start CODESYS on the first tool call instead of at launch |
163
- | `--no-autosave` | Don't save after every change; use `save_project` |
164
- | `--viewer-port <port>` | Port of the browser workspace on 127.0.0.1 (default 5180, or the next free one) |
165
- | `--no-viewer` | Don't serve the browser workspace |
166
- | `--no-shared` | Run CODESYS in this process instead of the shared session |
167
-
168
- ### Several CODESYS versions
169
-
170
- To keep SP21 and SP22 side by side, add one server entry per version, each with
171
- its own `--codesys-path` and `--codesys-profile`.
172
-
173
- The toolkit never updates a project's compiler or library versions, and
174
- `open_project` says when they differ from the running CODESYS. A project that
175
- needs a newer compiler opens, but can't compile until you open it in that
176
- version. Each version keeps its own devices and libraries, so a project from an
177
- older CODESYS may report missing libraries until you update it in the CODESYS
178
- window.
179
-
180
- ### Shared session
181
-
182
- Claude Desktop may start the server more than once. All processes started with
183
- the same options share one background session, so only one CODESYS runs and the
184
- panel shows the project Claude is working on. The session stops two minutes
185
- after the last client disconnects. Its log is `daemon-<id>.log` in
186
- `%LOCALAPPDATA%\codesys-mcp-toolkit`.
187
-
188
- ## How it works
189
-
190
- ```
191
- MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
192
- │ requests/<id>.json ▶ operation name + JSON arguments
193
- │ ◀ results/<id>.json
194
- │ ◀ heartbeat.json idle or busy, with a deadline
195
- ▼
196
- CODESYS.exe --noUI --runscript=watcher.py
197
- └─ fixed operation handlers (IronPython 2.7)
198
- ```
199
-
200
- - **No generated code.** Requests are an operation name plus JSON arguments,
201
- handled by fixed functions in `watcher/mcp_ops.py`.
202
- - **Hang detection.** The watcher reports `busy` with a deadline. If CODESYS
203
- blocks past it, the server kills it and starts a fresh one on the next call.
204
- - **No orphans.** The watcher exits when the server process goes away.
205
- - **Modal dialogs** are suppressed and logged, so they can't freeze CODESYS.
206
- - **UTF-8** from end to end.
207
- - **Localised names.** Object kinds come from CODESYS type GUIDs, not names, so
208
- a German task folder called `Taskkonfiguration` works.
209
-
210
- ## Troubleshooting
211
-
212
- | Message | What to do |
213
- | --- | --- |
214
- | **CODESYS is still starting** | The first start after boot can take minutes. Check `codesys_status`, then try again. |
215
- | **`startup_failed`** or **`startup_timeout`** | Check the profile name and that CODESYS starts by hand. The error includes the last lines of `watcher.log`. |
216
- | **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. |
217
- | **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. |
218
- | **`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. |
219
-
220
- Each session folder keeps a `watcher.log`.
221
-
222
- ## Development
223
-
224
- ```bash
225
- npm install
226
- npm test # unit, bridge and tool tests (no CODESYS needed)
227
- CODESYS_LIVE=1 npx vitest run test/live # end-to-end against your CODESYS
228
- npm run build # server and the single-file panel
229
- ```
230
-
231
- The normal tests run the real watcher under CPython 3 against a fake
232
- `scriptengine` (`test/fake/`). Watcher code must stay valid IronPython 2.7:
233
- ASCII-only, no f-strings.
234
-
235
- To work on the panel without Claude Desktop, run the dev host, then open
236
- http://localhost:5199:
237
-
238
- ```bash
239
- npm run build:panel && node scripts/dev-host/run.mjs 5199
240
- ```
241
-
242
- See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.
243
-
244
- ## Migrating from v1
245
-
246
- - Everything is now an action of the one `codesys` tool.
247
- - Actions don't take `projectFilePath`. Call `open_project` once.
248
- - `create_pou`, `create_method` and `create_property` are now `create_object`
249
- with a `kind`.
250
- - `set_pou_code` is now `write_object`.
251
- - `compile_project` is now `compile`, and it returns the errors.
252
- - Read access is through actions (`read_objects`, `get_project_tree`) instead of
253
- resources, so it works in Claude Desktop
254
- ([#6](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/6)).
255
-
256
- ## Acknowledgements
257
-
258
- The persistent-watcher design borrows ideas from
259
- [zbest1000/mcptoolkit-for-codesys](https://github.com/zbest1000/mcptoolkit-for-codesys)
260
- (op-handler registry, heartbeat, prompt handling) and
261
- [phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
262
- (file-queue IPC, version-safe opening). Both are MIT-licensed.
263
-
264
- ## License
265
-
266
- [MIT](LICENSE)
267
-
268
- CODESYS is a trademark of CODESYS GmbH. This project is independent and isn't
269
- affiliated with or endorsed by CODESYS GmbH.
1
+ <div align="center">
2
+
3
+ # CODESYS MCP Toolkit
4
+
5
+ **Let Claude read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
6
+
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
8
+ [![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)](https://www.npmjs.com/package/@codesys/mcp-toolkit)
9
+ ![CODESYS V3.5](https://img.shields.io/badge/CODESYS-V3.5-c8102e)
10
+ ![Node.js 20 or later](https://img.shields.io/badge/node-%E2%89%A520-339933)
11
+ ![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078d4)
12
+ [![Model Context Protocol](https://img.shields.io/badge/MCP-server-6e56cf)](https://modelcontextprotocol.io)
13
+
14
+ </div>
15
+
16
+ An [MCP](https://modelcontextprotocol.io) server that keeps one CODESYS session
17
+ open in the background and gives Claude, or any MCP client, direct access to
18
+ it. Claude works on your real project with the real CODESYS compiler, and you
19
+ can watch the code change as it happens.
20
+
21
+ ![The live workspace, showing a sample project with a change waiting for review](docs/images/workspace.png)
22
+
23
+ ## Highlights
24
+
25
+ - **Edits your real project.** POUs, methods, properties, interfaces, DUTs and
26
+ GVLs, as Structured Text.
27
+ - **Compiles with the real compiler.** Errors come back with object, line and
28
+ code, including in code that no task calls yet.
29
+ - **Tests in simulation.** Run, step exact cycles, read, write and force values
30
+ in CODESYS's own simulation, with nothing else to install.
31
+ - **Understands the project.** Outlines, I/O lists, the device tree and library
32
+ interfaces, without reading every object.
33
+ - **Shows its work.** A live panel with the project tree, the code as it is
34
+ written, compile results, and Accept or Revert for each change.
35
+ - **Never touches a real controller.** The only online connection is to
36
+ CODESYS's own simulation, and every online call checks for it first.
37
+
38
+ ## Quick start
39
+
40
+ ### Requirements
41
+
42
+ - Windows with **CODESYS V3.5** and its **Scripting** add-on. Tested with SP21
43
+ and SP22 on Scripting 4.2, and SP21 on 4.1. SP16 and later should work.
44
+ - **Node.js 20** or later.
45
+
46
+ Schneider EcoStruxure Machine Expert isn't supported yet. If you have it, the
47
+ [testing notes](docs/machine-expert-testing.md) help find out what works.
48
+
49
+ ### Install
50
+
51
+ ```bash
52
+ npm install -g @codesys/mcp-toolkit
53
+ ```
54
+
55
+ Coming from version 1? The tools have changed: see
56
+ [Migrating from v1](#migrating-from-v1).
57
+
58
+ ### Connect it to Claude Desktop
59
+
60
+ Add the server to `%APPDATA%\Claude\claude_desktop_config.json`, then restart
61
+ Claude Desktop:
62
+
63
+ ```json
64
+ {
65
+ "mcpServers": {
66
+ "codesys": {
67
+ "command": "codesys-mcp-tool",
68
+ "args": [
69
+ "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
70
+ "--codesys-profile", "CODESYS V3.5 SP21",
71
+ "--workspace", "C:\\PLC\\Projects"
72
+ ]
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ `--codesys-path` and `--codesys-profile` are optional. Without them the server
79
+ uses the newest CODESYS install under Program Files and its newest profile.
80
+
81
+ ### Try it
82
+
83
+ > Create a project called `BlinkDemo.project`. Add a function block that toggles
84
+ > an output once per second, call it from `PLC_PRG`, compile it, and prove in
85
+ > simulation that the output toggles.
86
+
87
+ CODESYS starts in the background when the server launches. A cold start takes
88
+ 1 to 3 minutes; later starts take about 10 seconds.
89
+
90
+ Claude Desktop asks for approval per tool. Choose **Always allow** the first
91
+ time it asks about `codesys`, and once more for `open_sim_panel`. After that it
92
+ doesn't ask again.
93
+
94
+ ## What Claude can do
95
+
96
+ Everything goes through one MCP tool, `codesys`, with an action for each
97
+ operation. [The reference](docs/reference.md) describes each one.
98
+
99
+ | Area | Actions |
100
+ | --- | --- |
101
+ | **Projects** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
102
+ | **Read code** | `get_project_tree` `read_objects` `search_code` `get_outline` |
103
+ | **Change code** | `write_object` `create_object` `delete_object` `rename_object` |
104
+ | **Build** | `compile` |
105
+ | **Libraries** | `list_libraries` `add_library` `remove_library` `get_library_api` |
106
+ | **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` |
107
+ | **Change tracking** | `checkpoint` `get_changes` `revert_object` |
108
+ | **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` |
109
+ | **Helpers** | `batch` `wait` `help` `open_workspace` |
110
+
111
+ `batch` runs up to 50 actions in one call, which is much faster than separate
112
+ calls.
113
+
114
+ Version 2 edits Structured Text only. Objects with graphical bodies (SFC, CFC,
115
+ LD, FBD) appear in the tree and can be read as PLCopenXML, but not edited.
116
+
117
+ ## Live panel
118
+
119
+ Right after opening or creating a project, Claude opens the panel as a card in
120
+ the chat. It shows the status, the object Claude is working on and how many
121
+ objects changed. **Open workspace** expands it into a CODESYS-style view with
122
+ the project tree, editor tabs, compile problems and a review list.
123
+
124
+ From the panel you can **Accept** or **Revert** each change, compare it with
125
+ the version you last reviewed, and **Pause Claude** while you look around.
126
+
127
+ The card needs a client that supports
128
+ [MCP Apps](https://modelcontextprotocol.io/extensions/apps). In our testing
129
+ Claude Desktop draws it in the Code tab but not in a normal chat
130
+ ([anthropics/claude-ai-mcp#1243](https://github.com/anthropics/claude-ai-mcp/issues/1243)).
131
+ Ask Claude to open the workspace in your browser if you'd rather have it there;
132
+ the browser never opens by itself.
133
+
134
+ [More about the panel](docs/reference.md#live-panel)
135
+
136
+ ## Safety
137
+
138
+ - **No real controller.** The toolkit doesn't log in or download to a
139
+ controller. It goes online only to CODESYS's own simulation, and every online
140
+ call first checks that simulation mode is on.
141
+ - **One approval covers every action.** That includes the actions that change
142
+ or delete project code, so work on a copy of any project you can't afford to
143
+ lose, or keep it in version control.
144
+ - **Changes can be undone.** A checkpoint is taken when a project is opened, and
145
+ `revert_object` puts an object back to it, including its methods and
146
+ properties.
147
+ - **Saved as it goes.** The project is saved after every change by default. Use
148
+ `--no-autosave` to save only on request.
149
+ - **The simulation can't change your project.** Editing is refused while it
150
+ runs, and the simulation setting on the device is never saved.
151
+
152
+ ## Configuration
153
+
154
+ | Option | Meaning |
155
+ | --- | --- |
156
+ | `--codesys-path <exe>` | `CODESYS.exe` to run |
157
+ | `--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 |
158
+ | `--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 |
159
+ | `--workspace <dir>` | Base folder for relative project paths (default: the working directory). Created if missing |
160
+ | `--project <file>` | Open this project as soon as CODESYS is up |
161
+ | `--session-dir <dir>` | Where session folders go (default: `%TEMP%\codesys-mcp-toolkit`) |
162
+ | `--no-autostart` | Start CODESYS on the first tool call instead of at launch |
163
+ | `--no-autosave` | Don't save after every change; use `save_project` |
164
+ | `--viewer-port <port>` | Port of the browser workspace on 127.0.0.1 (default 5180, or the next free one) |
165
+ | `--no-viewer` | Don't serve the browser workspace |
166
+ | `--no-shared` | Run CODESYS in this process instead of the shared session |
167
+
168
+ ### Several CODESYS versions
169
+
170
+ To keep SP21 and SP22 side by side, add one server entry per version, each with
171
+ its own `--codesys-path` and `--codesys-profile`.
172
+
173
+ The toolkit never updates a project's compiler or library versions, and
174
+ `open_project` says when they differ from the running CODESYS. A project that
175
+ needs a newer compiler opens, but can't compile until you open it in that
176
+ version. Each version keeps its own devices and libraries, so a project from an
177
+ older CODESYS may report missing libraries until you update it in the CODESYS
178
+ window.
179
+
180
+ ### Shared session
181
+
182
+ Claude Desktop may start the server more than once. All processes started with
183
+ the same options share one background session, so only one CODESYS runs and the
184
+ panel shows the project Claude is working on. The session stops two minutes
185
+ after the last client disconnects. Its log is `daemon-<id>.log` in
186
+ `%LOCALAPPDATA%\codesys-mcp-toolkit`.
187
+
188
+ ## How it works
189
+
190
+ ```
191
+ MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
192
+ │ requests/<id>.json ▶ operation name + JSON arguments
193
+ │ ◀ results/<id>.json
194
+ │ ◀ heartbeat.json idle or busy, with a deadline
195
+ ▼
196
+ CODESYS.exe --noUI --runscript=watcher.py
197
+ └─ fixed operation handlers (IronPython 2.7)
198
+ ```
199
+
200
+ - **No generated code.** Requests are an operation name plus JSON arguments,
201
+ handled by fixed functions in `watcher/mcp_ops.py`.
202
+ - **Hang detection.** The watcher reports `busy` with a deadline. If CODESYS
203
+ blocks past it, the server kills it and starts a fresh one on the next call.
204
+ - **No orphans.** The watcher exits when the server process goes away.
205
+ - **Modal dialogs** are suppressed and logged, so they can't freeze CODESYS.
206
+ - **UTF-8** from end to end.
207
+ - **Localised names.** Object kinds come from CODESYS type GUIDs, not names, so
208
+ a German task folder called `Taskkonfiguration` works.
209
+
210
+ ## Troubleshooting
211
+
212
+ | Message | What to do |
213
+ | --- | --- |
214
+ | **CODESYS is still starting** | The first start after boot can take minutes. Check `codesys_status`, then try again. |
215
+ | **`startup_failed`** or **`startup_timeout`** | Check the profile name and that CODESYS starts by hand. The error includes the last lines of `watcher.log`. |
216
+ | **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. |
217
+ | **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. |
218
+ | **`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. |
219
+
220
+ Each session folder keeps a `watcher.log`.
221
+
222
+ ## Development
223
+
224
+ ```bash
225
+ npm install
226
+ npm test # unit, bridge and tool tests (no CODESYS needed)
227
+ CODESYS_LIVE=1 npx vitest run test/live # end-to-end against your CODESYS
228
+ npm run build # server and the single-file panel
229
+ ```
230
+
231
+ The normal tests run the real watcher under CPython 3 against a fake
232
+ `scriptengine` (`test/fake/`). Watcher code must stay valid IronPython 2.7:
233
+ ASCII-only, no f-strings.
234
+
235
+ To work on the panel without Claude Desktop, run the dev host, then open
236
+ http://localhost:5199:
237
+
238
+ ```bash
239
+ npm run build:panel && node scripts/dev-host/run.mjs 5199
240
+ ```
241
+
242
+ See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.
243
+
244
+ ## Migrating from v1
245
+
246
+ - Everything is now an action of the one `codesys` tool.
247
+ - Actions don't take `projectFilePath`. Call `open_project` once.
248
+ - `create_pou`, `create_method` and `create_property` are now `create_object`
249
+ with a `kind`.
250
+ - `set_pou_code` is now `write_object`.
251
+ - `compile_project` is now `compile`, and it returns the errors.
252
+ - Read access is through actions (`read_objects`, `get_project_tree`) instead of
253
+ resources, so it works in Claude Desktop
254
+ ([#6](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/6)).
255
+
256
+ ## Acknowledgements
257
+
258
+ The persistent-watcher design borrows ideas from
259
+ [zbest1000/mcptoolkit-for-codesys](https://github.com/zbest1000/mcptoolkit-for-codesys)
260
+ (op-handler registry, heartbeat, prompt handling) and
261
+ [phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
262
+ (file-queue IPC, version-safe opening). Both are MIT-licensed.
263
+
264
+ ## License
265
+
266
+ [MIT](LICENSE)
267
+
268
+ CODESYS is a trademark of CODESYS GmbH. This project is independent and isn't
269
+ affiliated with or endorsed by CODESYS GmbH.
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { McpServer } from "@modelcontextprotocol/server";
2
2
  import { type AppContext } from "./tools.js";
3
- export declare const VERSION = "2.0.0-alpha.0";
3
+ export declare const VERSION = "2.0.0";
4
4
  export declare function createServer(ctx: AppContext): McpServer;
5
5
  export type { AppContext };
package/dist/server.js CHANGED
@@ -3,7 +3,7 @@ import { EXTENSION_ID } from "@modelcontextprotocol/ext-apps/server";
3
3
  import { currentCodesysSim } from "./codesys/simulation.js";
4
4
  import { registerTools, revertObject, versionLine } from "./tools.js";
5
5
  import { registerPanel } from "./panel.js";
6
- export const VERSION = "2.0.0-alpha.0";
6
+ export const VERSION = "2.0.0";
7
7
  const INSTRUCTIONS = `CODESYS V3.5 automation through a persistent CODESYS session.
8
8
  Everything goes through the one tool named codesys, as {"action": "<name>", "args": {...}}. The names below are its actions; {"action": "help"} lists them all with their arguments.
9
9
  Use batch whenever you know the next steps: it sends several actions in one call and is much faster than separate calls. For example, all the create_object and write_object calls of a step followed by compile, or codesys_sim_force, wait, codesys_sim_cycle and codesys_sim_read for one test.
package/dist/server.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAmB,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC;AAEvC,MAAM,YAAY,GAAG;;;;;;;;;yQASoP,CAAC;AAE1Q,MAAM,UAAU,YAAY,CAAC,GAAe;IAC1C,wFAAwF;IACxF,yEAAyE;IACzE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACtK,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,aAAa,CAAC,MAAM,EAAE;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI;QAChC,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC;QAC7G,UAAU,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC;QACxC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QACjD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KACzB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAmB,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,MAAM,YAAY,GAAG;;;;;;;;;yQASoP,CAAC;AAE1Q,MAAM,UAAU,YAAY,CAAC,GAAe;IAC1C,wFAAwF;IACxF,yEAAyE;IACzE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACtK,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,aAAa,CAAC,MAAM,EAAE;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI;QAChC,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC;QAC7G,UAAU,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC;QACxC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QACjD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KACzB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}
package/package.json CHANGED
@@ -1,67 +1,66 @@
1
- {
2
- "name": "@codesys/mcp-toolkit",
3
- "version": "2.0.0-alpha.0",
4
- "description": "MCP server for CODESYS V3.5: read, write and compile Structured Text through a persistent CODESYS session",
5
- "type": "module",
6
- "main": "dist/server.js",
7
- "bin": {
8
- "codesys-mcp-tool": "dist/cli.js"
9
- },
10
- "files": [
11
- "dist/",
12
- "watcher/",
13
- "README.md",
14
- "LICENSE",
15
- "CHANGELOG.md"
16
- ],
17
- "scripts": {
18
- "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
19
- "build": "npm run clean && tsc -p tsconfig.json && node scripts/build-panel.mjs",
20
- "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p panel/tsconfig.json",
21
- "test": "vitest run",
22
- "test:live": "vitest run test/live",
23
- "start": "node dist/cli.js",
24
- "build:panel": "node scripts/build-panel.mjs",
25
- "prepublishOnly": "npm run build"
26
- },
27
- "publishConfig": {
28
- "access": "public",
29
- "tag": "next"
30
- },
31
- "keywords": [
32
- "codesys",
33
- "mcp",
34
- "modelcontextprotocol",
35
- "plc",
36
- "iec-61131-3",
37
- "structured-text"
38
- ],
39
- "author": "Johannes Pettersson",
40
- "license": "MIT",
41
- "repository": {
42
- "type": "git",
43
- "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
44
- },
45
- "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
46
- "bugs": {
47
- "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
48
- },
49
- "engines": {
50
- "node": ">=20.0.0"
51
- },
52
- "os": [
53
- "win32"
54
- ],
55
- "dependencies": {
56
- "@modelcontextprotocol/ext-apps": "^2.0.4",
57
- "@modelcontextprotocol/server": "^2.4.0",
58
- "zod": "^4.2.0"
59
- },
60
- "devDependencies": {
61
- "@modelcontextprotocol/client": "^2.4.0",
62
- "@types/node": "^22.0.0",
63
- "esbuild": "^0.28.2",
64
- "typescript": "^7.0.2",
65
- "vitest": "^5.1.0"
66
- }
67
- }
1
+ {
2
+ "name": "@codesys/mcp-toolkit",
3
+ "version": "2.0.0",
4
+ "description": "MCP server for CODESYS V3.5: read, write and compile Structured Text through a persistent CODESYS session",
5
+ "type": "module",
6
+ "main": "dist/server.js",
7
+ "bin": {
8
+ "codesys-mcp-tool": "dist/cli.js"
9
+ },
10
+ "files": [
11
+ "dist/",
12
+ "watcher/",
13
+ "README.md",
14
+ "LICENSE",
15
+ "CHANGELOG.md"
16
+ ],
17
+ "scripts": {
18
+ "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
19
+ "build": "npm run clean && tsc -p tsconfig.json && node scripts/build-panel.mjs",
20
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p panel/tsconfig.json",
21
+ "test": "vitest run",
22
+ "test:live": "vitest run test/live",
23
+ "start": "node dist/cli.js",
24
+ "build:panel": "node scripts/build-panel.mjs",
25
+ "prepublishOnly": "npm run build"
26
+ },
27
+ "publishConfig": {
28
+ "access": "public"
29
+ },
30
+ "keywords": [
31
+ "codesys",
32
+ "mcp",
33
+ "modelcontextprotocol",
34
+ "plc",
35
+ "iec-61131-3",
36
+ "structured-text"
37
+ ],
38
+ "author": "Johannes Pettersson",
39
+ "license": "MIT",
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "git+https://github.com/johannesPettersson80/codesys-mcp-toolkit.git"
43
+ },
44
+ "homepage": "https://github.com/johannesPettersson80/codesys-mcp-toolkit#readme",
45
+ "bugs": {
46
+ "url": "https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues"
47
+ },
48
+ "engines": {
49
+ "node": ">=20.0.0"
50
+ },
51
+ "os": [
52
+ "win32"
53
+ ],
54
+ "dependencies": {
55
+ "@modelcontextprotocol/ext-apps": "^2.0.4",
56
+ "@modelcontextprotocol/server": "^2.4.0",
57
+ "zod": "^4.2.0"
58
+ },
59
+ "devDependencies": {
60
+ "@modelcontextprotocol/client": "^2.4.0",
61
+ "@types/node": "^22.0.0",
62
+ "esbuild": "^0.28.2",
63
+ "typescript": "^7.0.2",
64
+ "vitest": "^5.1.0"
65
+ }
66
+ }