116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# 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.
|