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/codesys-mcp-bridge-operations.md
+++ b/python_scripting/codesys-mcp-bridge-operations.md
@@ -0,0 +1,115 @@
+# CODESYS MCP Bridge Operations Guide
+
+This guide covers deployment, security, and smoke tests for the recommended architecture.
+
+## 1) Components
+
+- Linux: `mcp_codesys_bridge/server.py` (MCP server for Cursor)
+- Windows VM: `windows_codesys_agent/agent.py` (job API)
+- Windows VM scripts: `windows_codesys_agent/scripts/*.py`
+
+ScriptEngine actions (`create_project`, `read_project_inventory`, `build_project`, `download_to_device`) are executed by launching `CODESYS.exe --runscript --noUI` from the agent.
+
+## 2) Deployment Steps
+
+1. Copy `windows_codesys_agent` to the Windows VM.
+2. Install dependencies and start the agent on port `8787`.
+3. Open firewall only to trusted Linux host IP.
+4. Configure Linux MCP server with `CODESYS_AGENT_URL` and `CODESYS_AGENT_TOKEN`.
+5. Register MCP server in Cursor settings and restart Cursor.
+
+## 3) Security Checklist
+
+- Use a long random `CODESYS_AGENT_TOKEN`.
+- Restrict inbound access by firewall rules.
+- Keep `CODESYS_AGENT_ALLOW_DOWNLOAD=false` until testing completes.
+- Use dry-run for all mutating calls first.
+- Rotate token after initial setup validation.
+
+## 4) Smoke Tests
+
+## 4.1 Health check
+
+Call MCP tool:
+
+- `codesys_health`
+
+Expected:
+
+- `ok: true`
+- correct `scripts_dir`
+
+## 4.2 Submit dry-run create project
+
+Call MCP tool:
+
+- `create_project`
+  - `project_name`: `SmokeTest`
+  - `output_dir`: `C:\\Temp\\codesys-tests`
+  - `dry_run`: `true`
+
+Expected:
+
+- returns `job_id`
+- job transitions `queued -> running -> succeeded`
+
+## 4.3 Poll job result
+
+Call MCP tool:
+
+- `codesys_get_job` with returned `job_id`
+
+Expected:
+
+- final `status: succeeded`
+- `result.dry_run: true`
+
+## 4.4 Run one safe write artifact action
+
+Call MCP tool:
+
+- `write_pou` with test content and `dry_run=false`
+
+Expected:
+
+- `artifact_file` created under `_mcp_generated` near project path.
+
+## 4.5 Read existing project
+
+If your existing project is scattered in an old location, stage it first:
+
+Call MCP tool:
+
+- `stage_existing_project`
+  - `source_path`: `C:\\Users\\nearxos\\OneDrive - individual\\Codesys_Home_Automation`
+  - `projects_root_dir`: `C:\\Users\\nearxos\\OneDrive - individual\\Codesys_Projects`
+  - `project_folder_name`: `Home_Automation` (optional)
+  - `move`: `false` (copy by default)
+  - `overwrite`: `false`
+
+Expected:
+
+- returns `job_id`
+- result contains `project_folder` and resolved staged `project_path`
+
+Then read inventory:
+
+Call MCP tool:
+
+- `read_project_inventory`
+  - `project_path`: `C:\\path\\to\\project.project` (or `.projectarchive`, or a folder with one project file)
+  - `max_depth`: `3`
+
+Expected:
+
+- `node_count > 0`
+- tree entries in `nodes[]`
+
+## 5) Enabling download to device
+
+Only after successful smoke tests:
+
+1. Set `CODESYS_AGENT_ALLOW_DOWNLOAD=true` on VM.
+2. Restart agent service.
+3. Run download tool in dry-run first, then actual run.
+4. Verify target routing, credentials, and safety state before start.