🚀 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.

# 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.

{
  "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

🧰 Tool Reference

All tools return the same envelope:

{
  "status": "ok",
  "data": {},
  "warnings": [],
  "errors": []
}

Paths use Godot's res:// notation and are always checked against the selected project. Mutating tools do not overwrite existing files unless overwrite=true is provided. Generated or transformed images include verification data. Errors include a stable code, a retryability flag, a suggestion, and a correlation ID.

Project and image inspection

Example:

{
  "name": "inspect_asset",
  "arguments": {"path": "res://characters/hero.png"}
}

Offline image creation and palettes

These operations are offline and do not require ComfyUI, CUDA, or a GPU.

Godot scenes and animation

Scene tools validate references after writing and never edit .import files.

Aseprite and animation manifests

The current integration consumes Aseprite-exported JSON and PNG files; it does not execute the Aseprite binary or accept arbitrary shell commands.

Offline visual transformations

Transformation responses contain before, after, dimension changes, alpha-preservation information, and output verification.

ComfyUI generation and history

generate_asset also supports timeout, retries, validate_workflow, use_cache, overwrite, and an explicit endpoint. The core installation does not install ComfyUI or rembg.

Project discovery and MCP ergonomics

The selected project can also come from GODOT_PROJECT_ROOT. Project aliases are process-local and do not write global configuration.

Audio, fonts, SVG, 3D, and JSON

All extended-asset inspections enforce the configured input-size limit. No external URL is downloaded by these tools.

🧠 ComfyUI Integration (Optional)

The core installation intentionally omits heavy AI dependencies. To enable generative workflows and background removal, install the [ai] profile:

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

Development happens on develop. Changes reach the protected main branch through a pull request from develop, with one approving review and all Python 3.11, 3.12, and 3.13 checks passing. Merging that pull request starts the release workflow automatically. Before merging, update the package version and changelog; the workflow refuses to republish an existing release version.

Releases are created by pushing a tag that matches the package version, for example:

git tag v1.6.0
git push origin v1.6.0

The release workflow for future merges creates the version tag automatically. The manual tag commands above are only a fallback for releases that are not created through the develop → main pull request flow. It 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:

# Run unit tests
uv run pytest

# Run linter
uv run ruff check .

Documentation: Security Model | Tool Reference | Changelog