krita-codex-mcp

# Krita Codex MCP 服务器 <!-- mcp-name: io.github.cyyprezz/krita-codex-mcp --> 通过安全的本地模型上下文协议（MCP）服务器，从 OpenAI Codex 控制 Krita，适用于 Windows。 [PyPI 软件包](https://pypi.org/project/krita-codex-mcp/) · [GitHub 发布](https://github.com/cyyprezz/krita-codex-mcp/releases) · [Windows 安装指南](docs/windows-installation.md) 一个优先考虑 Windows 的本地 MCP 服务器，允许 Codex 通过小型身份验证桥接器检查和控制 Krita。MCP 进程使用 STDIO。Krita Python 插件仅在 `127.0.0.1` 上监听，验证共享的 bearer token，并将每个 Krita API 调用分派到 Qt 的主线程。 该仓库是优先考虑 Windows 的集成，具有基于能力的运行时兼容性检查。Krita 5.3.2.1 是一个已测试的构建版本，但不是硬版本要求。服务器故意公开一组小而集成的工具，而不是大量的微工具： | 工具 | 用途 | |---|---| | `krita_state` | 活动文档、画布/颜色空间、带有 UUID 的递归图层树、活动图层和当前绘画状态 | | `krita_preview` | 直接作为 MCP 图像内容返回的整个画布或精确裁剪的 PNG | | `krita_canvas` | 采样颜色；调整大小、缩放、裁剪、旋转或翻转；导入可编辑的栅格图层 | | `krita_edit` | 创建/细化/移动选择；本地复制、剪切、粘贴、选择到图层、填充和清除 | | `krita_document` | 检查运行时兼容性；列出、创建、打开、激活、保存和关闭文档 | | `krita_layers` | 读取/编辑图层树，安全地重新关联，并通过稳定的 UUID 转换图层 | | `krita_history` | 读取撤销/重做状态并执行有界的撤销或重做步骤 | | `krita_brush` | 读取/设置原生画笔状态并搜索已安装的 Krita 预设 | | `krita_paint_path` | 通过 Krita 的原生 `Node.paintLine` API 和活动画笔预设的压力感知线段 | | `krita_draw` | 原生预设支持的线条、开放/封闭路径、多边形、矩形和椭圆 | | `krita_color` | KRA 支持的项目调色板、Krita 调色板色块、颜色替换和安全校正过滤器 | | `krita_asset` | 导出图层 PNG 以及面向 Unity 的动画、图块集和命名区域包，并带有直接预览 | | `krita_save_export` | 在配置的根目录下保存 KRA 并导出 PNG | ```text Codex -> 本地 STDIO MCP 进程 -> 身份验证的 127.0.0.1 HTTP 桥接器 -> 队列化、超时感知的 Qt 主线程调度 -> Krita Python API ``` 桥接器没有任意的 Python 执行工具，也没有直接的像素绘画回退。实际绘画、形状、替换填充和校正过滤器通过原生 Krita 操作或笔画 API 进行。如果运行的 Krita 构建版本缺少某个功能，`krita_state` 和 `krita_document(action="compatibility")` 会报告受影响的工具。调用该功能会返回结构化的错误；桥接器永远不会静默地切换到不同的渲染后端。 ## 快速开始 这需要一个 Windows Krita 构建版本，通过实时兼容性检查并在 `PATH` 上安装 [`uv`/`uvx`](https://docs.astral.sh/uv/getting-started/installation/)。关闭 Krita，确保允许的目录已经存在，并从 PyPI 安装当前版本： ```powershell uvx --from "krita-codex-mcp==0.2.0" ` krita-codex-install install ` --allowed-root "C:\Krita Work" ``` 然后按照以下顺序进行实际的 Krita 会话： 1. 在 Krita 的 Python 插件管理器中启用 **Krita Codex Bridge**。 2. 重启 Krita，以便安装的插件和共享协议包一起加载。 3. 运行相同版本的 `krita-codex-install check`，并要求 `Ready for productive use.` 或明确的有限模式成功消息。 4. 使用 `krita-codex-install codex-config` 预览无需检查、精确版本固定的 `uvx` Codex 模块。 5. 仅在明确确认后应用，重启 Codex，验证 `krita_state` 和 `krita_preview`，然后再开始正常工作。 安装和更新永远不会关闭 Krita。如果身份验证的桥接器正在运行，则在任何已安装文件被更改之前，替换将被拒绝，并且必须手动关闭 Krita。繁忙的本地桥接器端口也会阻止安装程序在替换开始之前。 对于个人安装，请使用用户级别的 `C:\Users\<you>\.codex\config.toml`。这是推荐的选项，因为服务器随后可用于所有本地 Codex 任务和 Git 工作树。生成的模块使用 `uvx`，没有检查 `cwd`，并固定与安装的插件相同的确切发行版本。安装程序仅在显示完整预览并收到明确确认后才会更改该文件。永远不要提交个人配置。有关详细信息，请参见 [Windows 安装指南](docs/windows-installation.md#4-configure-codex)。 预飞行检查本地配置、完整的已安装哈希清单、轮子/插件/协议版本、环回端口、身份验证和正在运行的 Krita 能力配置文件。正在运行的插件报告发行版、协议和 Krita 版本，而不添加 MCP 工具。检查创建了一个 disposable 文档，验证了一个新的画笔图层、原生绘图、撤销/重做、事务性重新关联、直接 PNG 预览字节和临时 KRA/PNG 输出在允许的根目录下。它恢复了先前的活动文档并删除了所有临时文件。 未知 Krita 版本在所有关键功能通过时被接受。缺少可选功能会产生 `limited` 警告，指出受影响的 MCP 工具；缺少投影、持久性、稳定的图层树或文档生命周期 API 仍然是关键的。相同的结构化报告可通过 `krita_state` 提供给 Codex，因此它可以避免不可用的操作。 ## 功能和 Krita 限制 当前版本支持原生预设支持的绘画和形状、持久的文档和图层编辑、选择、颜色操作、KRA/PNG 输出以及面向 Unity 的动画、图块集和命名区域包。预览和资产操作直接向 MCP 调用者返回 PNG 图像。重新导出保留 Unity `.meta` 边车文件，以实现稳定的生成文件名。 测试的 Krita 5.3.2.1 构建版本施加了几个安全限制。其他构建版本在运行时进行评估，并可能报告不同的可用功能： - 免费图层缩放、旋转、剪切和裁剪操作不是原生撤销命令。桥接器创建一个隐藏的备份图层，并在 KRA 保存、关闭并重新打开之前阻止第二次直接转换。`checkpoint_reopen=true` 可以自动执行此往返过程。 - 变换掩模在打开的文档中受到限制。相同会话的掩模突变/删除以及混合掩模和直接转换后端在 Krita 重启之前被阻止。 - `Node.paintLine` 需要整数 `QPoint` 值，因此在原生 API 边界处舍入传入的画布坐标。 - PNG 导出临时启用 Krita 批处理模式，以便没有格式对话框能够阻塞本地桥接器。 ## 超时和生产防护 超时是 Codex、MCP `BridgeClient`、本地 HTTP 桥接器和 Qt 主线程调度器之间的操作特定： | 操作类别 | 调度器超时 | |---|---:| | 读取和正常编辑 | 30 秒 | | 文档打开和检查点保存 | 120 秒 | | KRA/PNG、图层、动画、图块集和区域导出 | 180 秒 | 推荐的 Codex `tool_timeout_sec` 是 210 秒，以便 MCP 客户端可以接收桥接器的结构化结果。如果已超时 Qt 操作已经运行，则 `operation_may_complete=true` 被保留，后续调用收到 `BRIDGE_BUSY` 直到 Krita 实际完成。 请保持 `allowed_roots` 尽可能窄，并保持普通的版本或手动 KRA 备份，不要将桥接器超时视为取消。桥接器仅限本地，并恰好绑定到 `127.0.0.1`。 参见 [Windows 安装](docs/windows-installation.md)、[工具行为和限制](docs/tool-reference.md)、[安全](SECURITY.md) 和 [GitHub 发布](https://github.com/cyyprezz/krita-codex-mcp/releases)。 ## 许可证 在 [MIT 许可证](LICENSE) 下发布。版权所有 (c) 2026 Nicklas Desens。