# 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.