godot-visual-mcp 1.5.0__tar.gz

godot_visual_mcp-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kta41
+
+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.

godot_visual_mcp-1.5.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: godot-visual-mcp
+Version: 1.5.0
+Summary: A secure, offline-first MCP server for Godot asset prototyping.
+Author: Kta41
+License: MIT License
+        
+        Copyright (c) 2026 kta41
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/kta41/godot-visual-mcp
+Project-URL: Repository, https://github.com/kta41/godot-visual-mcp
+Project-URL: Issues, https://github.com/kta41/godot-visual-mcp/issues
+Keywords: godot,mcp,pixel-art,asset-pipeline
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp<4.0,>=3.2.0
+Requires-Dist: Pillow<13.0,>=12.3.0
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.8; extra == "dev"
+Requires-Dist: mypy<2.0,>=1.13; extra == "dev"
+Provides-Extra: ai
+Requires-Dist: rembg<3.0,>=2.0; extra == "ai"
+Dynamic: license-file
+
+<div align="center">
+  
+# godot-visual-mcp
+
+> Secure, offline-first asset tools for Godot exposed through a Model Context Protocol (MCP) server.
+
+![Python](https://img.shields.io/badge/python-3.11+-blue.svg) ![Godot](https://img.shields.io/badge/Godot-4.x-478CBF?logo=godotengine&logoColor=white) ![Protocol](https://img.shields.io/badge/Protocol-MCP-8A2BE2) ![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+Empower your LLM agents (Cline, Roo Code, Copilot) to inspect, generate, and transform visual assets directly within your Godot Engine project. Engineered with strict filesystem sandboxing, this server securely translates agent reasoning into your game's `res://` pipeline.
+</div>
+
+## 🚀 Quickstart
+
+Requires Python 3.11+. The core profile runs entirely offline and has no heavy AI or GPU dependencies.
+
+The project uses `uv.lock` for reproducible environments. Configurable safety
+limits include `MCP_MAX_INPUT_BYTES`, `MCP_MAX_PIXELS`, `MCP_MAX_FRAMES`,
+`MCP_MAX_BATCH`, `MCP_MAX_OPERATION_SECONDS`, and `MCP_MAX_PROJECT_BYTES`.
+
+```bash
+# Install core tools and development dependencies
+uv sync
+
+# Run the server (requires Godot project path)
+GODOT_PROJECT_ROOT=/path/to/my-godot-project uv run python -m server.main
+```
+
+### Client Configuration (stdio)
+Configure your MCP client to launch the server via `stdio`. Every asset path provided by the agent is automatically interpreted as relative to the `res://` directory and resolved against your configured `GODOT_PROJECT_ROOT`.
+
+```json
+{
+  "mcpServers": {
+    "godot-visual-mcp": {
+      "command": "uv",
+      "args": ["run", "--no-dev", "python", "-m", "server.main"],
+      "env": {
+        "GODOT_PROJECT_ROOT": "/path/to/my-godot-project"
+      }
+    }
+  }
+}
+```
+
+## 🧰 Available Tools
+
+All tool responses use a standard envelope format (`status` / `data` / `warnings` / `errors`) ensuring LLM agents never receive raw, unhandled stack traces. 
+
+**Core Tools (v0.2):**
+*   **Inspection:** `inspect_asset`, `list_assets`, `validate_asset`
+*   **Prototyping:** `create_placeholder`, `generate_spritesheet` (assembled offline from equal-sized frames)
+*   **Palette Engine:** `apply_palette`, `list_palettes` (ships with Game Boy, PICO-8, and custom JSON palettes. Supports RGB/LAB distance matching while preserving alpha channels).
+
+**Generative AI Tools (v0.3):**
+*   **Generation & Cleaning:** `generate_asset`, `remove_background`
+
+## 🧠 ComfyUI Integration (Optional)
+
+The core installation intentionally omits heavy AI dependencies. To enable generative workflows and background removal, install the `[ai]` profile:
+
+```bash
+uv sync --extra ai
+```
+
+Configure your local ComfyUI instance via environment variables or pass the endpoint directly to the `generate_asset` tool:
+`COMFYUI_ENDPOINT=http://127.0.0.1:8188`
+
+**How generation works:**
+1. The tool submits a local JSON workflow (located in `workflows/`).
+2. Prompts, dimensions, seeds, and batch sizes are injected dynamically (credentials are never stored).
+3. The MCP polls without fixed completion assumptions.
+4. The output is retrieved, background is removed (if requested), transparent borders are cropped, and the final asset is written safely to `res://`.
+5. *Note: CPU-only machines can use ComfyUI's CPU backend; this project does not strictly require CUDA.*
+
+## 🛡️ Security Model
+
+Security and directory integrity are core design principles:
+*   **Strict Sandboxing:** All operations are strictly bound to the configured `GODOT_PROJECT_ROOT`.
+*   **Path Validation:** Absolute paths, parent directory traversal (`../`), and symlink escapes are aggressively rejected.
+*   **Non-Destructive by Default:** Existing files are never overwritten unless a tool explicitly receives the `overwrite=true` parameter from the agent.
+
+## 🐳 Docker Deployment
+
+The project includes an optional `Dockerfile` and `compose.yaml` to provide an isolated core container and an opt-in ComfyUI profile. The default core container has no GPU or AI runtime requirements, keeping the footprint minimal.
+
+## 📦 Releases
+
+Releases are created by pushing a tag that matches the package version, for
+example:
+
+```bash
+git tag v1.5.0
+git push origin v1.5.0
+```
+
+The release workflow builds the wheel and source distribution with `uv`,
+validates installation in Python 3.11, generates SHA-256 checksums and an SPDX
+SBOM, publishes the package to PyPI through trusted publishing, and publishes
+the container to GHCR. Configure a PyPI trusted publisher for the
+`pypi` environment before using the workflow.
+
+## 🛠️ Development & Testing
+
+Run the test suite and code quality checks using standard Python tooling:
+
+```bash
+# Run unit tests
+uv run pytest
+
+# Run linter
+uv run ruff check .
+```
+
+---
+
+**Documentation:** [Security Model](SECURITY.md) | [Tool Reference](TOOL_REFERENCE.md) | [Changelog](CHANGELOG.md)

godot_visual_mcp-1.5.0/README.md

@@ -0,0 +1,116 @@
+<div align="center">
+  
+# godot-visual-mcp
+
+> Secure, offline-first asset tools for Godot exposed through a Model Context Protocol (MCP) server.
+
+![Python](https://img.shields.io/badge/python-3.11+-blue.svg) ![Godot](https://img.shields.io/badge/Godot-4.x-478CBF?logo=godotengine&logoColor=white) ![Protocol](https://img.shields.io/badge/Protocol-MCP-8A2BE2) ![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+Empower your LLM agents (Cline, Roo Code, Copilot) to inspect, generate, and transform visual assets directly within your Godot Engine project. Engineered with strict filesystem sandboxing, this server securely translates agent reasoning into your game's `res://` pipeline.
+</div>
+
+## 🚀 Quickstart
+
+Requires Python 3.11+. The core profile runs entirely offline and has no heavy AI or GPU dependencies.
+
+The project uses `uv.lock` for reproducible environments. Configurable safety
+limits include `MCP_MAX_INPUT_BYTES`, `MCP_MAX_PIXELS`, `MCP_MAX_FRAMES`,
+`MCP_MAX_BATCH`, `MCP_MAX_OPERATION_SECONDS`, and `MCP_MAX_PROJECT_BYTES`.
+
+```bash
+# Install core tools and development dependencies
+uv sync
+
+# Run the server (requires Godot project path)
+GODOT_PROJECT_ROOT=/path/to/my-godot-project uv run python -m server.main
+```
+
+### Client Configuration (stdio)
+Configure your MCP client to launch the server via `stdio`. Every asset path provided by the agent is automatically interpreted as relative to the `res://` directory and resolved against your configured `GODOT_PROJECT_ROOT`.
+
+```json
+{
+  "mcpServers": {
+    "godot-visual-mcp": {
+      "command": "uv",
+      "args": ["run", "--no-dev", "python", "-m", "server.main"],
+      "env": {
+        "GODOT_PROJECT_ROOT": "/path/to/my-godot-project"
+      }
+    }
+  }
+}
+```
+
+## 🧰 Available Tools
+
+All tool responses use a standard envelope format (`status` / `data` / `warnings` / `errors`) ensuring LLM agents never receive raw, unhandled stack traces. 
+
+**Core Tools (v0.2):**
+*   **Inspection:** `inspect_asset`, `list_assets`, `validate_asset`
+*   **Prototyping:** `create_placeholder`, `generate_spritesheet` (assembled offline from equal-sized frames)
+*   **Palette Engine:** `apply_palette`, `list_palettes` (ships with Game Boy, PICO-8, and custom JSON palettes. Supports RGB/LAB distance matching while preserving alpha channels).
+
+**Generative AI Tools (v0.3):**
+*   **Generation & Cleaning:** `generate_asset`, `remove_background`
+
+## 🧠 ComfyUI Integration (Optional)
+
+The core installation intentionally omits heavy AI dependencies. To enable generative workflows and background removal, install the `[ai]` profile:
+
+```bash
+uv sync --extra ai
+```
+
+Configure your local ComfyUI instance via environment variables or pass the endpoint directly to the `generate_asset` tool:
+`COMFYUI_ENDPOINT=http://127.0.0.1:8188`
+
+**How generation works:**
+1. The tool submits a local JSON workflow (located in `workflows/`).
+2. Prompts, dimensions, seeds, and batch sizes are injected dynamically (credentials are never stored).
+3. The MCP polls without fixed completion assumptions.
+4. The output is retrieved, background is removed (if requested), transparent borders are cropped, and the final asset is written safely to `res://`.
+5. *Note: CPU-only machines can use ComfyUI's CPU backend; this project does not strictly require CUDA.*
+
+## 🛡️ Security Model
+
+Security and directory integrity are core design principles:
+*   **Strict Sandboxing:** All operations are strictly bound to the configured `GODOT_PROJECT_ROOT`.
+*   **Path Validation:** Absolute paths, parent directory traversal (`../`), and symlink escapes are aggressively rejected.
+*   **Non-Destructive by Default:** Existing files are never overwritten unless a tool explicitly receives the `overwrite=true` parameter from the agent.
+
+## 🐳 Docker Deployment
+
+The project includes an optional `Dockerfile` and `compose.yaml` to provide an isolated core container and an opt-in ComfyUI profile. The default core container has no GPU or AI runtime requirements, keeping the footprint minimal.
+
+## 📦 Releases
+
+Releases are created by pushing a tag that matches the package version, for
+example:
+
+```bash
+git tag v1.5.0
+git push origin v1.5.0
+```
+
+The release workflow builds the wheel and source distribution with `uv`,
+validates installation in Python 3.11, generates SHA-256 checksums and an SPDX
+SBOM, publishes the package to PyPI through trusted publishing, and publishes
+the container to GHCR. Configure a PyPI trusted publisher for the
+`pypi` environment before using the workflow.
+
+## 🛠️ Development & Testing
+
+Run the test suite and code quality checks using standard Python tooling:
+
+```bash
+# Run unit tests
+uv run pytest
+
+# Run linter
+uv run ruff check .
+```
+
+---
+
+**Documentation:** [Security Model](SECURITY.md) | [Tool Reference](TOOL_REFERENCE.md) | [Changelog](CHANGELOG.md)

godot_visual_mcp-1.5.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "godot-visual-mcp"
+version = "1.5.0"
+description = "A secure, offline-first MCP server for Godot asset prototyping."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Kta41" }]
+keywords = ["godot", "mcp", "pixel-art", "asset-pipeline"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "fastmcp>=3.2.0,<4.0",
+  "Pillow>=12.3.0,<13.0",
+  "httpx>=0.27,<1.0",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+  "pytest-asyncio>=0.23,<1.0",
+  "ruff>=0.8,<1.0",
+  "mypy>=1.13,<2.0",
+]
+ai = [
+  "rembg>=2.0,<3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kta41/godot-visual-mcp"
+Repository = "https://github.com/kta41/godot-visual-mcp"
+Issues = "https://github.com/kta41/godot-visual-mcp/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0,<9.0",
+  "pytest-asyncio>=0.23,<1.0",
+  "ruff>=0.8,<1.0",
+  "mypy>=1.13,<2.0",
+]
+
+[project.scripts]
+godot-visual-mcp = "server.main:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.setuptools.package-data]
+godot_visual_mcp = ["resources/palettes/*.json", "resources/workflows/*.json"]

godot_visual_mcp-1.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

godot_visual_mcp-1.5.0/src/godot_visual_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Secure Godot asset tools exposed through MCP."""
+
+__version__ = "1.5.0"

godot_visual_mcp-1.5.0/src/godot_visual_mcp/aseprite.py

@@ -0,0 +1,43 @@
+"""Aseprite JSON metadata and animation import helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .filesystem import GodotProject
+
+
+def inspect_aseprite_json(project: GodotProject, source: str) -> dict[str, Any]:
+    """Inspect a `.json` export produced by Aseprite."""
+    if Path(source).suffix.lower() != ".json":
+        raise ValueError("Aseprite metadata must be a .json file")
+    try:
+        payload = json.loads(project.safe_read(source).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"Invalid Aseprite JSON: {source}") from exc
+    frames = payload.get("frames")
+    if isinstance(frames, dict):
+        frame_names = list(frames)
+    elif isinstance(frames, list):
+        frame_names = [str(item.get("filename", index)) for index, item in enumerate(frames)]
+    else:
+        raise TypeError("Aseprite JSON has no frames")
+    tags = payload.get("meta", {}).get("frameTags", [])
+    if not isinstance(tags, list):
+        raise TypeError("Aseprite frameTags must be a list")
+    animations = [
+        {"name": tag.get("name"), "from": tag.get("from"), "to": tag.get("to"), "direction": tag.get("direction", "forward")}
+        for tag in tags
+        if isinstance(tag, dict) and isinstance(tag.get("name"), str)
+    ]
+    return {"path": project.validate_asset_path(source), "frames": len(frame_names), "frame_names": frame_names, "animations": animations}
+
+
+def create_animation_manifest(project: GodotProject, source: str, output: str, *, overwrite: bool = False) -> dict[str, Any]:
+    """Convert Aseprite frame tags into a stable JSON manifest for later import."""
+    metadata = inspect_aseprite_json(project, source)
+    content = json.dumps({"source": metadata["path"], "animations": metadata["animations"]}, indent=2) + "\n"
+    written = project.safe_write(output, content.encode("utf-8"), overwrite=overwrite)
+    return {"path": written, "animations": metadata["animations"], "frames": metadata["frames"]}

godot_visual_mcp-1.5.0/src/godot_visual_mcp/assets.py

@@ -0,0 +1,127 @@
+"""Image inspection, validation, and deterministic placeholder generation."""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+from PIL import Image, ImageDraw, ImageFont, UnidentifiedImageError
+
+from .filesystem import GodotProject
+from .limits import ensure_image_dimensions, ensure_input_size
+
+SUPPORTED_FORMATS = {"PNG", "JPEG", "WEBP", "BMP", "GIF", "TIFF"}
+
+
+def _frame_count(width: int, height: int) -> int:
+    """Estimate uniform horizontal/vertical sprite frames from image geometry."""
+    if width >= height * 2 and width % height == 0:
+        return width // height
+    if height >= width * 2 and height % width == 0:
+        return height // width
+    return 1
+
+
+def inspect_asset(project: GodotProject, path: str) -> dict[str, Any]:
+    """Return compact metadata suitable for an agent."""
+    data = project.safe_read(path)
+    ensure_input_size(len(data))
+    try:
+        with Image.open(io.BytesIO(data)) as image:
+            ensure_image_dimensions(image.width, image.height)
+            has_alpha = "A" in image.getbands() or "transparency" in image.info
+            return {
+                "path": project.validate_asset_path(path),
+                "format": image.format,
+                "width": image.width,
+                "height": image.height,
+                "has_alpha": has_alpha,
+                "frames": getattr(image, "n_frames", 1),
+                "sprite_frames": _frame_count(image.width, image.height),
+                "color_mode": image.mode,
+            }
+    except (UnidentifiedImageError, OSError) as exc:
+        raise ValueError(f"Unsupported or corrupt image: {path}") from exc
+
+
+def list_assets(project: GodotProject, extension: str | None = None) -> list[str]:
+    """List project assets, optionally filtered by extension."""
+    assets = project.iter_assets()
+    if extension:
+        suffix = extension.lower()
+        if not suffix.startswith("."):
+            suffix = "." + suffix
+        assets = [path for path in assets if path.lower().endswith(suffix)]
+    return assets
+
+
+def validate_asset(project: GodotProject, path: str) -> dict[str, Any]:
+    """Check that an image is readable and provide actionable diagnostics."""
+    try:
+        metadata = inspect_asset(project, path)
+    except (FileNotFoundError, ValueError) as exc:
+        return {"valid": False, "path": project.validate_asset_path(path), "errors": [str(exc)]}
+    errors: list[str] = []
+    if metadata["format"] not in SUPPORTED_FORMATS:
+        errors.append(f"Format {metadata['format']} is not supported")
+    if metadata["width"] <= 0 or metadata["height"] <= 0:
+        errors.append("Image dimensions must be positive")
+    return {
+        "valid": not errors,
+        "path": metadata["path"],
+        "errors": errors,
+        "metadata": metadata,
+    }
+
+
+def verify_asset(project: GodotProject, path: str) -> dict[str, Any]:
+    """Verify that an output is present and import-ready without reading `.import` files."""
+    validation = validate_asset(project, path)
+    if not validation["valid"]:
+        return {
+            "ready": False,
+            "path": validation["path"],
+            "import_verification": "failed_validation",
+            "validation": validation,
+        }
+    return {
+        "ready": True,
+        "path": validation["path"],
+        "import_verification": "readable_and_supported",
+        "validation": validation,
+    }
+
+
+def create_placeholder(
+    project: GodotProject,
+    output: str,
+    width: int,
+    height: int,
+    frames: int = 1,
+    label: str = "PLACEHOLDER",
+    *,
+    overwrite: bool = False,
+) -> dict[str, Any]:
+    """Create a labeled, deterministic RGBA placeholder spritesheet."""
+    if width <= 0 or height <= 0 or frames <= 0:
+        raise ValueError("width, height, and frames must be positive integers")
+    if frames > 128:
+        raise ValueError("frames must be 128 or fewer")
+    image = Image.new("RGBA", (width * frames, height), (38, 42, 54, 255))
+    draw = ImageDraw.Draw(image)
+    font = ImageFont.load_default()
+    for index in range(frames):
+        left = index * width
+        draw.rectangle((left, 0, left + width - 1, height - 1), outline=(235, 220, 120, 255), width=2)
+        text = label[:32]
+        bounds = draw.textbbox((0, 0), text, font=font)
+        draw.text(
+            (left + (width - (bounds[2] - bounds[0])) / 2, (height - (bounds[3] - bounds[1])) / 2),
+            text,
+            fill=(235, 220, 120, 255),
+            font=font,
+        )
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG", optimize=False)
+    written = project.safe_write(output, buffer.getvalue(), overwrite=overwrite)
+    return {"path": written, "width": width, "height": height, "frames": frames, "has_alpha": True}