# Krita Illustration MCP

让 AI 大模型通过 MCP 直接控制本机 Krita。模型查看 `krita_preview` 返回的真实画布，决定下一步文档、图层和绘制操作；Krita Bridge 在主线程执行，所以变化会直接显示在 Krita 中。

复杂人物插画优先使用混合流程：客户端生成参考图 → 客户端生图工具转换线稿 → MCP 导入独立图层 → Krita 局部修正和导出。生成与原生笔画必须明确区分，不把导入 PNG 冒充逐笔绘制或自动语义分层。服务本身默认不调用外部生图 API、不读取厂商密钥；GPT/Gemini 仍只保留未配置的扩展接口。

## 当前能力

- 创建透明画布和独立图层。
- `krita_image` 检查 PNG 尺寸/哈希，并以来源标记导入新图层；保留图片副本，重复请求不重复导入。
- 查询文档/图层状态并返回真实 PNG 预览。
- 定义、裁剪、预览区域并创建/扩展/羽化蒙版。
- 用 `krita_inpaint` 将客户端或已配置 provider 生成的局部 PNG 按 Mask 应用为新图层。
- 创建 KRA checkpoint，恢复为新文档。
- 安全保存 KRA 和导出 PNG。
- 对关键原生修改使用持久化 `request_id` 去重。
- 用 `krita_paint` 调用 Krita Brush Engine 批量绘制有压力信息的笔画。
- 用 `krita_draw` 绘制直线、折线、贝塞尔曲线、矩形、椭圆和可填充多边形。
- 用 `krita_illustration` 持久化草稿、线稿、底色、阴影、高光、终检和导出阶段，未预览不能推进。

原生图元、局部清除、预览和保存已经通过牡丹绘制实机验证；人物逐曲线重画成本较高，因此不再作为复杂插画的推荐主流程。图片入口复用现有 Bridge `import_image`，本次仅需重新加载 MCP 服务，不必重新安装 Bridge。

## 目录

```text
src/krita_workbench/
  domain/             纯数据与规则
  application/        Krita 原生控制用例
  contracts/          MCP 与 Bridge 共享契约
  adapters/krita/     本机 Bridge 客户端
  adapters/storage/   job、region、checkpoint 持久化
  native/             Krita 插件与主线程操作
  transport/mcp.py    STDIO MCP 工具
docs/                 架构、契约、开发计划、启动说明
dist/                 Krita 插件 ZIP
```

## 安装 Krita Bridge

在 Krita 中选择“工具 → 脚本 → 导入 Python 插件”，导入：

```text
D:/krita-mcp/dist/krita_workbench_bridge-20260905.zip
```

启用插件并重启 Krita。详细步骤见 [native-bridge.md](D:/krita-mcp/docs/native-bridge.md)。

## 使用 uv 启动 MCP

先确保 `D:/krita-mcp/config.local.json` 与其中引用的 Bridge 配置存在，然后在 PowerShell 执行：

```powershell
cd D:/krita-mcp
uv run python -m krita_workbench --config D:/krita-mcp/config.local.json --check-config
uv run python -m krita_workbench --config D:/krita-mcp/config.local.json
```

第二条命令启动 STDIO MCP 服务，等待 MCP 客户端连接；它不是交互式命令行。

可使用 [config/mcp.example.json](D:/krita-mcp/config/mcp.example.json) 配置客户端直接启动该服务。

## 推荐调用顺序

复杂插画采用以下流程，参数示例见 [混合绘图流程](D:/krita-mcp/docs/hybrid-workflow.md)：

1. 客户端生图并确认参考图，再以参考图为编辑输入生成干净线稿。
2. 将 PNG 复制到 `D:/krita-mcp/artifacts/`，不扩大 Bridge 的 allowed roots。
3. `krita_image(action="inspect")` 获取真实尺寸，再新建匹配画布。
4. 分别导入 reference 和 lineart；隐藏 reference，预览检查线稿。
5. 对手、眼睛、头发或褶皱定义 region，创建/扩展/羽化 Mask。
6. 用客户端生成与 region 尺寸完全一致的修复 PNG，调用 `krita_inpaint`；结果会按 Mask 变成透明补丁并新增图层。
7. 预览修复结果，在新的修正图层用 `krita_paint`/`krita_draw` 补线；危险修改前 checkpoint。
8. 最终预览后 `krita_save_export`；导入的是栅格层，不是自动拆出的头发/皮肤/服装层。

需要全程原生绘制时，原有流程仍可选：

1. `krita_capabilities`
2. `krita_state`
3. `krita_document` 创建透明画布和目标图层
4. `krita_illustration(action="start")` 记录文档和五个目标图层
5. 通过 `krita_paint`/`krita_draw` 分批写入当前阶段图层
6. 每个主要阶段后 `krita_preview`，再用 `krita_illustration(action="advance")` 记录通过
7. 高风险修改前 `krita_history(action="checkpoint")`
8. 完成后 `krita_save_export`，记录 export 阶段并完成会话

`krita_capabilities.external_image_generation` 会显示保留的 `gpt`、`gemini` 槽位。默认 `enabled=false`、`configured=false`；只有未来显式实现并注入 provider adapter 后才会启用。

## 验证

测试只使用 mocks 和临时目录，不访问真实 Krita：

```powershell
$env:PYTHONPATH='D:/krita-mcp/src;D:/krita-mcp'
D:/krita-mcp/.venv/Scripts/python.exe -m unittest discover -s tests -t . -v
```

离线测试通过不等于真实 Krita 绘制验收。每个新增原生能力必须另做运行中 Krita 的可见操作和 preview 检查。