# CSP Companion MCP

[简体中文](README.zh-CN.md)

An experimental, unofficial MCP server for CLIP STUDIO PAINT's Companion
protocol. Connect an MCP client to CSP over local TCP, without desktop input
automation or desktop screenshots.

## Features and limits

- Connect and disconnect after manual Companion pairing.
- List Quick Access items and execute enabled, locally allowlisted items.
- Read synchronized brush state; request color, brush size and opacity changes.
- Request canvas zoom, rotation and flipping.
- Retrieve composite canvas previews exposed by the Companion protocol.

This is **not a general layer API**. It cannot enumerate layers, edit layer
pixels, split artwork into layers, paint strokes, or target documents by a
stable document ID. Commands affect CSP's currently active document.

**Validation:** authentication, Quick Access listing and reconnecting were
verified against CSP 5.1.4 on Windows. Mutation, navigation and preview
features have mock coverage but have not been verified against real CSP.
Protocol acknowledgement alone does not prove the canvas changed.
See [VALIDATION.md](VALIDATION.md).

## Requirements

- Windows (the platform used for live validation).
- Python 3.11 or newer and the dependencies in `requirements.txt`.
- CLIP STUDIO PAINT with Companion mode available and enabled.
- A client supporting MCP over stdio, such as Codex.

Other operating systems have not been validated.

## Installation

Clone this repository and open PowerShell in its directory:

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

You may use a newer supported Python interpreter. The server and virtual
environment can be stored on any drive.

## Pair once, locally

1. In CSP, open **File > Connect to smartphone** to enable Companion mode.
2. Obtain the complete pairing URL from CSP's QR code, for example by scanning
   it with your phone and copying the URL to your own computer.
3. In an interactive PowerShell terminal, run:

   ```powershell
   .\.venv\Scripts\python.exe setup_pairing.py
   ```

4. Paste the URL into the hidden prompt. The script saves `session.json` with
   restricted file permissions. Do not paste it into chat or a public issue.
5. Optionally run `check_connection.py` with the same interpreter. It connects
   and disconnects without executing canvas commands. Do not run it while
   another Companion client is connected.

Only loopback and this computer's own IPv4 addresses are accepted. CSP rotates
the connection password; reconnecting uses the locally saved credentials.
If pairing expires, privately back up `session.json` and pair again. The
setup script will not overwrite an existing pairing file.

## Configure Codex

Add a server entry to your Codex MCP configuration, substituting your actual
absolute paths (the examples below are placeholders):

```toml
[mcp_servers.csp-companion]
command = 'F:\Projects\csp-companion-mcp\.venv\Scripts\python.exe'
args = ['-u', 'F:\Projects\csp-companion-mcp\server.py']

[mcp_servers.csp-companion.env]
PYTHONUTF8 = '1'
CSP_COMPANION_OUTPUT = 'F:\CSPoutput\CompanionPreviews'
```

Restart or refresh your MCP client. First call `csp_status`, then
`csp_connect`, then `csp_quick_access_list`. Execute changes only when the
user requests them. Never retry a mutation automatically after a timeout;
the operation may already have reached CSP.

Other stdio MCP clients can use the same Python executable and server script.

## Tools

| Tool | Purpose |
| --- | --- |
| `csp_status` | Read connection and capability status |
| `csp_connect` / `csp_disconnect` | Manage the Companion connection |
| `csp_quick_access_list` | List actual Quick Access items and allowlist status |
| `csp_quick_access_execute` | Execute one enabled, allowlisted item |
| `csp_brush_state` | Read received brush synchronization fields |
| `csp_set_color` | Request an RGB color change |
| `csp_set_brush` | Request brush size and/or opacity changes |
| `csp_navigate` | Request canvas view changes |
| `csp_preview_gallery` | Read available composite preview metadata |
| `csp_preview_read` | Save a bounded composite preview block as PNG |

The default `policy.json` only allows Quick Access `basiccommand` entries
named `undo` and `redo`; allowed tool UUIDs start empty. Items must also be
present and enabled in CSP. No command runs automatically. Add allowlist
entries only using identifiers actually returned by CSP.

## Local paths

| Variable | Default |
| --- | --- |
| `CSP_COMPANION_CONFIG` | `session.json` beside `server.py` |
| `CSP_COMPANION_POLICY` | `policy.json` beside `server.py` |
| `CSP_COMPANION_OUTPUT` | `previews/` beside `server.py` |

`setup_pairing.py` and `check_connection.py` use `session.json` beside their
scripts. If you override the server configuration path, securely relocate the
pairing file yourself and preserve its permissions.

Previews stay on the local filesystem; content returned to your MCP client is
handled under that client's data policies. Never commit credentials or artwork.

## Tests

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe smoke_mcp.py
```

These tests use simulated CSP responses and a real stdio MCP handshake. They
do not connect to CSP or modify artwork. Generated files go to ignored test
directories.

## Contributing and attribution

Bug reports and contributions are welcome. Include Python/CSP versions and
reproduction steps, but remove pairing URLs, credentials and private artwork.
Describe whether a result came from mock tests or real CSP.

This project was developed with AI assistance. It is an independent project,
not an official CELSYS or OpenAI integration.

Protocol references: [clipremote](https://github.com/chocolatkey/clipremote)
(MIT) and [LumaPaletteCSP protocol notes](https://github.com/andyubird/LumaPaletteCSP/blob/main/PROTOCOL.md).
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attribution and scope.

Licensed under [MIT](LICENSE). CLIP STUDIO PAINT belongs to CELSYS.