# cx-programmer-mcp

An MCP (Model Context Protocol) server for editing OMRON CX-Programmer ladder logic programs programmatically - without opening the GUI.

> **v0.2** - Adds `list_cpu_instructions` tool, CP1E-NA instruction table, and fixes comparison mnemonic parsing (`LD>=`, `AND<>`, `OR<=`, etc.).

Works with `.CXP` / `.CXT` files for **OMRON CJ/CP/CS series PLCs**.

> **Scope**: Programs, Sections, Ladder Mnemonics, rung comments, and symbol table only.
> Does **not** touch PLC Setup, I/O Table, network configuration, passwords, or transfer to PLC.

---

## How it works

OMRON documents `.CXP` as a compressed version of `.CXT`. `.CXT` is a text-based format that CX-Programmer can import/export. This server reads `.CXP` or `.CXT`, edits the program in memory, then saves the result as `.CXT` / `.CXP` for review in CX-Programmer before deploying to a real PLC.

Uses Python MCP SDK v2 (`MCPServer`) with `stdio` transport.

---

## Requirements

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) package manager
- CX-Programmer installed (to open `.cxp` output and download to PLC)

---

## Installation

```powershell
cd cx-programmer-mcp
uv sync
uv run cx-programmer-mcp
```

---

## MCP Client Setup

Add this to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "cx-programmer": {
      "command": "uv",
      "args": ["run", "cx-programmer-mcp"],
      "cwd": "ABSOLUTE_PATH_TO_THIS_FOLDER"
    }
  }
}
```

**Windows example:**
```json
"cwd": "C:\\Users\\yourname\\cx-programmer-mcp"
```

Optional - restrict file access to specific folders:
```
CX_MCP_ALLOWED_ROOTS=C:\PLC_Projects
```

---

## Project Template Setup

### Built-in template (CJ2M CPU11)

A native CJ2M CPU11 template is included. Generate a blank project:

```powershell
uv run python make_template.py
```

### Other PLC models

Each PLC model has a different binary configuration. For models other than CJ2M CPU11:

1. Open CX-Programmer on your machine
2. Create a **new empty project** for your PLC model (CP1L, CS1G, CP1E-NA, etc.)
3. Save it as `.CXP` or `.CXT`
4. **Place the file in the `project/` folder**
5. Update `make_template.py` to point to your file:

```python
SRC = Path(__file__).parent / "project" / "your_blank_template.cxp"
```

6. Run `make_template.py` once

---

## Example Program

An example ladder program is included: `project/example_basic_io.cxp`

It demonstrates a simple conveyor/IO controller with:
- Manual output control (hold-to-run)
- Scheduled auto run via RTC (configurable via DM)
- Timer-based duration
- SET/RSET latch
- Emergency reset

To rebuild it from source:

```powershell
uv run python make_template.py
uv run python build_program.py
```

Output: `project/example_basic_io.cxp` - open in CX-Programmer to review and download.

---

## Run Tests

```powershell
uv run pytest -q
```

---

## Available MCP Tools

### Read-only

| Tool | Description |
|---|---|
| `list_project_templates` | List available built-in project templates |
| `session_status` | Current revision, dirty flag, undo depth |
| `project_summary` | PLC model, I/O config, and program tree |
| `list_programs` | List all programs in the loaded project |
| `list_sections` | List sections and rung counts in a program |
| `get_program_context` | Full ladder content with rung analysis (reads/writes/AST) |
| `get_rungs` | Get rungs from one section with optional analysis |
| `analyze_rung` | Parse one rung into mnemonic, boolean AST, reads/writes, timers, counters |
| `simulate_rung` | Boolean simulation of a rung (supported subset only) |
| `search_program` | Search mnemonic text, addresses, comments, and symbols |
| `cross_reference_address` | Find every reference to an address (read/write/coil/set/reset) |
| `program_diagnostics_tool` | Report duplicate coils, SET/RSET imbalance, unclassified instructions |
| `compile_structured_rung` | Convert JSON boolean expression to mnemonic lines (dry-run) |
| `validate_program` | Validate program XML structure |
| `project_diff` | Diff two loaded projects |
| `semantic_snapshot` | Semantic JSON snapshot of the full project for AI review |
| `list_cpu_instructions` | List all known instructions for a CPU model, grouped by family |

### Session edits (in-memory, undoable)

| Tool | Description |
|---|---|
| `replace_rung` | Replace a rung's mnemonic instructions |
| `replace_rung_structured` | Replace a rung using a JSON boolean expression |
| `insert_rung` | Insert a new rung at a given index |
| `delete_rung` | Delete a rung |
| `patch_program` | Batch multiple rung edits atomically |
| `close_project` | Discard the session without saving |

### File and app

| Tool | Description |
|---|---|
| `load_project` | Load a `.cxp` or `.cxt` file into a session |
| `create_project_from_template` | Create a new blank project from a built-in template |
| `save_cxt` | Write the current session to disk as `.cxt` |
| `launch_in_cx_programmer` | Save and open the project in CX-Programmer (Windows) |

---

## CP1E-NA Instruction Support

`list_cpu_instructions` returns 60+ instructions for the CP1E-NA, grouped by family:

- **contact** - LD, LDNOT, AND, ANDNOT, OR, ORNOT
- **compare** - CMP, CMPL, LD=/LD<>/LD</LD<=/LD>/LD>=, AND=/OR= variants
- **move** - MOV, MOVL, MVN, XFER, BSET, XCHG, DIST, COLL
- **byte_move** - MOVB, MOVD, MOVW
- **math** - ADD, SUB, MUL, DIV, INC, DEC, ANDW, ORW, XORW, COM, shift/rotate
- **conversion** - BIN, BCD, BINS, BCDS, BINL, BCDL
- **timer** - TIM, TIMH, TIMX, TIMHX
- **counter** - CNT, CNTR, CNTX, CNTRX
- **control_flow** - JMP, JME, CJP, IL, ILC
- **other** - NOP, STUP, TXD, RXD (serial, CP1E-NA only)

Pass `cpu_model="CP1E-NA"` to the tool. Unknown models return `known: false` and a list of registered models.

---

## Project Structure

```
cx-programmer-mcp/
|-- src/cx_programmer_mcp/
|   |-- server.py              # MCP tool definitions
|   |-- cxt.py                 # CXT/CXP parser and editor
|   |-- ladder.py              # Mnemonic parser, analyzer, compiler, simulator
|   |-- cpu_instructions.py    # CPU-specific instruction tables (CP1E-NA, CJ2M, ...)
|   |-- diagnostics.py         # Program diagnostics and cross-reference
|   |-- recipes.py             # Reusable ladder patterns
|   |-- session.py             # In-memory session with undo/redo
|   |-- templates.py           # Built-in template registry
|   |-- templates/
|       |-- CJ2M_CPU11.cxt     # Native CJ2M CPU11 blank template
|-- tests/                     # Test suite
|-- project/                   # Output folder
|   |-- example_basic_io.cxp   # Example ladder program
|-- build_program.py           # Builds the example ladder program
|-- make_template.py           # Generates blank template from base .cxp
|-- pyproject.toml
```

---

## Notes

- Always run **Program Check in CX-Programmer** before downloading to a real PLC.
- This tool edits program logic only - I/O table, unit setup, and PLC configuration are preserved as-is from the template.
- `.CXP` output is binary-compatible with CX-Programmer 9.73 on CJ2M CPU11.
- For other PLC models, provide your own blank `.CXP` template (see Project Template Setup above).
- Comparison instructions (`LD>=`, `AND<>`, `OR<=`, etc.) are fully parsed and classified as family `compare` - no false warnings in diagnostics.