# CorelDRAW Live MCP

Control the exact document already open in CorelDRAW through the Model Context Protocol. Version 0.2.2 focuses on safe live editing, predictable coordinates, atomic undo, and cross-model reliability.

> Windows-only: CorelDRAW automation uses the local COM API. The MCP server must run on the same Windows computer as CorelDRAW.
>
> **Supported usage scope:** This project is intended only for desktop applications and local CLI agents that support user-configured/custom MCP servers—for example Claude Desktop and compatible desktop/CLI clients such as Antigravity. It is not designed for browser-only AI websites that cannot start or connect to a local custom MCP server. A desktop ChatGPT client is supported only when that specific app/version provides custom local MCP configuration.

## What changed in 0.2.2

- Attaches to an existing CorelDRAW process by default; it will not silently launch a second instance.
- Binds every edit to an explicit document session.
- Uses one public coordinate system: page top-left, Y downward, millimetres.
- Applies related changes atomically as one CorelDRAW Undo command.
- Detects both stale agent revisions and external document changes before editing.
- Prevents preview/export from overwriting files unless `overwrite=true`.
- Keeps hidden and non-printable layers unchanged during preview and export.
- Lazily reconnects when CorelDRAW starts after the MCP server.
- Separates live edit, create, save, Save As, preview, and export.
- Exposes a compact 14-tool MCP catalog instead of 70+ overlapping tools.
- Fixes nested COM-thread deadlocks and double Y-coordinate conversion.

See [the phased implementation document](docs/PHASED_IMPLEMENTATION.md) for completed and planned phases.
Use [the manual Windows/CorelDRAW test plan](docs/MANUAL_TEST_PLAN.md) before production use.

## Requirements

- Windows 10/11
- CorelDRAW X6 or newer; certify your exact version before production use
- 64-bit Python 3.11–3.13 recommended
- Python bitness matching CorelDRAW

## Install

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
```

Optional features are separate so MCP-only users do not install heavy agent and data-processing packages:

```powershell
pip install ".[agent]"       # Streamlit + bundled LLM agent
pip install ".[datamerge]"   # Excel, barcode and image helpers
pip install ".[https]"       # Optional local HTTPS wrapper
pip install ".[all]"         # Everything
```

Start CorelDRAW and open the document you want to edit before starting the server.

```powershell
$env:COREL_ATTACH_POLICY = "existing_only"
python server\server.py --transport stdio
```

## MCP client configuration

Replace the two example paths with paths on the user's computer.

```json
{
  "mcpServers": {
    "coreldraw-live": {
      "command": "C:\\path\\to\\coreldraw-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\coreldraw-mcp\\server\\server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "COREL_ATTACH_POLICY": "existing_only",
        "COREL_TOOL_PROFILE": "compact"
      }
    }
  }
}
```

This local stdio configuration is intended for desktop applications and local CLI agents that support custom MCP servers, including Claude Desktop, Claude Code, Antigravity-compatible CLI environments, Gemini CLI, Cursor, and VS Code.

A desktop ChatGPT app should be treated as compatible only if its installed version supports adding and running a custom local MCP server. Browser-only ChatGPT and other web-only AI interfaces are outside the supported scope because they cannot directly run this local stdio process.

## Safe live-edit workflow

1. `corel_status`
2. `list_open_documents`
3. `attach_active_document` or `attach_open_document`
4. `inspect_document`
5. `apply_operations` using the returned revision
6. `render_preview` when visual verification is needed
7. `save_current_document` only when explicitly requested
8. `detach_document`

`attach_active_document` never creates or opens a document. `save_current_document` never invents another filename.

## Coordinate contract

All public geometry is expressed as:

```json
{
  "coordinate_space": "page_top_left",
  "unit": "mm",
  "bounds": {"x": 10, "y": 20, "width": 80, "height": 30}
}
```

- `(0,0)` is the page top-left.
- X increases right.
- Y increases down.
- The driver converts coordinates to CorelDRAW exactly once.

## Atomic operation example

```json
{
  "session_id": "sess_example",
  "expected_revision": 4,
  "label": "Update sale heading",
  "operations": [
    {
      "op": "text.set_content",
      "shape_id": "128",
      "value": "SUMMER SALE"
    },
    {
      "op": "text.set_style",
      "shape_id": "128",
      "font_family": "Montserrat",
      "font_size_pt": 30,
      "bold": true
    },
    {
      "op": "shape.move",
      "shape_id": "128",
      "x": 20,
      "y": 15
    }
  ]
}
```

Supported operation names in 0.2.2:

- `text.set_content`
- `text.set_style`
- `text.create_frame`
- `shape.set_bounds`
- `shape.move`
- `shape.resize`
- `shape.create_rectangle`
- `shape.rotate`
- `shape.rename`
- `shape.delete`
- `fill.set_cmyk`
- `fill.set_rgb`

## Tool profiles

Production default:

```powershell
$env:COREL_TOOL_PROFILE = "compact"
```

Temporary migration profile exposing the original tools:

```powershell
$env:COREL_TOOL_PROFILE = "legacy"
```

The legacy profile is not recommended for general AI clients because the large catalog reduces tool-selection reliability.

## Tests

Platform-independent unit tests:

```powershell
python -m unittest discover -s tests -v
python -m compileall -q server tests
```

Windows/CorelDRAW end-to-end test:

```powershell
python server\test_e2e.py
```

The final release gate must be run on Windows with each supported CorelDRAW version. Linux tests cannot validate COM behaviour.

## Reference-image reconstruction

The project retains a reconstruction foundation, but a flattened image cannot guarantee a perfect editable clone. Production reconstruction requires OCR, font matching, asset detection, vector tracing, and a render-and-compare loop. See Phase 3 in the implementation plan.

## Security

- Never commit `.env` files, API keys, logs, generated customer designs, or crash dumps.
- Keep the local server on stdio or loopback-only networking.
- Do not expose CorelDRAW COM automation directly to the public internet.
- Require explicit confirmation before overwrite, destructive edits, or remote execution.
- Set `COREL_OUTPUT_ROOT` to restrict Save As, preview, and export destinations to one approved directory.
- Preview/export defaults to `overwrite=false` and rejects an existing destination.

## License

Apache License 2.0. See `LICENSE` and `NOTICE`.