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