gimp-mcp 0.2.0__tar.gz

gimp_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manoah BERNIER and gimp-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gimp_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: gimp-mcp
+Version: 0.2.0
+Summary: A reliable Model Context Protocol server for inspecting and editing GIMP 3 projects.
+Keywords: gimp,mcp,model-context-protocol,image-editing,llm
+Author: Manoah BERNIER
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Editors :: Raster-Based
+Requires-Dist: mcp>=2.3,<3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/mhbxyz/gimp-mcp
+Project-URL: Documentation, https://github.com/mhbxyz/gimp-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/mhbxyz/gimp-mcp/issues
+Project-URL: Changelog, https://github.com/mhbxyz/gimp-mcp/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# gimp-mcp
+
+<!-- mcp-name: io.github.mhbxyz/gimp-mcp -->
+
+Let an AI assistant inspect and edit images in **your running GIMP** through the
+[Model Context Protocol](https://modelcontextprotocol.io): layers, text, selections, filters, files, previews.
+Linux, GIMP 3.2+. MIT licensed.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) and an MCP client
+(Claude Code, Claude Desktop, VS Code, Cursor…). On Ubuntu 26.04:
+
+<!-- doctest: quickstart -->
+```sh
+sudo apt install -y gimp python3-gi gir1.2-gimp-3.0   # GIMP 3.2+ (other distributions and Flatpak: see below)
+uvx gimp-mcp setup                                    # installs the GIMP plug-in, adds the server to your MCP clients
+uvx gimp-mcp doctor                                   # after (re)starting GIMP: every check should be [ok]
+```
+
+Then ask your assistant: *"Use GIMP to create a 1280×720 image with the title 'Hello' and export it to
+~/hello.png"*.
+
+* Other distributions (Arch, Debian 14, Fedora 44, openSUSE Tumbleweed, Alpine 3.24) and their packages:
+  [compatibility](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/compatibility.md#linux-distributions).
+  GIMP from **Flathub** works too: `flatpak install flathub org.gimp.GIMP`, then the two `uvx` commands.
+* Step-by-step per client: [Claude Code](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/claude-code.md),
+  [Claude Desktop](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/claude-desktop.md),
+  [VS Code and Cursor](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/vscode-cursor.md),
+  [any other MCP client](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/generic.md).
+* Something wrong? `uvx gimp-mcp doctor` says what and how to fix it
+  ([troubleshooting](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/troubleshooting.md)).
+
+Also listed in the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.mhbxyz/gimp-mcp)
+as `io.github.mhbxyz/gimp-mcp` (from the first PyPI release on).
+
+## What it can do
+
+52 tools: inspect images and layer trees, previews, create/open/save XCF/export PNG and JPEG, layers and
+groups, resize/crop/transform, selections and masks, painting, brightness/contrast, hue/saturation, blur
+(destructive or editable filters), editable text, undo groups and checkpoints, and allowlisted access to
+~420 GIMP procedures. See the [tool reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/tools.md)
+and the [coverage matrix](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/coverage.md).
+
+## Demo
+
+```sh
+uv run demo/thumbnail.py                 # from a checkout: isolated headless GIMP, outputs in demo/out/
+```
+
+Builds a 1280×720 thumbnail through MCP only (blurred backdrop with editable corrections, masked photo,
+banner, editable title, a badge undone and redone with checkpoints), saves and reopens the XCF, exports PNG
+and JPEG, and writes a report of every call and check.
+Walk-through: [docs/guide-thumbnail.md](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/guide-thumbnail.md).
+
+## Documentation
+
+- [Installation reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/install.md) (manual install, upgrade, uninstall) ·
+  [MCP clients](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients.md) ·
+  [troubleshooting](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/troubleshooting.md) ·
+  [compatibility](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/compatibility.md)
+- [Tool reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/tools.md) ·
+  [coverage matrix](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/coverage.md)
+- [Architecture](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/architecture.md) ·
+  [bridge protocol](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/bridge-protocol.md) ·
+  [security](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/security.md) ·
+  [decisions](https://github.com/mhbxyz/gimp-mcp/tree/main/docs/adr)
+- [Testing](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/testing.md) ·
+  [releasing](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/releasing.md) ·
+  [GIMP behaviour notes](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/gimp-notes.md) ·
+  [changelog](https://github.com/mhbxyz/gimp-mcp/blob/main/CHANGELOG.md)

gimp_mcp-0.2.0/README.md

@@ -0,0 +1,71 @@
+# gimp-mcp
+
+<!-- mcp-name: io.github.mhbxyz/gimp-mcp -->
+
+Let an AI assistant inspect and edit images in **your running GIMP** through the
+[Model Context Protocol](https://modelcontextprotocol.io): layers, text, selections, filters, files, previews.
+Linux, GIMP 3.2+. MIT licensed.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) and an MCP client
+(Claude Code, Claude Desktop, VS Code, Cursor…). On Ubuntu 26.04:
+
+<!-- doctest: quickstart -->
+```sh
+sudo apt install -y gimp python3-gi gir1.2-gimp-3.0   # GIMP 3.2+ (other distributions and Flatpak: see below)
+uvx gimp-mcp setup                                    # installs the GIMP plug-in, adds the server to your MCP clients
+uvx gimp-mcp doctor                                   # after (re)starting GIMP: every check should be [ok]
+```
+
+Then ask your assistant: *"Use GIMP to create a 1280×720 image with the title 'Hello' and export it to
+~/hello.png"*.
+
+* Other distributions (Arch, Debian 14, Fedora 44, openSUSE Tumbleweed, Alpine 3.24) and their packages:
+  [compatibility](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/compatibility.md#linux-distributions).
+  GIMP from **Flathub** works too: `flatpak install flathub org.gimp.GIMP`, then the two `uvx` commands.
+* Step-by-step per client: [Claude Code](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/claude-code.md),
+  [Claude Desktop](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/claude-desktop.md),
+  [VS Code and Cursor](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/vscode-cursor.md),
+  [any other MCP client](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients/generic.md).
+* Something wrong? `uvx gimp-mcp doctor` says what and how to fix it
+  ([troubleshooting](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/troubleshooting.md)).
+
+Also listed in the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.mhbxyz/gimp-mcp)
+as `io.github.mhbxyz/gimp-mcp` (from the first PyPI release on).
+
+## What it can do
+
+52 tools: inspect images and layer trees, previews, create/open/save XCF/export PNG and JPEG, layers and
+groups, resize/crop/transform, selections and masks, painting, brightness/contrast, hue/saturation, blur
+(destructive or editable filters), editable text, undo groups and checkpoints, and allowlisted access to
+~420 GIMP procedures. See the [tool reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/tools.md)
+and the [coverage matrix](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/coverage.md).
+
+## Demo
+
+```sh
+uv run demo/thumbnail.py                 # from a checkout: isolated headless GIMP, outputs in demo/out/
+```
+
+Builds a 1280×720 thumbnail through MCP only (blurred backdrop with editable corrections, masked photo,
+banner, editable title, a badge undone and redone with checkpoints), saves and reopens the XCF, exports PNG
+and JPEG, and writes a report of every call and check.
+Walk-through: [docs/guide-thumbnail.md](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/guide-thumbnail.md).
+
+## Documentation
+
+- [Installation reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/install.md) (manual install, upgrade, uninstall) ·
+  [MCP clients](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/clients.md) ·
+  [troubleshooting](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/troubleshooting.md) ·
+  [compatibility](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/compatibility.md)
+- [Tool reference](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/tools.md) ·
+  [coverage matrix](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/coverage.md)
+- [Architecture](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/architecture.md) ·
+  [bridge protocol](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/bridge-protocol.md) ·
+  [security](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/security.md) ·
+  [decisions](https://github.com/mhbxyz/gimp-mcp/tree/main/docs/adr)
+- [Testing](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/testing.md) ·
+  [releasing](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/releasing.md) ·
+  [GIMP behaviour notes](https://github.com/mhbxyz/gimp-mcp/blob/main/docs/gimp-notes.md) ·
+  [changelog](https://github.com/mhbxyz/gimp-mcp/blob/main/CHANGELOG.md)

gimp_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "gimp-mcp"
+version = "0.2.0"
+description = "A reliable Model Context Protocol server for inspecting and editing GIMP 3 projects."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "gimp",
+    "mcp",
+    "model-context-protocol",
+    "image-editing",
+    "llm",
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics :: Editors :: Raster-Based",
+]
+dependencies = ["mcp>=2.3,<3"]
+
+[[project.authors]]
+name = "Manoah BERNIER"
+
+[project.urls]
+Homepage = "https://github.com/mhbxyz/gimp-mcp"
+Documentation = "https://github.com/mhbxyz/gimp-mcp/tree/main/docs"
+Issues = "https://github.com/mhbxyz/gimp-mcp/issues"
+Changelog = "https://github.com/mhbxyz/gimp-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+gimp-mcp = "gimp_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pillow>=13.0.0",
+    "pyright>=1.1.414",
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "pyyaml>=6.0.3",
+    "ruff>=0.17.4",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["gimp: end-to-end test that drives a real GIMP 3 instance (skipped when GIMP is absent unless GIMP_MCP_REQUIRE_GIMP=1)"]
+addopts = "-ra --strict-markers"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+]
+ignore = ["SIM105"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/gimp_mcp/plugin/**" = ["UP"]
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "demo",
+]
+exclude = ["src/gimp_mcp/plugin"]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"

gimp_mcp-0.2.0/pyproject.toml.orig

@@ -0,0 +1,72 @@
+[project]
+name = "gimp-mcp"
+version = "0.2.0"
+description = "A reliable Model Context Protocol server for inspecting and editing GIMP 3 projects."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Manoah BERNIER" }]
+keywords = ["gimp", "mcp", "model-context-protocol", "image-editing", "llm"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics :: Editors :: Raster-Based",
+]
+dependencies = ["mcp>=2.3,<3"]
+
+[project.urls]
+Homepage = "https://github.com/mhbxyz/gimp-mcp"
+Documentation = "https://github.com/mhbxyz/gimp-mcp/tree/main/docs"
+Issues = "https://github.com/mhbxyz/gimp-mcp/issues"
+Changelog = "https://github.com/mhbxyz/gimp-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+gimp-mcp = "gimp_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pillow>=13.0.0",
+    "pyright>=1.1.414",
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "pyyaml>=6.0.3",
+    "ruff>=0.17.4",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = [
+    "gimp: end-to-end test that drives a real GIMP 3 instance (skipped when GIMP is absent unless GIMP_MCP_REQUIRE_GIMP=1)",
+]
+addopts = "-ra --strict-markers"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["SIM105"]
+
+[tool.pyright]
+include = ["src", "tests", "demo"]
+exclude = ["src/gimp_mcp/plugin"]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+
+[tool.ruff.lint.per-file-ignores]
+# Runs on GIMP's own Python (may be older than the server's): keep it conservative.
+"src/gimp_mcp/plugin/**" = ["UP"]

gimp_mcp-0.2.0/src/gimp_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""MCP server for inspecting and editing GIMP 3 projects."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth: the `version` field of pyproject.toml.
+    __version__ = version("gimp-mcp")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
+    __version__ = "0+unknown"

gimp_mcp-0.2.0/src/gimp_mcp/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())