157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
# How To Use CODESYS MCP Bridge
|
|
|
|
This guide explains day-to-day usage of your CODESYS MCP bridge from Cursor.
|
|
|
|
## 1) Confirm prerequisites
|
|
|
|
- Windows VM agent is running on port `8787`
|
|
- Linux host can reach VM IP
|
|
- Same token is configured on both sides:
|
|
- VM: `CODESYS_AGENT_TOKEN`
|
|
- Cursor MCP config: `CODESYS_AGENT_TOKEN`
|
|
- **CODESYS IDE must be closed** for write operations (read operations work even with IDE open)
|
|
|
|
Quick connectivity check from Linux:
|
|
|
|
```bash
|
|
curl http://10.77.30.50:8787/health
|
|
```
|
|
|
|
## 2) Cursor MCP config (working example)
|
|
|
|
Update `~/.cursor/mcp.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"codesys-bridge": {
|
|
"command": "/home/nearxos/Projects/.venvs/winrm/bin/python",
|
|
"args": [
|
|
"/home/nearxos/Projects/gitea/codesys-mcp-agent/python_scripting/mcp_codesys_bridge/server.py"
|
|
],
|
|
"env": {
|
|
"CODESYS_AGENT_URL": "http://10.77.30.50:8787",
|
|
"CODESYS_AGENT_TOKEN": "<your-token>",
|
|
"CODESYS_AGENT_REQUEST_TIMEOUT_SEC": "30"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Reload MCP servers or restart Cursor after editing.
|
|
|
|
## 3) Available MCP tools
|
|
|
|
### Reading (works even with IDE open)
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `codesys_health` | Check VM agent status |
|
|
| `codesys_get_job` | Poll job status/result by ID |
|
|
| `read_project_inventory` | Read project tree + textual sources (POUs, GVLs, NVLs, structs) |
|
|
| `read_device_io` | Read device tree, I/O channels, variable mappings |
|
|
|
|
### Writing (requires CODESYS IDE to be closed)
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `write_pou` | Update single or batch textual objects (declaration + implementation) |
|
|
| `write_io_mapping` | Map IEC variables to device I/O channels |
|
|
| `manage_device` | Add, remove, update, rename devices; set device parameters |
|
|
| `sync_project` | **Batch push** -- apply textual updates, IO mappings, and device params in one save |
|
|
|
|
### Build & Deploy
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `create_project` | Create new empty CODESYS project on VM |
|
|
| `build_project` | Compile a project |
|
|
| `download_to_device` | Deploy to PLC (requires `CODESYS_AGENT_ALLOW_DOWNLOAD=true`) |
|
|
|
|
### Low-level
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `codesys_submit_job` | Submit any action directly to the job queue |
|
|
| `stage_existing_project` | Copy/move project into standardized folder |
|
|
|
|
## 4) Typical round-trip workflow
|
|
|
|
### Import existing project into Cursor
|
|
|
|
```
|
|
1. read_project_inventory → get tree + textual sources → populate codesys_tree/
|
|
2. read_device_io → get devices, I/O channels, variable mappings → populate codesys_tree/
|
|
```
|
|
|
|
### Edit locally
|
|
|
|
Edit `.st`, `.gvl`, `.nvl`, `.type.st` files under `codesys_tree/` in Cursor.
|
|
|
|
### Push changes back to VM project
|
|
|
|
```
|
|
3. sync_project (dry_run=true) → preview what will change
|
|
4. sync_project (dry_run=false) → apply all textual + IO mapping changes in one save
|
|
5. build_project → compile
|
|
6. download_to_device → deploy to PLC
|
|
```
|
|
|
|
For individual changes, use `write_pou` or `write_io_mapping` directly.
|
|
|
|
## 5) Safety-first usage
|
|
|
|
- Start with `dry_run=true` for all mutating operations.
|
|
- Keep `CODESYS_AGENT_ALLOW_DOWNLOAD=false` while validating.
|
|
- Enable download only when target routing and credentials are verified.
|
|
- Close the CODESYS IDE on the VM before any write/push operations.
|
|
|
|
## 6) Local project layout
|
|
|
|
Every project in `Codesys_Projects/projects/<name>/` uses this structure:
|
|
|
|
```
|
|
<project>/
|
|
├── config/project.json # VM paths, profile, target device
|
|
├── codesys_tree/ # 1:1 mirror of CODESYS IDE tree
|
|
│ └── Device/
|
|
│ ├── Plc Logic/Application/
|
|
│ │ ├── POUs/PLC_PRG/PLC_PRG.program.st
|
|
│ │ ├── GVL/GVL.gvl
|
|
│ │ └── 3.Function Blocks/fb_boiler/fb_boiler.fb.st
|
|
│ └── EtherCAT_Master/EK1100/
|
|
│ ├── K1/K1.io_mapping.txt
|
|
│ └── K2/K2.io_mapping.txt
|
|
└── docs/
|
|
```
|
|
|
|
`codesys_tree/` is the canonical source layout. It mirrors the hierarchical
|
|
structure inside the CODESYS IDE so every folder and file maps 1:1 to a
|
|
CODESYS tree node.
|
|
|
|
## FAQ
|
|
|
|
### Do we need to keep CODESYS IDE open?
|
|
|
|
- **No.** The agent launches `CODESYS.exe` with `--noUI --runscript` for all operations.
|
|
- **Read operations** (inventory, device I/O) work even if the IDE has the project open (uses readonly mode).
|
|
- **Write operations** (write_pou, sync_project, manage_device) require the IDE to have the project **closed**, because CODESYS project files are exclusively locked.
|
|
- A CODESYS installation and valid profile are still required on the VM.
|
|
|
|
### Can we read existing CODESYS projects?
|
|
|
|
- Yes. Use `read_project_inventory` for sources and `read_device_io` for device/IO info.
|
|
- Sources are written into `codesys_tree/` mirroring the exact CODESYS IDE hierarchy.
|
|
|
|
### Can we modify device I/O mappings?
|
|
|
|
- Yes. Use `write_io_mapping` with device_path + param_id + variable.
|
|
- Or use `sync_project` with `io_mappings` for batch updates.
|
|
- Or import/export CSV via `read_device_io(export_csv_path=...)` and `write_io_mapping(import_csv_path=...)`.
|
|
|
|
### Can we add/remove devices?
|
|
|
|
- Yes. Use `manage_device` with operations like `add`, `remove`, `update`, `rename`, `enable`/`disable`, `set_param`.
|
|
- Device type/id/version values come from `read_device_io` output or the CODESYS device catalog.
|