Update .gitignore and README.md for CODESYS MCP project. Added entries to .gitignore for VSIX files and VS Code settings. Expanded README to include architecture, components, deployment instructions, and details about the Cursor extension.

2026-05-24 15:47:21 +03:00
parent acdd740d01
commit bedc5d0628
55 changed files with 11120 additions and 3 deletions
--- a/python_scripting/how-to-use-codesys-mcp.md
+++ b/python_scripting/how-to-use-codesys-mcp.md
@@ -0,0 +1,156 @@
+# 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.