control-expert-mcp 0.9.1__tar.gz
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.
- control_expert_mcp-0.9.1/MANIFEST.in +29 -0
- control_expert_mcp-0.9.1/PKG-INFO +474 -0
- control_expert_mcp-0.9.1/README.md +454 -0
- control_expert_mcp-0.9.1/benchmarks/CHECKPOINT.md +194 -0
- control_expert_mcp-0.9.1/benchmarks/README.md +389 -0
- control_expert_mcp-0.9.1/benchmarks/deepseek.example.json +51 -0
- control_expert_mcp-0.9.1/benchmarks/example.json +35 -0
- control_expert_mcp-0.9.1/benchmarks/opc.example.json +23 -0
- control_expert_mcp-0.9.1/pyproject.toml +35 -0
- control_expert_mcp-0.9.1/samples/claude_desktop_config.json +11 -0
- control_expert_mcp-0.9.1/samples/opc-mcp.json +12 -0
- control_expert_mcp-0.9.1/samples/vscode-mcp.json +12 -0
- control_expert_mcp-0.9.1/setup.cfg +4 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/__init__.py +5 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/__main__.py +3 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/__init__.py +1 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/alarms.py +221 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/archive.py +273 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/cli.py +163 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/core.py +239 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/opc.py +329 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/plot.py +139 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/provider.py +227 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/regrade.py +58 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/report.py +140 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/runner.py +349 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/tasks.py +220 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/benchmark/transport.py +181 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/bridge.py +2952 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/constants.py +118 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/diagnostics.py +60 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/documentation.py +374 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/lang_reference.py +411 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/live_access.py +59 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/modbus.py +203 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/opc.py +117 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/opc_worker.py +196 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/prompts.py +293 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/schema.py +207 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp/server.py +1229 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/PKG-INFO +474 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/SOURCES.txt +62 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/dependency_links.txt +1 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/entry_points.txt +3 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/requires.txt +14 -0
- control_expert_mcp-0.9.1/src/control_expert_mcp.egg-info/top_level.txt +1 -0
- control_expert_mcp-0.9.1/tools/benchmark_fake_server.py +121 -0
- control_expert_mcp-0.9.1/tools/check_ce_automation.py +90 -0
- control_expert_mcp-0.9.1/tools/check_distribution.py +109 -0
- control_expert_mcp-0.9.1/tools/check_opc.py +86 -0
- control_expert_mcp-0.9.1/tools/export_ce_help.py +415 -0
- control_expert_mcp-0.9.1/tools/index_ce_help.py +7 -0
- control_expert_mcp-0.9.1/tools/lang_refs/OPC_Bench.xml +29 -0
- control_expert_mcp-0.9.1/tools/lang_refs/ST_2_Feeder.xml +127 -0
- control_expert_mcp-0.9.1/tools/requirements-help.txt +5 -0
- control_expert_mcp-0.9.1/tools/test_benchmark.py +400 -0
- control_expert_mcp-0.9.1/tools/test_benchmark_alarms.py +93 -0
- control_expert_mcp-0.9.1/tools/test_benchmark_archive.py +108 -0
- control_expert_mcp-0.9.1/tools/test_diagnostics.py +95 -0
- control_expert_mcp-0.9.1/tools/test_documentation.py +183 -0
- control_expert_mcp-0.9.1/tools/test_export_ce_help.py +98 -0
- control_expert_mcp-0.9.1/tools/test_mcp_runtime.py +155 -0
- control_expert_mcp-0.9.1/tools/test_opc.py +132 -0
- control_expert_mcp-0.9.1/tools/test_opc_benchmark.py +57 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
include README.md pyproject.toml MANIFEST.in
|
|
2
|
+
recursive-include samples *.json
|
|
3
|
+
include tools/check_distribution.py
|
|
4
|
+
include tools/check_ce_automation.py
|
|
5
|
+
include tools/export_ce_help.py
|
|
6
|
+
include tools/index_ce_help.py
|
|
7
|
+
include tools/test_documentation.py
|
|
8
|
+
include tools/test_diagnostics.py
|
|
9
|
+
include tools/requirements-help.txt
|
|
10
|
+
include tools/test_export_ce_help.py
|
|
11
|
+
include tools/test_mcp_runtime.py
|
|
12
|
+
include tools/test_opc.py
|
|
13
|
+
include tools/check_opc.py
|
|
14
|
+
include tools/test_opc_benchmark.py
|
|
15
|
+
include tools/lang_refs/OPC_Bench.xml
|
|
16
|
+
include benchmarks/opc.example.json
|
|
17
|
+
include tools/test_benchmark.py
|
|
18
|
+
include tools/test_benchmark_archive.py
|
|
19
|
+
include tools/test_benchmark_alarms.py
|
|
20
|
+
include tools/benchmark_fake_server.py
|
|
21
|
+
include tools/lang_refs/ST_2_Feeder.xml
|
|
22
|
+
include benchmarks/example.json
|
|
23
|
+
include benchmarks/deepseek.example.json
|
|
24
|
+
include benchmarks/README.md
|
|
25
|
+
include benchmarks/CHECKPOINT.md
|
|
26
|
+
prune manuals
|
|
27
|
+
prune tmp
|
|
28
|
+
prune tools/bigtest
|
|
29
|
+
global-exclude __pycache__ *.py[cod]
|
|
@@ -0,0 +1,474 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: control-expert-mcp
|
|
3
|
+
Version: 0.9.1
|
|
4
|
+
Summary: MCP server exposing EcoStruxure Control Expert (Unity Pro) to AI agents via the UDE COM automation API
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/PBrunot/control-expert-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/PBrunot/control-expert-mcp/issues
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Requires-Dist: mcp<3,>=2.3.0
|
|
11
|
+
Requires-Dist: pywin32>=312; sys_platform == "win32"
|
|
12
|
+
Requires-Dist: pymodbus<4,>=3.16.2
|
|
13
|
+
Requires-Dist: lxml<7,>=6.1.3
|
|
14
|
+
Provides-Extra: benchmark
|
|
15
|
+
Requires-Dist: openai<3,>=2; extra == "benchmark"
|
|
16
|
+
Requires-Dist: matplotlib<4,>=3.10; extra == "benchmark"
|
|
17
|
+
Provides-Extra: test
|
|
18
|
+
Requires-Dist: beautifulsoup4<5,>=4.15; extra == "test"
|
|
19
|
+
Requires-Dist: markdownify<2,>=1.2.4; extra == "test"
|
|
20
|
+
|
|
21
|
+
# Control Expert MCP Server
|
|
22
|
+
|
|
23
|
+
[](https://github.com/PBrunot/control-expert-mcp/actions/workflows/ci.yml)
|
|
24
|
+

|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
Connect MCP clients to a local **EcoStruxure Control Expert** (formerly **Unity Pro**) installation. Inspect, create, edit, and build PLC projects through Schneider Electric's Unity Developer's Edition (UDE) COM automation API.
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
MCP client ── stdio ──> control-expert-mcp ── COM ──> Control Expert
|
|
31
|
+
└─ Modbus TCP ──> PLC / simulator (opt-in)
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Inspired by [tiaportal-mcp](https://github.com/heilingbrunner/tiaportal-mcp). This project uses the Control Expert UDE broker (`PSBroker.PServerBroker`) through `pywin32`.
|
|
35
|
+
|
|
36
|
+
> [!WARNING]
|
|
37
|
+
> Online tools can download applications, start or stop controllers, and write process values. They are disabled by default. Enable them only for a simulator or a supervised test bench; production equipment requires qualified supervision.
|
|
38
|
+
|
|
39
|
+
## Contents
|
|
40
|
+
|
|
41
|
+
- [Features](#features)
|
|
42
|
+
- [Requirements](#requirements)
|
|
43
|
+
- [Quick start](#quick-start)
|
|
44
|
+
- [MCP client configuration](#mcp-client-configuration)
|
|
45
|
+
- [Configuration](#configuration)
|
|
46
|
+
- [Usage](#usage)
|
|
47
|
+
- [Tool reference](#tool-reference)
|
|
48
|
+
- [Guided workflows](#guided-workflows)
|
|
49
|
+
- [PLC and simulator access](#plc-and-simulator-access)
|
|
50
|
+
- [Searchable local manuals](#searchable-local-manuals)
|
|
51
|
+
- [Troubleshooting](#troubleshooting)
|
|
52
|
+
- [Development and validation](#development-and-validation)
|
|
53
|
+
- [Packaging and releases](#packaging-and-releases)
|
|
54
|
+
- [Contributing](#contributing)
|
|
55
|
+
- [License and affiliation](#license-and-affiliation)
|
|
56
|
+
|
|
57
|
+
## Features
|
|
58
|
+
|
|
59
|
+
- **Project management:** create projects using installed CPU catalog entries; open and save `.stu` / `.sta`; import and export `.xef` / `.zef`.
|
|
60
|
+
- **Program authoring:** inspect and edit ST, LD, FBD, SFC, and IL sections. Write ST directly or import Control Expert exchange XML for graphical languages, variables, DFBs, and DDTs.
|
|
61
|
+
- **Hardware configuration:** inspect buses, drops, racks, and modules; add, replace, or remove supported hardware; change the CPU.
|
|
62
|
+
- **Communications:** manage DTMs, device addresses, M580 Modbus scan requests, CPU Ethernet services, and Premium/Quantum logical networks.
|
|
63
|
+
- **Validation:** check exchange XML against installed schemas, analyze and build projects, and retrieve build diagnostics.
|
|
64
|
+
- **Documentation:** search locally converted vendor manuals and retrieve topics with source citations, without opening Control Expert.
|
|
65
|
+
- **Monitoring and commissioning:** open animation tables and, when explicitly enabled, connect to a PLC or simulator and read or write located tags over Modbus TCP.
|
|
66
|
+
|
|
67
|
+
Availability depends on the installed Control Expert version, license, hardware catalog, and DTM libraries.
|
|
68
|
+
|
|
69
|
+
## Requirements
|
|
70
|
+
|
|
71
|
+
| Requirement | Details |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| Operating system | Windows for Control Expert COM automation |
|
|
74
|
+
| Python | 3.11 or newer, as declared in `pyproject.toml` |
|
|
75
|
+
| Control Expert | Licensed local installation of EcoStruxure Control Expert or Unity Pro; validated with versions 14.0 and 16.4 |
|
|
76
|
+
| Automation interface | Registered UDE COM broker (`PSBroker.PServerBroker.1`) |
|
|
77
|
+
| MCP client | A client supporting stdio servers, such as Claude Desktop, Claude Code, or VS Code with GitHub Copilot |
|
|
78
|
+
|
|
79
|
+
Run the server on the **same machine as Control Expert**. DCOM remoting is not configured. The UDE automation server ships with Control Expert; the separate UDE package is only needed for its documentation. Python dependencies are installed with the package.
|
|
80
|
+
|
|
81
|
+
## Quick start
|
|
82
|
+
|
|
83
|
+
Run these commands in PowerShell:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
git clone https://github.com/PBrunot/control-expert-mcp.git
|
|
87
|
+
cd control-expert-mcp
|
|
88
|
+
py -3.11 -m venv .venv
|
|
89
|
+
.venv\Scripts\python.exe -m pip install -e .
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Configure your MCP client with the absolute path to `.venv\Scripts\python.exe` and arguments `["-m", "control_expert_mcp"]`, using an example below.
|
|
93
|
+
|
|
94
|
+
To launch the stdio server manually:
|
|
95
|
+
|
|
96
|
+
```powershell
|
|
97
|
+
.venv\Scripts\python.exe -m control_expert_mcp
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The installed `control-expert-mcp` console command is equivalent. This is a stdio service; an MCP client normally starts and manages the process.
|
|
101
|
+
|
|
102
|
+
## MCP client configuration
|
|
103
|
+
|
|
104
|
+
Replace `C:\path\to\control-expert-mcp` with your checkout path. Keep online access disabled for initial setup.
|
|
105
|
+
|
|
106
|
+
### Claude Desktop
|
|
107
|
+
|
|
108
|
+
Add this entry to `%APPDATA%\Claude\claude_desktop_config.json`. A copy is available in [samples/claude_desktop_config.json](samples/claude_desktop_config.json).
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"mcpServers": {
|
|
113
|
+
"control-expert": {
|
|
114
|
+
"command": "C:\\path\\to\\control-expert-mcp\\.venv\\Scripts\\python.exe",
|
|
115
|
+
"args": ["-m", "control_expert_mcp"],
|
|
116
|
+
"env": {
|
|
117
|
+
"CE_MCP_ENABLE_ONLINE": "0"
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Claude Code
|
|
125
|
+
|
|
126
|
+
```powershell
|
|
127
|
+
claude mcp add control-expert -- C:\path\to\control-expert-mcp\.venv\Scripts\python.exe -m control_expert_mcp
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Online access remains disabled unless the server inherits an enabling environment variable.
|
|
131
|
+
|
|
132
|
+
### VS Code / GitHub Copilot
|
|
133
|
+
|
|
134
|
+
Add the server to `.vscode/mcp.json`. See [samples/vscode-mcp.json](samples/vscode-mcp.json).
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"servers": {
|
|
139
|
+
"control-expert": {
|
|
140
|
+
"type": "stdio",
|
|
141
|
+
"command": "C:\\path\\to\\control-expert-mcp\\.venv\\Scripts\\python.exe",
|
|
142
|
+
"args": ["-m", "control_expert_mcp"],
|
|
143
|
+
"env": {
|
|
144
|
+
"CE_MCP_ENABLE_ONLINE": "0"
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Configuration
|
|
152
|
+
|
|
153
|
+
Set environment variables in the MCP client's server configuration so they reach the server process.
|
|
154
|
+
|
|
155
|
+
| Variable | Default | Purpose |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `CE_MCP_ENABLE_ONLINE` | Disabled | Set to `1` to register `plc_*`, `opc_*`, `modbus_*`, `read_tags`, and `write_tags`. Session setup and user approval are still required. Restart after changing it. |
|
|
158
|
+
| `CE_MCP_OPC_PYTHON` | Server Python | Python executable matching the installed OPC Automation DLL bitness, with `pywin32` installed. Usually a separate 32-bit Python for OFS. |
|
|
159
|
+
| `CE_MCP_SCHEMA_DIR` | Auto-discovered | Override the path to Control Expert's installed `SrcXmlSchema` directory for XML validation. |
|
|
160
|
+
| `CE_MCP_MANUALS_DIR` | Repository-relative `manuals/ce-16.4` | Path to a converted and indexed local manual corpus. Set an absolute path for packaged installations. |
|
|
161
|
+
|
|
162
|
+
## Usage
|
|
163
|
+
|
|
164
|
+
Start with a disposable project or a copy of an existing project. Example requests to your connected AI client:
|
|
165
|
+
|
|
166
|
+
- “Open this project and summarize its CPU, tasks, sections, and global variables.”
|
|
167
|
+
- “Create an ST section for a motor interlock, declare its variables, and build the project.”
|
|
168
|
+
- “Inspect the hardware tree and list the configured Modbus devices.”
|
|
169
|
+
- “Search the installed manuals for `READ_VAR` and cite the relevant topic.”
|
|
170
|
+
|
|
171
|
+
### Authoring logic
|
|
172
|
+
|
|
173
|
+
For Structured Text, `write_st_logic` accepts IEC source directly. The following illustrates MCP tool arguments; it is not a standalone Python script:
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
write_st_logic(
|
|
177
|
+
task="MAST",
|
|
178
|
+
section="MotorControl",
|
|
179
|
+
st_source="MotorRun := StartButton AND NOT StopButton;",
|
|
180
|
+
declare="StartButton:BOOL, StopButton:BOOL, MotorRun:BOOL"
|
|
181
|
+
)
|
|
182
|
+
build_project()
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The tool creates the section or replaces its existing logic. For LD, FBD, SFC, and IL, consult `get_language_reference`, export a similar object when needed, validate the candidate XML with `validate_xml`, and import it with `import_xml`. Declare referenced variables first or include them in the exchange XML.
|
|
186
|
+
|
|
187
|
+
**Imports can replace existing sections.** Build after changes, inspect the result, and save explicitly. `close_project` discards changes unless `save=true`.
|
|
188
|
+
|
|
189
|
+
### Interpreting build results
|
|
190
|
+
|
|
191
|
+
`build_project` and `analyze_project` return `build_state`, raw `output`, an `error` when present, parsed `diagnostics`, and capture metadata. Recognized diagnostic lines include severity, code, task/section, and line/column where available; unknown or localized formats remain in raw output.
|
|
192
|
+
|
|
193
|
+
An empty diagnostic list does **not** prove a clean build. Check `build_state`, `error`, raw output, and `diagnostics_summary` together. `diagnostics_available` distinguishes an empty Build tab from unavailable output. Capture metadata reports freshness and snapshot/appended scope, but attribution remains `unverified`: the COM output API provides no operation identifier, and identical output may belong to a repeated build or an older operation.
|
|
194
|
+
|
|
195
|
+
## Tool reference
|
|
196
|
+
|
|
197
|
+
Tools are registered in [server.py](src/control_expert_mcp/server.py). The client exposes their full argument schemas and descriptions.
|
|
198
|
+
|
|
199
|
+
| Area | Tools |
|
|
200
|
+
| --- | --- |
|
|
201
|
+
| Project lifecycle | `get_status`, `open_project`, `new_project`, `save_project`, `close_project`, `export_project` |
|
|
202
|
+
| Build and settings | `analyze_project`, `build_project`, `get_project_setting`, `set_project_settings` |
|
|
203
|
+
| Project structure | `get_project_structure`, `create_task`, `create_section`, `delete_section`, `read_section` |
|
|
204
|
+
| Logic authoring | `write_st_logic`, `get_language_reference`, `place_fb_in_ladder`, `use_fb_in_ladder` |
|
|
205
|
+
| Exchange XML | `validate_xml`, `import_xml`, `export_xml` |
|
|
206
|
+
| Variables and types | `list_variables`, `create_variable`, `update_variable`, `delete_variable`, `list_data_types` |
|
|
207
|
+
| Hardware | `get_hardware`, `add_io_module`, `remove_io_module`, `replace_io_module`, `add_drop`, `add_rack`, `replace_rack`, `change_cpu` |
|
|
208
|
+
| DTM topology and addressing | `list_dtms`, `add_dtm`, `delete_dtm`, `set_dtm_address` |
|
|
209
|
+
| DTM configuration | `get_dtm_control_parameters`, `set_dtm_control_parameters`, `get_dtm_dataset`, `set_dtm_dataset`, `get_master_dtm_dataset`, `set_master_dtm_dataset` |
|
|
210
|
+
| Ethernet and networks | `configure_cpu_ethernet`, `list_networks`, `add_network`, `set_network_ip` |
|
|
211
|
+
| Animation tables and UI | `list_animation_tables`, `create_animation_table`, `delete_animation_table`, `show_ui`, `open_animation_table` |
|
|
212
|
+
| Simulator process | `start_simulator`, `stop_simulator` |
|
|
213
|
+
| Local manuals | `get_documentation_status`, `search_manuals`, `get_manual_topic` |
|
|
214
|
+
| Live session setup (always available) | `get_live_access_setup`, `configure_live_access` |
|
|
215
|
+
| PLC connection **(opt-in)** | `plc_setup_connection`, `plc_connect`, `plc_disconnect`, `plc_state`, `plc_transfer`, `plc_command` |
|
|
216
|
+
| Symbolic live values **(opt-in, preferred)** | `opc_connect`, `opc_disconnect`, `opc_status`, `opc_browse`, `opc_read_tags`, `opc_write_tags` |
|
|
217
|
+
| Modbus live values **(opt-in)** | `modbus_connect`, `modbus_disconnect`, `modbus_status`, `read_tags`, `write_tags` |
|
|
218
|
+
|
|
219
|
+
DTM scan-request configuration uses the master/CPU dataset's `ManagedModbusRequestList`. Follow the template in `set_master_dtm_dataset` and the `add_modbus_device` prompt, including GUID and numbering rules. `place_fb_in_ladder` generates pin geometry for project DFBs; `use_fb_in_ladder` provides a template-based fallback for elementary blocks or exact GUI geometry.
|
|
220
|
+
|
|
221
|
+
## Guided workflows
|
|
222
|
+
|
|
223
|
+
The server includes reusable MCP prompts in [prompts.py](src/control_expert_mcp/prompts.py). Select them through your client's prompt picker.
|
|
224
|
+
|
|
225
|
+
| Prompt | Workflow |
|
|
226
|
+
| --- | --- |
|
|
227
|
+
| `scaffold_project` | Create a project using exact CPU/catalog versions, configure hardware, build, and save. |
|
|
228
|
+
| `author_logic` | Consult language references, author or import logic, build, and resolve errors. |
|
|
229
|
+
| `fb_in_ladder` | Place a function block in Ladder and bind its pins. |
|
|
230
|
+
| `add_modbus_device` | Add a Modbus TCP slave DTM and configure a scan request. |
|
|
231
|
+
| `commission_simulator` | Build, start the simulator, connect, transfer, and run, including the first-transfer limitation. |
|
|
232
|
+
| `setup_live_access` | Obtain session consent, prefer OPC, record the OFS alias, and separately approve closed-loop operation. |
|
|
233
|
+
| `test_logic_opc` | Browse and debug symbolic variables, including exposed unlocated variables and DFB/array members, through OFS. |
|
|
234
|
+
| `test_logic_live` | Test located values over Modbus, including mirrors for unlocated DFB internals. |
|
|
235
|
+
| `consult_installed_manuals` | Prepare, search, retrieve, and cite local documentation. |
|
|
236
|
+
| `benchmark_training_project` | Run the offline benchmark training workflow. |
|
|
237
|
+
|
|
238
|
+
## PLC and simulator access
|
|
239
|
+
|
|
240
|
+
Set `CE_MCP_ENABLE_ONLINE=1` in the server environment and restart it to expose online tools. This only makes the tools available; every server process starts with live access blocked.
|
|
241
|
+
|
|
242
|
+
On connection, the LLM is instructed to call `get_live_access_setup` and collect the user's choices: offline or live access, OPC (preferred) or Modbus, and the OFS device alias for OPC. Before closed-loop writes or PLC control, the user must explicitly approve that mode and confirm OFS is available and running for OPC. `configure_live_access` records these answers; the server enforces them before connecting, reading, writing, transferring, or issuing PLC commands. There is no automatic protocol fallback. Configuration lasts for the server process; restarting requires setup again. Changing setup disconnects existing connections. Cleanup and status calls remain available. MCP instructions guide the conversation; client support determines how the questions are displayed.
|
|
243
|
+
|
|
244
|
+
For example, **after** the user approves OPC connections, confirms the alias and running OFS, and approves closed-loop tests:
|
|
245
|
+
|
|
246
|
+
```text
|
|
247
|
+
configure_live_access(allow_live_connection=true, protocol="opc",
|
|
248
|
+
ofs_alias="Dev_Alias_2", opc_server_confirmed_running=true, allow_closed_loop=true)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
Use `allow_closed_loop=false` for read-only sessions. To revoke live access, call `configure_live_access(allow_live_connection=false)`. Tool arguments attest to answers obtained by the client; the server cannot independently authenticate a conversational user confirmation.
|
|
252
|
+
|
|
253
|
+
Use the `commission_simulator` prompt for the complete commissioning procedure.
|
|
254
|
+
|
|
255
|
+
The commissioning sequence is:
|
|
256
|
+
|
|
257
|
+
1. Build the project and confirm `build_state="built_ok"`.
|
|
258
|
+
2. Launch the simulator with `start_simulator` or the installed `PLC_Simulator\sim.exe`.
|
|
259
|
+
3. Configure `plc_setup_connection(target="simulator", address="127.0.0.1")` and call `plc_connect(target="simulator")`.
|
|
260
|
+
4. Ensure the controller is stopped before `plc_transfer(direction="pc_to_plc")`.
|
|
261
|
+
5. Call `plc_command(command="run")` and inspect `plc_state`.
|
|
262
|
+
|
|
263
|
+
> [!IMPORTANT]
|
|
264
|
+
> A fresh simulator with no station loaded (`no_conf`) can reject API downloads with **“Family check failed.”** Seed it once through the Control Expert GUI: PLC → Simulation Mode → Connect → Transfer, using a project of the matching controller family. The station persists while `sim.exe` runs. Subsequent API downloads require the controller to be stopped.
|
|
265
|
+
|
|
266
|
+
### Symbolic live values through OFS OPC DA
|
|
267
|
+
|
|
268
|
+
The expected testing environment is a running **OFS server connected to PLC Simulator**. The default test device alias is **`Dev_Alias_2`**, configured for `MBT:127.0.0.1/U` (M580), with dictionary use (`UsingDataDic`) and unlocated support (`UnlocatedSupport`) enabled. Confirm this alias and that OFS is available/running during session setup; another alias may be explicitly selected.
|
|
269
|
+
|
|
270
|
+
The UDE COM API exposes the project database. OFS provides symbolic live access using the application's built/downloaded data dictionary. In Control Expert **Project Settings → General → PLC embedded data**, enable **Data dictionary** and clear **Only HMI variables** so the dictionary includes **non-HMI variables** with write access. **Keep other variables in Read Only** is insufficient for closed-loop tests that write non-HMI inputs. Include DFB/PU private variables if those internals are needed. Build the application with these settings and download that build to PLC Simulator. Changing settings without rebuilding/downloading does not update the running application's dictionary. If the running application already exposes the required symbols, no rebuild or transfer is needed. Only exposed symbols and scalar members can be accessed; browse DFB and array branches to discover exact IDs.
|
|
271
|
+
|
|
272
|
+
The installed `OPC.Automation` DLL and its Python host must have matching bitness. A 64-bit MCP server can use a separate 32-bit Python with `pywin32` through `CE_MCP_OPC_PYTHON`. For a normal installed 32-bit Python, install its dependency using `<32-bit-python.exe> -m pip install pywin32`. The helper script is shipped as Python source with this package; it does not require MCP installed in the helper interpreter. COM objects stay on the helper's single STA thread. No registry changes or UDE write token are needed.
|
|
273
|
+
|
|
274
|
+
See [samples/opc-mcp.json](samples/opc-mcp.json) for a client configuration. Device choice and permission are collected by session setup, rather than preapproved in the environment.
|
|
275
|
+
|
|
276
|
+
After completing setup:
|
|
277
|
+
|
|
278
|
+
```text
|
|
279
|
+
opc_connect()
|
|
280
|
+
opc_browse()
|
|
281
|
+
opc_browse(branches=["Dev_Alias_2"])
|
|
282
|
+
opc_browse(branches=["Dev_Alias_2", "Forming_motor"])
|
|
283
|
+
opc_read_tags(tags=["Start", "Material_A", "Forming_motor.running_left"])
|
|
284
|
+
opc_disconnect()
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Use the configured alias for short names or exact browsed `alias!symbol` IDs belonging to that device. Browse results are paginated with `next_offset`; `flat=true` follows server semantics and may omit nested DFB members. Reads request the device, return quality/timestamp/type/access metadata, and exclude bad/uncertain samples from `values`. `opc_write_tags(values={"name": value})` uses canonical scalar types; booleans must be JSON booleans and integers must fit their type. Write success acknowledges the request; PLC logic may overwrite values. Observe outputs separately and restore test inputs. A timeout disconnects the helper and is never automatically retried, especially for writes.
|
|
288
|
+
|
|
289
|
+
Validation on 2026-11-21 used Control Expert 16.4, M580 `BME P58 3040` version `03.20`, OFS 3.63, and the running `samples/demo_ControlExpert_M580.STU` simulator application. Alias `Dev_Alias_2` used the PLC dictionary with unlocated support enabled. A 64-bit MCP Python called the installed 32-bit Automation wrapper through a 32-bit Python 3.11.9 helper with pywin32 312. Browsing found DFB members; device reads had quality `192` (good). Writing unlocated `Measured_temp` from `0` to `1` produced `Cmeasured_temp=1.0` and `Temp_ok=false`; restoring `0` restored both derived values. No logic change, build, or download was needed. This validates the tested symbols and configuration, not every project variable or OFS release.
|
|
290
|
+
|
|
291
|
+
Reproduce only after confirming the same demo is running and approving reversible tests, with the two environment variables above set:
|
|
292
|
+
|
|
293
|
+
```powershell
|
|
294
|
+
.venv\Scripts\python.exe tools\test_opc.py
|
|
295
|
+
.venv\Scripts\python.exe tools\test_mcp_runtime.py
|
|
296
|
+
.venv\Scripts\python.exe tools\check_opc.py --alias Dev_Alias_2 --allow-live --confirm-ofs-running --exercise-demo --report tmp\opc-validation.json
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Omit `--exercise-demo` to browse without writing. The report stays local. Restoration is attempted in a `finally` step and failures are reported explicitly; process termination or loss of communication can prevent restoration.
|
|
300
|
+
|
|
301
|
+
For LLM evaluation, use the separate [`ce-bench opc` benchmark](benchmarks/README.md#live-opc-readwrite-benchmark). It builds a simple program with unlocated non-HMI BOOL/INT/REAL inputs, tests model-driven symbolic reads/writes, and independently verifies the running simulator's calculated outputs. The existing offline benchmark remains offline.
|
|
302
|
+
|
|
303
|
+
### Live values over Modbus TCP
|
|
304
|
+
|
|
305
|
+
Select Modbus explicitly in session setup when using a standard Modbus TCP endpoint. Animation tables can also display values in the GUI.
|
|
306
|
+
|
|
307
|
+
Example MCP tool calls against a Modbus endpoint after setup:
|
|
308
|
+
|
|
309
|
+
```text
|
|
310
|
+
modbus_connect(host="127.0.0.1", port=502)
|
|
311
|
+
read_tags(tags="MotorRun, %MW0, %MW2:REAL")
|
|
312
|
+
write_tags(values={"%MW2:REAL": 4.0})
|
|
313
|
+
modbus_disconnect()
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
- Only **located `%M` / `%MW` tags** are reachable. Mirror unlocated DFB internals such as `Pump1.Running` to located variables in the program first.
|
|
317
|
+
- Use global variable names or explicit addresses, optionally with a type: `%M3`, `%MW86`, `%MW2:REAL`, `%MW70:UDINT`, or `%MW10.2` for a word bit.
|
|
318
|
+
- 32-bit `REAL` / `DINT` values use Schneider's low-word-first order by default. Set `word_order="high_first"` when required by the target.
|
|
319
|
+
- Prefer OFS for simulator access; a simulator address accepting OFS traffic does not establish support for this Modbus client.
|
|
320
|
+
|
|
321
|
+
## Searchable local manuals
|
|
322
|
+
|
|
323
|
+
Convert your locally installed Control Expert help, then build its search index. Conversion requires Windows, the optional help dependencies, and 7-Zip for CHM extraction.
|
|
324
|
+
|
|
325
|
+
From the repository root:
|
|
326
|
+
|
|
327
|
+
```powershell
|
|
328
|
+
.venv\Scripts\python.exe -m pip install -e . -r tools/requirements-help.txt
|
|
329
|
+
.venv\Scripts\python.exe tools/export_ce_help.py --list
|
|
330
|
+
.venv\Scripts\python.exe tools/export_ce_help.py --languages en --jobs 4
|
|
331
|
+
.venv\Scripts\python.exe tools/index_ce_help.py --manuals-dir manuals/ce-16.4
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
The converter defaults to `C:\Program Files (x86)\Schneider Electric\EcoStruxure Control Expert 16.4` and writes to `manuals/ce-16.4`. Use `--install-dir` and `--output` to override paths, `--languages en it` or `--languages all` for additional languages, and `--include baselib.chm` to select a source. Completed unchanged sources are cached; `--force` regenerates them. Failed or partial exports can be resumed.
|
|
335
|
+
|
|
336
|
+
Set `CE_MCP_MANUALS_DIR` to the absolute corpus path in your client configuration. Wheel installations can index an existing corpus with:
|
|
337
|
+
|
|
338
|
+
```powershell
|
|
339
|
+
python -m control_expert_mcp.documentation --manuals-dir C:\path\to\manuals\ce-16.4
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Use `get_documentation_status`, then `search_manuals(query="TON")`, and retrieve a result with `get_manual_topic(topic_id=...)`. Searches return excerpts and citations; topic retrieval preserves original Markdown, tables, code, and source context. Follow `next_cursor` with the same topic and section until it is null.
|
|
343
|
+
|
|
344
|
+
Key behavior and limits:
|
|
345
|
+
|
|
346
|
+
- Conversion and indexing are explicit local operations. MCP requests never convert, index, or download manuals and require no COM session or PLC connection.
|
|
347
|
+
- Search accepts literal words and symbols. `language` selects the documentation language, not the PLC programming language; version filters require exact metadata matches.
|
|
348
|
+
- Citations include source paths/hashes, topic locations, language, converter metadata, and warnings. Unknown publication versions remain unknown; a manual match does not establish CPU applicability or installed-block availability.
|
|
349
|
+
- Stale indexes are refused. Rerun conversion after vendor updates and indexing after corpus or metadata changes. Freshness is checked against the conversion manifest, not a live scan of the vendor installation.
|
|
350
|
+
- Conversion performs no OCR. PDF layouts and tables may need comparison with the originals; pages without native text are reported. CHM scripts are not executed.
|
|
351
|
+
- Generated vendor manuals, indexes, and reports stay local and are excluded from Git and distributions. Treat manual content as reference data.
|
|
352
|
+
|
|
353
|
+
## Troubleshooting
|
|
354
|
+
|
|
355
|
+
| Symptom | Action |
|
|
356
|
+
| --- | --- |
|
|
357
|
+
| COM broker creation fails | Confirm Control Expert is installed and licensed. Repair its installation if COM registration is broken. |
|
|
358
|
+
| `Catalog object not found` | Match CPU part number, spacing, and firmware exactly to the installed catalog; for example, `BMX P34 2020` / `02.70`. |
|
|
359
|
+
| Module reference is missing from the catalog | Supply the exact module reference and catalog version. Check the installed catalog rather than assuming a version. |
|
|
360
|
+
| `new_project` returns a bare `Exception occurred` | Try the same CPU in the GUI to check platform licensing and installed libraries. |
|
|
361
|
+
| Write access is reserved by another client | Close the project in the other writable GUI/automation session. The server holds one write token per session. |
|
|
362
|
+
| First project operation takes a long time | Startup and large-project loading can take 30–120 seconds. Increase the client's tool timeout. |
|
|
363
|
+
| XML import reports `Invalid file` | Export a similar object and mirror its schema, including headers. Run `validate_xml` before importing. |
|
|
364
|
+
| DTM protocol ID is invalid | Use the exact DTM catalog name, such as `Modbus Device`, and protocol `Modbus`. Inspect `tools/list_dtm_catalog.py` when needed. |
|
|
365
|
+
| Master DTM dataset update fails with an RPC error | Check request XML against the tool's template. `requestUniqueID` must be a fresh GUID. |
|
|
366
|
+
| Simulator transfer reports `Family check failed` | Complete the GUI seed transfer described under [PLC and simulator access](#plc-and-simulator-access). |
|
|
367
|
+
| Manuals are unavailable or stale | Check the corpus path with `get_documentation_status`, then rerun the required conversion/indexing step. |
|
|
368
|
+
|
|
369
|
+
Report reproducible bugs through [GitHub Issues](https://github.com/PBrunot/control-expert-mcp/issues). Include Python and Control Expert versions, CPU/firmware when relevant, the tool sequence, and sanitized errors. Exclude customer projects, credentials, and proprietary exports.
|
|
370
|
+
|
|
371
|
+
## Development and validation
|
|
372
|
+
|
|
373
|
+
### Repository layout
|
|
374
|
+
|
|
375
|
+
```text
|
|
376
|
+
src/control_expert_mcp/ MCP tools, COM bridge, Modbus access, schemas, prompts,
|
|
377
|
+
language references, documentation service, and benchmarks
|
|
378
|
+
samples/ MCP client configuration examples
|
|
379
|
+
tools/ Diagnostics, offline tests, help conversion, and integration scripts
|
|
380
|
+
benchmarks/ Benchmark setup, checkpoints, and archived results
|
|
381
|
+
.github/workflows/ CI and package publishing
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
The DDT Mirror application has moved to a separate repository.
|
|
385
|
+
|
|
386
|
+
### Offline checks
|
|
387
|
+
|
|
388
|
+
```powershell
|
|
389
|
+
.venv\Scripts\python.exe -m pip install -e ".[test]"
|
|
390
|
+
.venv\Scripts\python.exe -m compileall -q src
|
|
391
|
+
.venv\Scripts\python.exe -m unittest discover -s tools -p "test_*.py"
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
[CI](.github/workflows/ci.yml) runs offline regression tests on Windows with Python 3.11–3.15, validates distributions, and tests the installed wheel in an isolated environment. These checks use synthetic documentation and mocked COM responses; they do not validate licensed COM integration or PLC runtime behavior.
|
|
395
|
+
|
|
396
|
+
### Local Control Expert validation
|
|
397
|
+
|
|
398
|
+
Review scripts before running them. Integration workflows can modify projects or terminate Control Expert processes.
|
|
399
|
+
|
|
400
|
+
```powershell
|
|
401
|
+
.venv\Scripts\python.exe tools/check_ce_automation.py
|
|
402
|
+
# Optional: create, build, export, reopen, and delete a disposable offline project.
|
|
403
|
+
.venv\Scripts\python.exe tools/check_ce_automation.py --exercise-project --report tmp/automation-check.json
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
The automation check does not connect to a PLC. The default scratch CPU is M340 `BMX P34 2020` / `02.70`; override `--cpu` and `--cpu-version` for your installed catalog.
|
|
407
|
+
|
|
408
|
+
Recorded local validation includes Control Expert 16.4 with an M340 scratch-project round trip and an offline M580 `BME P58 3040` / `03.20` demo check. The M580 check exercised analyze/build, an intentional undefined-symbol diagnostic, cleanup back to `built_ok`, and unchanged-output detection. These are environment-specific results, not a guarantee for every CPU or installation.
|
|
409
|
+
|
|
410
|
+
### Architecture and extension rules
|
|
411
|
+
|
|
412
|
+
- Keep all COM calls on the bridge's dedicated STA worker thread.
|
|
413
|
+
- Preserve session write-token handling. The bridge acquires and caches the project's write token once per session.
|
|
414
|
+
- Hardware and DTM automation use secondary COM interfaces; preserve the bridge's interface-query helpers.
|
|
415
|
+
- Exchange-file extensions must match XML roots because Control Expert selects import parsers by extension.
|
|
416
|
+
- Shared Modbus calls are serialized across concurrent MCP handlers.
|
|
417
|
+
|
|
418
|
+
See [bridge.py](src/control_expert_mcp/bridge.py), [schema.py](src/control_expert_mcp/schema.py), and [constants.py](src/control_expert_mcp/constants.py) for implementation details.
|
|
419
|
+
|
|
420
|
+
### Optional model benchmarks
|
|
421
|
+
|
|
422
|
+
The `ce-bench` CLI compares server revisions or manual-tool availability using configured OpenAI or DeepSeek API models. Provider packages and API calls are optional; normal server operation needs no provider key.
|
|
423
|
+
|
|
424
|
+
Five training tasks cover inspection, threshold edits, temperature tolerance, compile repair, and a demo-derived extension with gated low/high alarm hysteresis. Temperature grading accepts redundant bound parentheses; alarm grading checks a restricted ST transition model across the full INT input range and prior alarm states.
|
|
425
|
+
|
|
426
|
+
See the [benchmark guide](benchmarks/README.md), [validation checkpoint](benchmarks/CHECKPOINT.md), and [archived results](benchmarks/archive/README.md). Static artifact checks do not establish PLC runtime behavior, and API results do not reproduce ChatGPT UI orchestration.
|
|
427
|
+
|
|
428
|
+
## Packaging and releases
|
|
429
|
+
|
|
430
|
+
Build and validate distributions from the repository root using a fresh output directory:
|
|
431
|
+
|
|
432
|
+
```powershell
|
|
433
|
+
.venv\Scripts\python.exe -m pip install build twine
|
|
434
|
+
.venv\Scripts\python.exe -m build --outdir dist/0.9.0
|
|
435
|
+
.venv\Scripts\python.exe -m twine check --strict dist/0.9.0/*
|
|
436
|
+
.venv\Scripts\python.exe tools/check_distribution.py --dist-dir dist/0.9.0
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Use the version declared in `pyproject.toml` when choosing the output directory. The wheel contains the runtime package; the source archive includes selected tools and samples listed in `MANIFEST.in`. The archive audit rejects unexpected content, including customer projects, generated manuals, and vendor extracts.
|
|
440
|
+
|
|
441
|
+
Successful CI runs retain a `python-distributions` artifact for 14 days. To install a downloaded wheel in a dedicated environment:
|
|
442
|
+
|
|
443
|
+
```powershell
|
|
444
|
+
py -3.11 -m venv C:\Tools\control-expert-mcp
|
|
445
|
+
C:\Tools\control-expert-mcp\Scripts\python.exe -m pip install .\control_expert_mcp-0.9.0-py3-none-any.whl
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
Use the actual downloaded filename, then point your client to that environment's Python executable. Disconnected installations also need a compatible dependency wheelhouse prepared on a connected Windows machine.
|
|
449
|
+
|
|
450
|
+
The [publish workflow](.github/workflows/publish.yml) reruns CI and uploads validated artifacts using PyPI Trusted Publishing with GitHub OIDC:
|
|
451
|
+
|
|
452
|
+
1. Update the version in `pyproject.toml` and let CI pass.
|
|
453
|
+
2. Create the matching `v<version>` tag and publish a GitHub Release for it.
|
|
454
|
+
3. Verify publication and installation in a clean environment.
|
|
455
|
+
|
|
456
|
+
Production publishing requires a tag matching the wheel version. Manual workflow dispatch defaults to TestPyPI; its publisher must be configured separately. Jobs use the `pypi` or `testpypi` GitHub environment. Published version filenames cannot be reused.
|
|
457
|
+
|
|
458
|
+
## Contributing
|
|
459
|
+
|
|
460
|
+
Bug reports, documentation improvements, and focused pull requests are welcome.
|
|
461
|
+
|
|
462
|
+
1. Describe the problem or intended behavior in an issue or pull request.
|
|
463
|
+
2. Follow the existing Python style: four-space indentation, type hints for public helpers, and concise docstrings.
|
|
464
|
+
3. Add or extend an MCP prompt for each new capability, including the validated tool sequence, prerequisites, and known gotchas.
|
|
465
|
+
4. Update the README tool reference when capabilities change.
|
|
466
|
+
5. Run the relevant offline checks and document local integration validation when available: CPU, Control Expert version, prerequisites, commands, and results. State any environment limitations.
|
|
467
|
+
|
|
468
|
+
Use concise, descriptive commit subjects. Keep customer exports, proprietary reference data, vendor binaries, generated archives, and credentials out of commits. See [AGENTS.md](AGENTS.md) for repository conventions.
|
|
469
|
+
|
|
470
|
+
## License and affiliation
|
|
471
|
+
|
|
472
|
+
The package declares the **MIT** license in [pyproject.toml](pyproject.toml).
|
|
473
|
+
|
|
474
|
+
This project is not affiliated with or endorsed by Schneider Electric. Control Expert and Unity Pro are Schneider Electric products; their software, licenses, and documentation are supplied separately.
|