Metadata-Version: 2.4
Name: spritehatch-mcp
Version: 0.1.0
Summary: MCP server for SpriteHatch: AI agents generate 2D game sprites, animations, effects, items, UI, scenes and tilesets and export them for Godot, Unity, GameMaker and RPG Maker.
Author: SpriteHatch
License-Expression: MIT
Project-URL: Homepage, https://spritehatch.com
Project-URL: Documentation, https://spritehatch.com/docs/mcp
Keywords: mcp,model-context-protocol,ai-agents,game-development,sprites,pixel-art,animation,gamedev
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pillow>=10
Dynamic: license-file

# SpriteHatch MCP

Lets AI agents (Claude Code, Cursor, Codex, Windsurf…) make 2D game assets with [SpriteHatch](https://spritehatch.com)
and bring them into the game: characters, monsters, animations, abilities with separate effect layers, effects, items,
UI, parallax scenes and tilesets, exported for Godot, Unity, GameMaker, RPG Maker or plain sprite sheets.

The server teaches the agent which tool fits each need and guards the user's credits:

- `spritehatch_guide` (free) turns a game need ("the dragon breathes fire at the player") into the right recipe, with
  costs and pitfalls. The same decision rules are sent to the agent when it connects.
- Quality, art style and image engine are the user's choice: when the request does not say, the tool returns the
  options (with costs) for the agent to ask, or shows a form in clients that support it. Image engines are known only by
  their product names.
- Effects that stay on the body (a charge-up) are drawn into the character animation; what flies to a target becomes
  separate effects the game moves. The animation plan is shown exactly as it will be generated (prompt, ending, beats)
  and can be corrected before paying.
- Session budget and approval: spending above the approval limit since the last approval asks the user (MCP elicitation,
  or a one-time `confirm_token` the agent only sends after asking), so splitting a request does not get around it. A
  prompt the client declines on its own is not taken as the user's answer. Failed jobs are refunded and give the budget
  back; the same request failing twice stops.
- Effects are checked for frames cut by the canvas edge and empty frames; a bad ending can be redone from a frame.
- Animations are judged for free after generation; the agent may improve one at most once on its own, then shows the
  user.
- Results come back as preview images, and exports come with a manifest (frame size, pivot, clips, ability timeline)
  the agent can wire into code.

Requires a SpriteHatch API key (Pro or Studio plan): app → avatar → **My account and statement** → **API keys**.

## Local (stdio): files go straight into your game project

```sh
# Claude Code
claude mcp add spritehatch -e SPRITEHATCH_API_KEY=sg_live_... -- uvx spritehatch-mcp
```

Other clients (Cursor, Windsurf, Codex…), in their MCP config:

```json
{
  "mcpServers": {
    "spritehatch": {
      "command": "uvx",
      "args": ["spritehatch-mcp"],
      "env": { "SPRITEHATCH_API_KEY": "sg_live_..." }
    }
  }
}
```

| Variable | Default | |
|---|---|---|
| `SPRITEHATCH_API_KEY` | — | Required. |
| `SPRITEHATCH_BUDGET` | `300` | Credits this session may spend. |
| `SPRITEHATCH_CONFIRM_ABOVE` | `60` | Single requests above this need the user's approval. `0` = always ask. |
| `SPRITEHATCH_EXPORT_DIR` | `spritehatch-assets` | Where `export_asset` writes when no folder is given. |
| `SPRITEHATCH_URL` | `https://spritehatch.com` | API address. |

## Hosted (streamable HTTP): nothing to install

```sh
claude mcp add --transport http spritehatch https://spritehatch.com/mcp \
  --header "Authorization: Bearer sg_live_..." --header "X-SpriteHatch-Budget: 300"
```

Optional headers: `X-SpriteHatch-Budget`, `X-SpriteHatch-Confirm-Above`. The hosted server cannot read or write the
agent's disk: reference images go as https URLs or base64, and exports come back as 30-minute download links.

Run it yourself: `spritehatch-mcp --http --host 0.0.0.0 --port 7870` with `SPRITEHATCH_URL` pointing at the API and
`SPRITEHATCH_MCP_PUBLIC_URL` set to this server's public address (for the download links). Health check: `GET /health`.

## Tools

| Need | Tool |
|---|---|
| Not sure what to make | `spritehatch_guide` (free) |
| Account, credits, session budget | `get_account` |
| Projects and style kit (pixel art, height, 2/4/8 directions, palette) | `list_projects`, `setup_project` |
| What already exists | `list_assets`, `get_asset`, `get_preview` |
| New character/monster, from text or an image | `create_character`, `choose_candidate` |
| Outfit, color, armor, elite version, rarity | `add_skin` |
| Top-down / isometric views | `add_directions` |
| Body animation (effects on the body included) | `plan_animation` (free) → `generate_animation`, `review_animation` (free), `improve_animation` |
| Attack or power that emits something | charge animation + `create_vfx` (best control), or `create_ability` (automatic) |
| Standalone effect, projectile, impact | `create_vfx`, `improve_vfx` |
| Pick which kept version is used | `use_version` |
| Item, weapon, prop, icon | `create_item` |
| Buttons, bars, panels | `create_ui`, `add_ui_states` |
| Side-scroller background | `create_scene`, `add_parallax_layers` |
| Tilesets / maps | `create_tileset` |
| Fix a detail | `edit_asset`, `apply_edit` |
| Wait for generation | `wait_for_jobs` |
| Take it to the game | `export_asset` |

Resource `spritehatch://guide` has the full guide; prompts `make_game_character` and `add_attack_with_effect` start the
two most common flows.

## Development

Tests live in the main repository: `.venv/bin/python scripts/check_mcp.py` runs the real API, queue, billing and
exports with a simulated GPU, through both transports.
