gimp-mcp

<p align="center"> <img src="assets/crest.png" alt="gimp-mcp crest" width="300"> <br> _{<i>本徽章由 gimp-mcp 代理完全设计 - 形状 + 弧形文本 + 透明度，无需人工参与像素</i>} </p> ``` _ __ _(_)_ __ ___ _ __ _ __ ___ ___ _ __ / _` | | '_ ` _ \| '_ \ _____| '_ ` _ \ / __| '_ \ | (_| | | | | | | | |_) |_____| | | | | | (__| |_) | \__, |_|_| |_| |_| .__/ |_| |_| |_|\___| .__/ |___/ |_| |_| ``` # gimp-mcp [](https://github.com/constant-itis/gimp-mcp/actions/workflows/ci.yml) 通过 AI 代理驱动 **GIMP 2.10**。一个 [MCP](https://modelcontextprotocol.io) 服务器桥接工具调用到 GIMP 的内置 **Script-Fu** 服务器，暴露整个 GIMP 程序数据库（每个过滤器、图层操作、变换、导出器）— 以及一个 **视觉反馈环路**，以便模型可以实际看到它所编辑的内容。 ``` Agent ──MCP/stdio──▶ server.py ──TCP :10008──▶ GIMP Script-Fu server ──▶ GIMP PDB ``` 与任何 MCP 客户端配合使用。以下示例使用 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)。 ## 工作原理：模型看到自己的编辑 最有用的工具是 `look` — 它渲染当前图像并以图像形式内联返回给模型，这样就不会进行盲编辑。环路如下： > **编辑 → `look` → 判断 → 调整** 由 `inspect`（区域亮度/对比度 + 文本放置提示 — 区域的量化“此区域是否足够暗以容纳浅色文本？”）和 `describe`（确切大小/模式/图层/ dpi）支持，代理按照人的方式工作：进行更改，查看结果，纠正。其他所有操作都服务于此环路。 `look` 和 `render_preview` 接受一个 `bg` 参数 — `auto`（默认）当图像具有 alpha 时显示透明 **棋盘格**，以便实际看到透明/剪切艺术而不是白色。 使用 `bg=black`/`bg=white` 预览艺术在暗或亮背景（衬衫、贴纸、页面）上的效果，或使用 `bg=none` 保留 alpha。 ## 构建用于驱动它的代理（前沿 *和* 本地模型） 工具表面根据 LLM 的实际工作方式设计，而不是人类点击的方式： - **看到透明度，而不是白色** — 视觉环路默认将 alpha 复合到棋盘格上，因此模型永远不会在剪切艺术上进行盲编辑。 - **无需坐标数学** — `place` / `add_text(anchor=…)` 按重力定位（`center`、`top-center`、`bottom-left`，...）。一次调用，而不是小型模型经常出错的测量 → 计算 → 设置偏移的往返过程。 - **原生透明度操作** — `color_to_alpha`（软键控背景退出）和 `trim_to_content`（裁剪到 alpha 边界框）使打印/贴纸工作流程只需一次调用。 - **可恢复的错误** — 故障被转换为可行的提示（“字体丢失 — 调用 `list_fonts`”，“图像 ID 过时 — 调用 `list_images`”，“服务器宕机 — 运行 `start-gimp-server.sh`”）。对于本地模型（Hermes、Qwen 等）来说，这一点尤为重要，否则它们将在 GIMP 不透明的“没有返回值的返回”上卡住。 - **更少的往返次数** — `gimp_batch` 在一次调用中运行许多语句，并带有每步错误捕获；包装器返回您原本需要重新查询的 ID/边界框。 ## 不只是编辑 — 从头开始绘制 <p align="center"> <img src="assets/showcase.png" alt="a landscape drawn from scratch by an agent" width="620"> <br> _{<i>没有源图像 — 此处的每个形状（日出、太阳、分层山脉、星星）都是由代理从 <code>generate</code> 包的基元绘制的，每次移动都使用 <code>look</code> 进行检查</i>} </p> `generate` 包（`draw_ellipse`/`draw_polygon`/`draw_star`/`draw_line`/`sunburst` + 程序 `render_plasma`/`render_noise`）将工具从编辑器变成画布：代理将原始矢量/程序艺术组合成原创作品，并针对视觉环路进行迭代。 ## 超越单一图像 — 自动化、矢量、运动 GIMP 的真正强大之处在于它不限于编辑单个文件；它具有规模和范围。三个包可以解锁这一点： - **`batch`** — 处理整个 **文件夹**：`batch_resize`、`batch_convert`、`batch_watermark`、`batch_recipe`（将任何保存的配方应用于每个图像）、`contact_sheet`。生产流水线的解锁：“给这 200 张照片添加水印”，“使整个拍摄的照片具有复古风格。” - **`paths`** — `draw_curve`：通过锚点（波浪、丝带、有机轮廓）绘制真正的平滑贝塞尔曲线 — 适当的矢量插图，而不仅仅是矩形和椭圆。 - **`animate`** — `frames_to_gif`（图层 → 动画 GIF）、`gif_from_folder`（帧序列 → GIF）、`spin_gif`（旋转图层成循环旋转器）。动态图形。 ## 为什么使用 Script-Fu 桥接器（不是 GIMP 插件） 在现代 Linux 上，GIMP 2.10 的 **Python-Fu 已有效消失** — `gimp-python` 由于依赖于 Python 2（生命周期结束），因此被删除，因此 Python 插件无法安装。 但是 **Script-Fu（Scheme）始终内置**，并且 GIMP 附带了一个 Script-Fu **服务器**，该服务器侦听 TCP 并运行任何 PDB 命令。该项目桥接到该服务器。**GIMP 本身没有任何内容被安装** — 它只是与套接字通信。 ## 需求 - **GIMP 2.10**（2.10.30+ 已验证）在 `PATH` 上作为 `gimp` - **Python 3.10+** - **[`fastmcp`](https://github.com/jlowin/fastmcp)** — 唯一第三方依赖项（`pip install -r requirements.txt`） - Linux/macOS（Windows 应该通过 Script-Fu 服务器工作，但未经测试） ## 安装 ```bash git clone https://github.com/constant-itis/gimp-mcp.git cd gimp-mcp pip install -r requirements.txt ``` 使用 Claude Code 注册服务器： ```bash claude mcp add gimp -s user -- python3 "$(pwd)/server.py" ``` （对于其他客户端，请指向 `python3 /abs/path/to/server.py`，stdio 传输。） **如果需要，请精简。** 工具表面是模块化的（核心 + 可选包）。仅加载您需要的工具，并使用 `GIMP_MCP_PACKS` — 例如 `GIMP_MCP_PACKS=core,text,select` 提供约 24 个工具而不是 72 个，这对于上下文有限/本地模型来说很有用。请参阅 [PACKS.md](PACKS.md)。 ## 快速入门 **无头（快速，无窗口）：** ```bash ./start-gimp-server.sh # GIMP 在 127.0.0.1:10008 上，幂等 ``` 然后询问您的代理 — `gimp` 工具会自动加载： > “加载 ~/pic.jpg，缩放为 800px 宽，增加对比度，查看它，然后导出为 PNG。” 模型编写 Scheme 并使用 `look` 检查自己的工作。您不需要编写 GIMP 脚本。 ## 观看它工作 — 设计师工作流程 常见情况不是“从头生成图像”，而是 **您已经打开 GIMP 并有您的艺术作品**，然后您说 **“嘿，做 X”。** 因为 GIMP 是 单实例的，所以您将服务器指向已经打开的窗口： ```bash # 1. 使用 GIMP 打开图像（正常） # 2. 将服务器附加到同一个窗口： ./start-gimp-server.sh --gui # （或在 GIMP 中：Filters ▸ Script-Fu ▸ Start Server） # 3. 告诉您的代理：“处理我打开的图像 - 做 X” ``` 代理找到您的打开的图像（`list_images` / `suggest`），`show` 它，然后 **实时在您的窗口中编辑它** — 每个工具都会刷新显示，以便您观看。随时询问“查看它”，它就会打开/刷新视图。 **房屋规则 - [AGENTS.md](AGENTS.md)**。驱动工具的 **LLM** 的一套简短约定：附加到您已经打开的文件，编写能力（不要强加），**在每个阶段显示预览并提供选项**，以及 **在任何破坏性/自动步骤之前进行快照（checkpoint）** — GIMP 2.10 没有 API 级别的撤销，因此快照 **是** 撤销。`suggest` 为代理提供了一个上下文相关的下一步菜单。 ## 配方和日记 — 强大的用户层 技术被 **保存、参数化和重用**，而不仅仅是重建： - **`apply_recipe(name, image_id, params)`** 在任何图像上运行一个命名、可调的管道 — 例如 `distressed-text`（纹理刻度）、`vintage`、`sticker-outline`。捆绑的配方只是 `recipes/` 中的可编辑 JSON；您的配方位于 `~/.config/gimp-mcp/recipes/`（`$GIMP_MCP_RECIPES`）。使用 `list_recipes` / `show_recipe` 浏览。 - **`journal`** 是一个宏记录器：`journal start` → 执行编辑 → `journal show` / `journal script`（独立重放 `.py`）/ `save_recipe(from_journal=True)` 将您刚刚的操作转换为可重用的配方。纯查询和预览草图被过滤掉，因此日志类似于您会手动编写的配方。 配方是 **能力，而不是内置行为** — 您的数据可以读取、编辑、共享和扩展；没有任何工作流程是强制的。 ## 工具（16 个核心 + 73 个包 = 89） 模块化：**核心**（~16 个，始终开启）可以访问整个 PDB 并驱动视觉环路；其余工具位于可选 **包** 中（[PACKS.md](PACKS.md)）。下面列出的工具是完整的集合。 **核心三元组** 使整个 PDB 可访问 — 其余的是便利设施： - `gimp_eval(scheme)` — 原始逃脱口；运行任何 Scheme/PDB 表达式 - `pdb_query(keyword)` — 在 PDB 中搜索过程名称 - `pdb_help(procedure)` — 过程的简介 + 类型参数列表 **视觉和监视：** `look`（内联渲染 — 视觉反馈环路，透明度感知的 `bg`）、`render_preview`、`describe`（元数据）、`inspect`（区域亮度/对比度 + 放置提示）、`show`（在 GIMP 窗口中打开以实时监视）、`suggest`（上下文相关的下一步菜单） **配方和日记：** `apply_recipe`、`list_recipes`、`show_recipe`、`save_recipe`、`delete_recipe`、`journal`（记录 → 重放脚本 / 新配方） **编辑：** 图层（`new_layer`、`add_layer_from_file`、`set_layer`、`list_layers`、`merge_visible`、`delete_layer`）、文本（`add_text`、`list_fonts`、`outline_text`、`text_with_shadow`、`arc_text` — 圆形弧上的文本，用于徽章/徽标/任务补丁）、变换（`crop`、`autocrop`、`rotate`、`flip`、`resize_canvas`、`scale_image`、`scale_to_fit`）、颜色/色调（`brightness_contrast`、`hue_saturation`、`desaturate`、`invert`、`auto_levels`、`curves_adjust`）、过滤器（`gaussian_blur`、`sharpen`、`pixelize`、`drop_shadow`、`vignette`、`oilify`、`emboss`、`lens_flare`、`motion_blur`）、选择（`select`、`select_by_color` — 魔术杖/键控、`feather_selection`、`grow_shrink_selection`）、填充/形状（`fill`、`draw_rect`、`gradient_fill`、`add_border`、`overlay_blend`）、放置和透明度（`place` — 按重力锚定图层、`color_to_alpha` — 软键控背景退出、`trim_to_content` — 裁剪到 alpha 边界框） **从头开始绘制（`generate`）：** `draw_ellipse`、`draw_polygon`、`draw_star`、`draw_line`、`sunburst`、`render_plasma`、`render_noise` — 矢量 + 程序基元，代理将其组合成原创艺术，并在每次移动时使用 `look` 进行检查。 **会话和安全：** `load_image`、`list_images`、`new_image`、`export_image`、`save_xcf`、`export_layers`、`close_image`、`checkpoint`/`restore_checkpoint`（不可变快照 — GIMP 2.10 没有撤销）、`gimp_batch`（多语句运行，并带有每步错误捕获）、`gimp_status`、`gimp_docs` ## 知识库（`knowledge/`） 一个 **AI-native、自再生** 的 GIMP 参考资料 — **从安装的 GIMP 通过内省生成**，因此它永远不会偏离您可以实际调用的内容： - `pdb_full.json` — 所有 ~1264 个过程的带有类型参数（机器真相）的过程 - `pdb_index.md` — 分类的一行索引所有内容 - `cookbook/00..11` — 每个领域都有密集的指南和工作 Scheme（请先阅读 `00-overview`） - `recipes.md` — “我想要做 X” → 哪个工具 / 指南 - 在会话中使用 `gimp_docs` 工具进行搜索；使用 `./build-knowledge.sh` 在 GIMP 升级后重建 请参阅 `knowledge/README.md` 以获取完整的布局和再生故事。 ## 文件 | 文件 | 角色 | |------|------| | `server.py` | 入口点 — 加载核心 + 启用的包，通过 stdio 提供服务 | | `_core.py` | 精简的基础设施：eval/introspection、视觉环路、IO、安全、共享基础设施 | | `packs/` | 可选工具包（图层、文本、效果、配方、监视、...）— 参见 PACKS.md | | `recipes/` | 捆绑的配方管道（可编辑的 JSON） | | `AGENTS.md` · `PACKS.md` | 驱动它的房屋规则 · 包系统 | | `gimp_bridge.py` | Script-Fu 线缆协议的零依赖客户端 | | `start-gimp-server.sh` | 使用 Script-Fu 服务器启动 GIMP（无头，或 `--gui` 监视） | | `build_pdb_dump.py` | 内省实时 PDB → `knowledge/pdb_full.json` | | `build_index.py` | 构建 `knowledge/pdb_index.md` + 每个领域的 `_slices/` | | `build-knowledge.sh` | 一次性再生机器可读知识 | | `knowledge/` | AI-native GIMP 参考（参见 `knowledge/README.md`) | ## 教学小型模型（`teach/`） Opus→Fable 移动：强大的模型制造 **验证** 的示例库，用于 **验证** 小型/本地模型（Hermes、Qwen、fine-tune）驱动 gimp-mcp。 [`teach/factory.py`](teach/) 执行 JSON 任务规范，对实时 GIMP 进行记录，渲染 + 检查每个记录，并发出 `demos.jsonl`（fine-tune ready）、`fewshot.md`（prompt-ready 示例）和 `contact-sheet.png`。捆绑的课程（36 个验证设计任务）由种子传递 + 子代理编写；工厂会丢弃任何实际运行的内容。 请参阅 [teach/README.md](teach/README.md)。 ## 线缆协议（GIMP 2.10.30 上确认） - 请求： `'G'` + uint16_be(len) + scheme - 响应： `'G'` + err_byte(0 ok / 1 err) + uint16_be(len) + body - `plug-in-script-fu-server` 参数： `run-mode, ip(STRING), port(INT), logfile(STRING)` ### 值得注意的注意事项 - **不要使用 `-f`/`--no-fonts` 启动 GIMP** — `gimp-text-fontname` 然后静默返回 `-1` 并且不渲染任何内容。 `start-gimp-server.sh` 故意省略它。 - `script-fu-*` 过程 **没有** 运行模式参数；`plug-in-*` 过程 **有` （`RUN-NONINTERACTIVE`）。 - Script-Fu 解释器是一个长久的进程，因此上下文（前景色、刷子等）和 `define` 在调用之间持续存在 — 使用 `gimp-context-push/pop`。 - `gimp-drawable-histogram` 在 2.10 上返回 **0..255** 刻度上的 mean/std（白色 = 255.0），而不是 0..1。 ## 路径到 GIMP 3.x 如果您稍后安装 GIMP 3，Python 3 GI 插件会回来 **并且** Script-Fu 服务器仍然存在 — 此桥接器继续工作；您只需获得更丰富的 **进程内插件** 的选项。## 许可证 [AGPL-3.0](LICENSE).