# Codesys MCP

MCP bridge for working on CODESYS projects from Cursor, backed by a Windows agent in Parallels.

## Architecture

```
Cursor (Mac) → MCP bridge (FastMCP) → Windows agent (FastAPI :8787) → CODESYS ScriptEngine
```

## Components

| Path | Role |
|------|------|
| `python_scripting/mcp_codesys_bridge/` | MCP server for Cursor |
| `python_scripting/windows_codesys_agent/` | Windows job API + ScriptEngine scripts |
| `vscode_codesys_companion/` | Cursor/VS Code extension (UI, ST syntax, commands) |
| `deploy/windows/start-agent.bat.example` | Windows agent startup template |
| `deploy/cursor/mcp.json.example` | Cursor MCP config template |

## Deployment (Parallels)

### Windows VM

1. Copy `python_scripting/windows_codesys_agent/` to `C:\codesys-agent\`
2. Install Python 3.12 ARM64 and create venv: `python -m venv C:\codesys-agent\.venv`
3. `pip install -r requirements.txt`
4. Copy `deploy/windows/start-agent.bat.example` → `C:\codesys-agent\start-agent.bat` and set `CODESYS_AGENT_TOKEN`
5. Run `C:\codesys-agent\start-agent.bat` (listens on `0.0.0.0:8787`)

Current VM: **Windows 11** at `10.211.55.3` (Parallels shared network).

### Mac (Cursor)

1. `python3 -m venv .venv && .venv/bin/pip install -r python_scripting/mcp_codesys_bridge/requirements.txt`
2. Add MCP server config to `~/.cursor/mcp.json` (see `deploy/cursor/mcp.json.example`)
3. Restart Cursor / reload MCP servers

## Cursor extension (CODESYS MCP Companion)

The companion extension adds a **CODESYS sidebar**, command palette actions, ST syntax highlighting, and job polling UI — alongside the MCP tools used by the AI in chat.

### Install

```bash
cd vscode_codesys_companion
npm install && npm run compile && npm run package
cursor --install-extension codesys-mcp-companion-0.1.0.vsix
```

Or from Cursor: **Extensions → … → Install from VSIX** and select the `.vsix` file.

### Configure

Copy `.vscode/settings.json.example` to `.vscode/settings.json` (or set **Settings → CODESYS MCP Companion**):

- `codesys.agentUrl` → `http://10.211.55.3:8787`
- `codesys.agentToken` → same token as the Windows agent
- `codesys.pythonPath` → project `.venv/bin/python`
- `codesys.bridgeScriptPath` → path to `mcp_codesys_bridge/server.py`

Reload Cursor, then run **CODESYS: Connect MCP Bridge** and **CODESYS: Health Check**.

### Extension vs MCP server

| Feature | Cursor MCP (`~/.cursor/mcp.json`) | Companion extension |
|---------|-----------------------------------|---------------------|
| AI chat tools | Yes | No |
| Sidebar (Projects/Jobs/Actions) | No | Yes |
| ST syntax + snippets | No | Yes |
| Command palette workflows | No | Yes |
| Sync current `.st` file | No | Yes |

Both can run together; the extension spawns its own bridge process when you connect.

## Smoke tests

```bash
curl http://10.211.55.3:8787/health
```

Use MCP tools `codesys_health`, `create_project` (dry_run), `read_project_inventory`.

**Note:** Project paths on Parallels shared folders (`C:\Mac\Home\...` / OneDrive) may fail when the agent runs as SYSTEM. Use native Windows paths like `C:\Temp\codesys-tests\` for reliable ScriptEngine access.

## Docs

See `python_scripting/how-to-use-codesys-mcp.md` and `python_scripting/codesys-mcp-bridge-operations.md`.

## Origin

Ported from [codesys-mcp-agent](https://git.paraskeva.net/nearxos/codesys-mcp-agent).