@codesys/mcp-toolkit 2.0.0 → 2.1.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.
- package/CHANGELOG.md +28 -0
- package/README.md +293 -269
- package/dist/bridge/bridge.d.ts +12 -0
- package/dist/bridge/bridge.js +126 -3
- package/dist/bridge/bridge.js.map +1 -1
- package/dist/cli.js +20 -4
- package/dist/cli.js.map +1 -1
- package/dist/codesys/install.js +3 -2
- package/dist/codesys/install.js.map +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +10 -10
- package/dist/tools.d.ts +2 -0
- package/dist/tools.js +38 -7
- package/dist/tools.js.map +1 -1
- package/package.json +67 -66
- package/watcher/mcp_compat.py +35 -7
- package/watcher/mcp_sim.py +8 -0
- package/watcher/watcher.py +73 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,34 @@ 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.1.0] - 2026-11-13
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- `--attach <dir>` (experimental): work in a CODESYS / Machine Expert window you
|
|
12
|
+
already have open. The server writes `start_attach.py`; run it in the window
|
|
13
|
+
with Tools > Scripting > Execute Script File. A UI timer polls for requests, so
|
|
14
|
+
the window stays usable. Nothing is started or killed. (#12, thanks @dFxed)
|
|
15
|
+
- EcoStruxure Machine Expert V2.3 works: `LogicBuilder.exe` has no profiles, so
|
|
16
|
+
`--codesys-profile` is optional for products other than `CODESYS.exe` and
|
|
17
|
+
`--profile` is left out when there is none. CODESYS behaviour is unchanged.
|
|
18
|
+
(#7, #11, thanks @dFxed)
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
- `read_objects` says when the PLCopenXML export of a graphical object fails,
|
|
22
|
+
instead of leaving its body out without a word. (#13, thanks @Alfabete-spec)
|
|
23
|
+
- `codesys_sim_start` refuses when the application is already logged in, which
|
|
24
|
+
can happen in a window opened with `--attach`. It could otherwise have taken
|
|
25
|
+
over a connection to a real controller.
|
|
26
|
+
- A result file that stays unreadable fails the call after a few seconds
|
|
27
|
+
instead of being retried forever.
|
|
28
|
+
|
|
29
|
+
## [2.0.1] - 2026-11-10
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
- Listing in the official MCP Registry as
|
|
33
|
+
`io.github.johannesPettersson80/codesys-mcp-toolkit`: `mcpName` in
|
|
34
|
+
`package.json` and a `server.json`.
|
|
35
|
+
|
|
8
36
|
## [2.0.0] - 2026-11-09
|
|
9
37
|
|
|
10
38
|
Rewrite. See README "Migrating from v1".
|
package/README.md
CHANGED
|
@@ -1,269 +1,293 @@
|
|
|
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)
|
|
8
|
-
[](https://www.npmjs.com/package/@codesys/mcp-toolkit)
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
[](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
|
-
|
|
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
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
Claude
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
"
|
|
69
|
-
|
|
70
|
-
"--codesys-
|
|
71
|
-
"--
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
>
|
|
85
|
-
>
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
| **
|
|
103
|
-
| **
|
|
104
|
-
| **
|
|
105
|
-
| **
|
|
106
|
-
| **
|
|
107
|
-
| **
|
|
108
|
-
| **
|
|
109
|
-
| **
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
the
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
the browser
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
| `--codesys-
|
|
158
|
-
| `--codesys-
|
|
159
|
-
| `--
|
|
160
|
-
| `--
|
|
161
|
-
| `--
|
|
162
|
-
| `--
|
|
163
|
-
| `--no-
|
|
164
|
-
| `--
|
|
165
|
-
| `--
|
|
166
|
-
| `--no-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
[
|
|
267
|
-
|
|
268
|
-
|
|
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)
|
|
8
|
+
[](https://www.npmjs.com/package/@codesys/mcp-toolkit)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
[](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
|
+
|
|
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 V2.3 (`LogicBuilder.exe`, Scripting 4.1)
|
|
47
|
+
works too: pass `--codesys-path` and leave out `--codesys-profile`, since Machine
|
|
48
|
+
Expert has no profiles. See the [Machine Expert notes](docs/machine-expert-testing.md).
|
|
49
|
+
|
|
50
|
+
### Install
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm install -g @codesys/mcp-toolkit
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Coming from version 1? The tools have changed: see
|
|
57
|
+
[Migrating from v1](#migrating-from-v1).
|
|
58
|
+
|
|
59
|
+
### Connect it to Claude Desktop
|
|
60
|
+
|
|
61
|
+
Add the server to `%APPDATA%\Claude\claude_desktop_config.json`, then restart
|
|
62
|
+
Claude Desktop:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"mcpServers": {
|
|
67
|
+
"codesys": {
|
|
68
|
+
"command": "codesys-mcp-tool",
|
|
69
|
+
"args": [
|
|
70
|
+
"--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
|
|
71
|
+
"--codesys-profile", "CODESYS V3.5 SP21",
|
|
72
|
+
"--workspace", "C:\\PLC\\Projects"
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`--codesys-path` and `--codesys-profile` are optional. Without them the server
|
|
80
|
+
uses the newest CODESYS install under Program Files and its newest profile.
|
|
81
|
+
|
|
82
|
+
### Try it
|
|
83
|
+
|
|
84
|
+
> Create a project called `BlinkDemo.project`. Add a function block that toggles
|
|
85
|
+
> an output once per second, call it from `PLC_PRG`, compile it, and prove in
|
|
86
|
+
> simulation that the output toggles.
|
|
87
|
+
|
|
88
|
+
CODESYS starts in the background when the server launches. A cold start takes
|
|
89
|
+
1 to 3 minutes; later starts take about 10 seconds.
|
|
90
|
+
|
|
91
|
+
Claude Desktop asks for approval per tool. Choose **Always allow** the first
|
|
92
|
+
time it asks about `codesys`, and once more for `open_sim_panel`. After that it
|
|
93
|
+
doesn't ask again.
|
|
94
|
+
|
|
95
|
+
## What Claude can do
|
|
96
|
+
|
|
97
|
+
Everything goes through one MCP tool, `codesys`, with an action for each
|
|
98
|
+
operation. [The reference](docs/reference.md) describes each one.
|
|
99
|
+
|
|
100
|
+
| Area | Actions |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| **Projects** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
|
|
103
|
+
| **Read code** | `get_project_tree` `read_objects` `search_code` `get_outline` |
|
|
104
|
+
| **Change code** | `write_object` `create_object` `delete_object` `rename_object` |
|
|
105
|
+
| **Build** | `compile` |
|
|
106
|
+
| **Libraries** | `list_libraries` `add_library` `remove_library` `get_library_api` |
|
|
107
|
+
| **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` |
|
|
108
|
+
| **Change tracking** | `checkpoint` `get_changes` `revert_object` |
|
|
109
|
+
| **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` |
|
|
110
|
+
| **Helpers** | `batch` `wait` `help` `open_workspace` |
|
|
111
|
+
|
|
112
|
+
`batch` runs up to 50 actions in one call, which is much faster than separate
|
|
113
|
+
calls.
|
|
114
|
+
|
|
115
|
+
Version 2 edits Structured Text only. Objects with graphical bodies (SFC, CFC,
|
|
116
|
+
LD, FBD) appear in the tree and can be read as PLCopenXML, but not edited.
|
|
117
|
+
|
|
118
|
+
## Live panel
|
|
119
|
+
|
|
120
|
+
Right after opening or creating a project, Claude opens the panel as a card in
|
|
121
|
+
the chat. It shows the status, the object Claude is working on and how many
|
|
122
|
+
objects changed. **Open workspace** expands it into a CODESYS-style view with
|
|
123
|
+
the project tree, editor tabs, compile problems and a review list.
|
|
124
|
+
|
|
125
|
+
From the panel you can **Accept** or **Revert** each change, compare it with
|
|
126
|
+
the version you last reviewed, and **Pause Claude** while you look around.
|
|
127
|
+
|
|
128
|
+
The card needs a client that supports
|
|
129
|
+
[MCP Apps](https://modelcontextprotocol.io/extensions/apps). In our testing
|
|
130
|
+
Claude Desktop draws it in the Code tab but not in a normal chat
|
|
131
|
+
([anthropics/claude-ai-mcp#1243](https://github.com/anthropics/claude-ai-mcp/issues/1243)).
|
|
132
|
+
Ask Claude to open the workspace in your browser if you'd rather have it there;
|
|
133
|
+
the browser never opens by itself.
|
|
134
|
+
|
|
135
|
+
[More about the panel](docs/reference.md#live-panel)
|
|
136
|
+
|
|
137
|
+
## Safety
|
|
138
|
+
|
|
139
|
+
- **No real controller.** The toolkit doesn't log in or download to a
|
|
140
|
+
controller. It goes online only to CODESYS's own simulation, and every online
|
|
141
|
+
call first checks that simulation mode is on.
|
|
142
|
+
- **One approval covers every action.** That includes the actions that change
|
|
143
|
+
or delete project code, so work on a copy of any project you can't afford to
|
|
144
|
+
lose, or keep it in version control.
|
|
145
|
+
- **Changes can be undone.** A checkpoint is taken when a project is opened, and
|
|
146
|
+
`revert_object` puts an object back to it, including its methods and
|
|
147
|
+
properties.
|
|
148
|
+
- **Saved as it goes.** The project is saved after every change by default. Use
|
|
149
|
+
`--no-autosave` to save only on request.
|
|
150
|
+
- **The simulation can't change your project.** Editing is refused while it
|
|
151
|
+
runs, and the simulation setting on the device is never saved.
|
|
152
|
+
|
|
153
|
+
## Configuration
|
|
154
|
+
|
|
155
|
+
| Option | Meaning |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `--codesys-path <exe>` | `CODESYS.exe` to run |
|
|
158
|
+
| `--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 |
|
|
159
|
+
| `--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 |
|
|
160
|
+
| `--workspace <dir>` | Base folder for relative project paths (default: the working directory). Created if missing |
|
|
161
|
+
| `--project <file>` | Open this project as soon as CODESYS is up |
|
|
162
|
+
| `--session-dir <dir>` | Where session folders go (default: `%TEMP%\codesys-mcp-toolkit`) |
|
|
163
|
+
| `--no-autostart` | Start CODESYS on the first tool call instead of at launch |
|
|
164
|
+
| `--no-autosave` | Don't save after every change; use `save_project` |
|
|
165
|
+
| `--viewer-port <port>` | Port of the browser workspace on 127.0.0.1 (default 5180, or the next free one) |
|
|
166
|
+
| `--no-viewer` | Don't serve the browser workspace |
|
|
167
|
+
| `--no-shared` | Run CODESYS in this process instead of the shared session |
|
|
168
|
+
| `--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) |
|
|
169
|
+
|
|
170
|
+
### Several CODESYS versions
|
|
171
|
+
|
|
172
|
+
To keep SP21 and SP22 side by side, add one server entry per version, each with
|
|
173
|
+
its own `--codesys-path` and `--codesys-profile`.
|
|
174
|
+
|
|
175
|
+
The toolkit never updates a project's compiler or library versions, and
|
|
176
|
+
`open_project` says when they differ from the running CODESYS. A project that
|
|
177
|
+
needs a newer compiler opens, but can't compile until you open it in that
|
|
178
|
+
version. Each version keeps its own devices and libraries, so a project from an
|
|
179
|
+
older CODESYS may report missing libraries until you update it in the CODESYS
|
|
180
|
+
window.
|
|
181
|
+
|
|
182
|
+
### Shared session
|
|
183
|
+
|
|
184
|
+
Claude Desktop may start the server more than once. All processes started with
|
|
185
|
+
the same options share one background session, so only one CODESYS runs and the
|
|
186
|
+
panel shows the project Claude is working on. The session stops two minutes
|
|
187
|
+
after the last client disconnects. Its log is `daemon-<id>.log` in
|
|
188
|
+
`%LOCALAPPDATA%\codesys-mcp-toolkit`.
|
|
189
|
+
|
|
190
|
+
### Work in a window you already have open (experimental)
|
|
191
|
+
|
|
192
|
+
`--attach <dir>` makes the server use a CODESYS / Machine Expert window you
|
|
193
|
+
already work in, instead of starting a hidden one. It starts nothing and kills
|
|
194
|
+
nothing.
|
|
195
|
+
|
|
196
|
+
1. Add `--attach "C:\\PLC\\attach"` to the server arguments and start the
|
|
197
|
+
server. It writes `C:\PLC\attach\scripts\start_attach.py`.
|
|
198
|
+
2. In your window, open the project, then run that file with **Tools >
|
|
199
|
+
Scripting > Execute Script File**. It returns at once; a UI timer polls for
|
|
200
|
+
requests, so the window stays usable.
|
|
201
|
+
3. Use the `codesys` tool as usual. `open_project` on the project that is
|
|
202
|
+
already open just reuses it.
|
|
203
|
+
4. To stop, create an empty file `stop.flag` in the attach folder (or close the
|
|
204
|
+
window).
|
|
205
|
+
|
|
206
|
+
The window is busy only while a request runs, for example during `compile`.
|
|
207
|
+
Your own unsaved edits are saved with the next change Claude makes
|
|
208
|
+
(autosave), so use `--no-autosave` if that is not what you want. If the window
|
|
209
|
+
stops answering (a dialog is open), the call fails with an error and nothing is
|
|
210
|
+
closed; run `start_attach.py` again if the watcher was stopped.
|
|
211
|
+
|
|
212
|
+
## How it works
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
|
|
216
|
+
│ requests/<id>.json ▶ operation name + JSON arguments
|
|
217
|
+
│ ◀ results/<id>.json
|
|
218
|
+
│ ◀ heartbeat.json idle or busy, with a deadline
|
|
219
|
+
▼
|
|
220
|
+
CODESYS.exe --noUI --runscript=watcher.py
|
|
221
|
+
└─ fixed operation handlers (IronPython 2.7)
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
- **No generated code.** Requests are an operation name plus JSON arguments,
|
|
225
|
+
handled by fixed functions in `watcher/mcp_ops.py`.
|
|
226
|
+
- **Hang detection.** The watcher reports `busy` with a deadline. If CODESYS
|
|
227
|
+
blocks past it, the server kills it and starts a fresh one on the next call.
|
|
228
|
+
- **No orphans.** The watcher exits when the server process goes away.
|
|
229
|
+
- **Modal dialogs** are suppressed and logged, so they can't freeze CODESYS.
|
|
230
|
+
- **UTF-8** from end to end.
|
|
231
|
+
- **Localised names.** Object kinds come from CODESYS type GUIDs, not names, so
|
|
232
|
+
a German task folder called `Taskkonfiguration` works.
|
|
233
|
+
|
|
234
|
+
## Troubleshooting
|
|
235
|
+
|
|
236
|
+
| Message | What to do |
|
|
237
|
+
| --- | --- |
|
|
238
|
+
| **CODESYS is still starting** | The first start after boot can take minutes. Check `codesys_status`, then try again. |
|
|
239
|
+
| **`startup_failed`** or **`startup_timeout`** | Check the profile name and that CODESYS starts by hand. The error includes the last lines of `watcher.log`. |
|
|
240
|
+
| **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. |
|
|
241
|
+
| **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. |
|
|
242
|
+
| **`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. |
|
|
243
|
+
|
|
244
|
+
Each session folder keeps a `watcher.log`.
|
|
245
|
+
|
|
246
|
+
## Development
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
npm install
|
|
250
|
+
npm test # unit, bridge and tool tests (no CODESYS needed)
|
|
251
|
+
CODESYS_LIVE=1 npx vitest run test/live # end-to-end against your CODESYS
|
|
252
|
+
npm run build # server and the single-file panel
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
The normal tests run the real watcher under CPython 3 against a fake
|
|
256
|
+
`scriptengine` (`test/fake/`). Watcher code must stay valid IronPython 2.7:
|
|
257
|
+
ASCII-only, no f-strings.
|
|
258
|
+
|
|
259
|
+
To work on the panel without Claude Desktop, run the dev host, then open
|
|
260
|
+
http://localhost:5199:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
npm run build:panel && node scripts/dev-host/run.mjs 5199
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.
|
|
267
|
+
|
|
268
|
+
## Migrating from v1
|
|
269
|
+
|
|
270
|
+
- Everything is now an action of the one `codesys` tool.
|
|
271
|
+
- Actions don't take `projectFilePath`. Call `open_project` once.
|
|
272
|
+
- `create_pou`, `create_method` and `create_property` are now `create_object`
|
|
273
|
+
with a `kind`.
|
|
274
|
+
- `set_pou_code` is now `write_object`.
|
|
275
|
+
- `compile_project` is now `compile`, and it returns the errors.
|
|
276
|
+
- Read access is through actions (`read_objects`, `get_project_tree`) instead of
|
|
277
|
+
resources, so it works in Claude Desktop
|
|
278
|
+
([#6](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/6)).
|
|
279
|
+
|
|
280
|
+
## Acknowledgements
|
|
281
|
+
|
|
282
|
+
The persistent-watcher design borrows ideas from
|
|
283
|
+
[zbest1000/mcptoolkit-for-codesys](https://github.com/zbest1000/mcptoolkit-for-codesys)
|
|
284
|
+
(op-handler registry, heartbeat, prompt handling) and
|
|
285
|
+
[phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
|
|
286
|
+
(file-queue IPC, version-safe opening). Both are MIT-licensed.
|
|
287
|
+
|
|
288
|
+
## License
|
|
289
|
+
|
|
290
|
+
[MIT](LICENSE)
|
|
291
|
+
|
|
292
|
+
CODESYS is a trademark of CODESYS GmbH. This project is independent and isn't
|
|
293
|
+
affiliated with or endorsed by CODESYS GmbH.
|