Codesys-MCP/python_scripting/codesys-mcp-bridge-operations.md

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.