Metadata-Version: 2.4
Name: krita-cli
Version: 1.0.1
Summary: SOTA CLI + MCP server for programmatic painting in Krita
Project-URL: Homepage, https://github.com/edithatogo/krita-cli
Project-URL: Repository, https://github.com/edithatogo/krita-cli
Project-URL: Issues, https://github.com/edithatogo/krita-cli/issues
Project-URL: Changelog, https://github.com/edithatogo/krita-cli/blob/master/CHANGELOG.md
Author: Krita MCP Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,automation,claude,cli,fastmcp,krita,mcp,painting
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Editors :: Raster-Based
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastmcp>=3.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: beartype>=0.18.0; extra == 'dev'
Provides-Extra: numpy
Requires-Dist: numpy>=1.26.0; extra == 'numpy'
Description-Content-Type: text/markdown

# Krita MCP Server & CLI

Let AI agents paint in [Krita](https://krita.org/) via the [Model Context Protocol](https://modelcontextprotocol.io/).

This subproject provides the core implementation of the Krita-MCP ecosystem, including the FastMCP server, the `krita` CLI, and the high-performance Python plugin.

## 🛠️ Components

1. **Krita Plugin** (`krita-plugin/`) — A Python plugin for Krita that exposes a thread-safe HTTP server on `localhost` using the configured port (default `5678`).
2. **MCP Server** (`src/krita_mcp/`) — A FastMCP server exposing 40+ painting and manipulation tools.
3. **Krita CLI** (`src/krita_cli/`) — A Typer-based command line interface for human operators.
4. **Krita Client** (`src/krita_client/`) — A reusable, fully-typed Python library for Krita automation.

## 🚀 Setup

### 1. Krita Plugin Installation
Copy the contents of `krita-plugin/` to your Krita resources:
- **Windows**: `%APPDATA%\krita\pykrita\`
- **Linux**: `~/.local/share/krita/pykrita/`
- **macOS**: `~/Library/Application Support/krita/pykrita/`

Enable **"Krita MCP Bridge"** in Krita (Configure Krita → Python Plugin Manager) and restart.

### 2. Environment Setup
```bash
# Install dependencies with uv
uv sync
```

### 3. Windows Validation Checklist
Before debugging the plugin, make sure the local Python runtime is healthy:

1. `python -c "import ssl, ctypes"` must succeed.
2. `python scripts/windows_preflight.py` should report a clean Windows setup.
3. `uv run pytest tests/e2e/test_e2e_mock.py` should pass without Krita.
4. The plugin files must exist under `%APPDATA%\krita\pykrita\kritamcp\`.
5. Krita must be restarted after enabling **Krita MCP Bridge** in the Plugin Manager.
6. The plugin should expose `http://127.0.0.1:<configured-port>/health` once Krita finishes loading.

If Krita starts but `/health` never appears, check the diagnostic artifacts in your home directory:
- `~/kritamcp_startup.log`
- `~/kritamcp_diag.log`

If those logs are missing entirely, the plugin likely was not enabled or did not load during startup.

## 🔧 CLI Commands

The `krita` CLI is grouped into logical subcommands:

- **Painting**: `stroke`, `fill`, `clear`, `draw-shape`
- **Layers**: `layers list`, `layers create`, `layers select`, `layers delete`
- **Selection**: `selection select-rect`, `selection transform`, `selection save-channel`
- **Canvas**: `canvas-info`, `current-color`, `current-brush`
- **Session**: `history`, `replay`, `rollback`, `batch`
- **System**: `health`, `config`, `capabilities`, `security-status`

Run `uv run krita --help` for full details.

## 🤖 MCP Server Tools (40 Total)

The MCP server exposes a vast range of capabilities to AI agents:

| Category | Key Tools |
|----------|-----------|
| **Core** | `krita_health`, `krita_new_canvas`, `krita_save`, `krita_open_file` |
| **Painting** | `krita_stroke`, `krita_fill`, `krita_draw_shape`, `krita_set_color`, `krita_set_brush` |
| **Selection** | `krita_select_rect`, `krita_select_ellipse`, `krita_select_polygon`, `krita_select_by_color`, `krita_select_by_alpha` |
| **Selection Ops** | `krita_transform_selection`, `krita_grow_selection`, `krita_combine_selections`, `krita_invert_selection` |
| **Persistence** | `krita_save_selection`, `krita_load_selection`, `krita_save_selection_channel`, `krita_list_selection_channels` |
| **Automation** | `krita_batch`, `krita_rollback`, `krita_get_command_history` |
| **Inspection** | `krita_get_canvas_info`, `krita_get_color_at`, `krita_selection_stats`, `krita_security_status` |

## ⚡ Performance

The plugin uses **numpy-accelerated** direct pixel manipulation for rendering. This ensures that strokes and shapes are rendered significantly faster than standard Python loops, especially on high-resolution canvases.

## 🔒 Security

Krita MCP includes a built-in security layer to protect your system:
- **Path Sanitization**: Restricts file operations to allowed directories.
- **Resource Limits**: Prevents OOM by limiting max canvas dimensions and layer counts.
- **Rate Limiting**: Throttles rapid command execution.
- **Security Tool**: `krita_security_status` allows agents to check active limits.

## 📄 License
MIT
