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)
