Metadata-Version: 2.5
Name: lpc-character-mcp
Version: 0.4.0
Summary: MCP server that generates LPC pixel-art characters and exports them to Godot, Unity and the web
Project-URL: Homepage, https://github.com/kyuza1/lpc-character-mcp
Project-URL: Issues, https://github.com/kyuza1/lpc-character-mcp/issues
Author: LUCAS ARAUJO
License-Expression: MIT
License-File: LICENSE
Keywords: gamedev,godot,lpc,mcp,phaser,pixel-art,sprites,spritesheet,unity
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: mcp>=2
Requires-Dist: numpy
Requires-Dist: pillow
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# LPC Character Generator — MCP

<!-- mcp-name: io.github.kyuza1/lpc-character-mcp -->

*English · [Português](https://github.com/kyuza1/lpc-character-mcp/blob/main/README.pt-BR.md)*

[![tests](https://github.com/kyuza1/lpc-character-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/kyuza1/lpc-character-mcp/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/lpc-character-mcp)](https://pypi.org/project/lpc-character-mcp/)

An MCP server that builds LPC pixel-art character spritesheets — the same parts as the
[Universal LPC Spritesheet Character Generator](https://liberatedpixelcup.github.io/Universal-LPC-Spritesheet-Character-Generator/) —
and exports them ready for **Godot**, **Unity** and the **web** (Phaser/PixiJS).

Ask in plain language ("make a tanned blacksmith with a leather apron and a hammer") and
your assistant assembles the character, shows an animated preview in the chat and saves
the files.

## Installation

You need **[uv](https://docs.astral.sh/uv/getting-started/installation/)** and **Git**.
uv fetches the right Python and the package by itself — nothing to clone, no
dependencies to install.

1. Install uv (once):
   - Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`
   - macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
2. Prepare the server (downloads the item definitions, ~10 s, only once):
   ```
   uvx lpc-character-mcp --setup
   ```
3. Register it in your assistant (below). The command is always `uvx lpc-character-mcp`.

To run the latest code straight from GitHub, replace `uvx lpc-character-mcp` with
`uvx --from git+https://github.com/kyuza1/lpc-character-mcp lpc-character-mcp` in any example.

Characters are saved to `~/lpc-characters` (on Windows, `C:\Users\<you>\lpc-characters`).
Set `LPC_OUTPUT_DIR` to change it — for example, to your Godot/Unity sprites folder.
`lpc-character-mcp --where` prints every folder in use. Messages are in English; set
`LPC_LANG=pt` for Portuguese.

### Claude Code
```
claude mcp add lpc --scope user -- uvx lpc-character-mcp
```

### Claude Desktop
**One click:** download `lpc-character-mcp.mcpb` from the
[latest release](https://github.com/kyuza1/lpc-character-mcp/releases/latest) and open it
(or drag it into **Settings → Extensions**). You can pick the output folder and language
during install.

Or add it by hand in **Settings → Developer → Edit config** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}
```

### Codex (OpenAI)
```
codex mcp add lpc -- uvx lpc-character-mcp
```
Or edit `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`):
```toml
[mcp_servers.lpc]
command = "uvx"
args = ["lpc-character-mcp"]
startup_timeout_sec = 60
```
Check with `codex mcp list`. The same file is used by the Codex VS Code extension.

### Antigravity (Google)
In the agent panel click **…** → **MCP Servers** → **Manage MCP Servers** →
**View raw config** and add to `mcp_config.json` (`~/.gemini/config/mcp_config.json`;
on Windows, `%USERPROFILE%\.gemini\config\mcp_config.json`):
```json
{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}
```
Save and click **Refresh** on the MCP Servers page. In the Antigravity CLI, use `/mcp`.

### Directories
Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.kyuza1/lpc-character-mcp)
as `io.github.kyuza1/lpc-character-mcp`, which clients and directories that read the
registry pick up automatically.

### Other MCP clients
Any client that runs **stdio** servers works with the same `uvx lpc-character-mcp` command.

### Without uv (pip)
```
pip install lpc-character-mcp
lpc-character-mcp --setup
```
Then register the `lpc-character-mcp` command (no arguments) in your assistant.

### Tips
- **Free disk space:** `lpc-character-mcp --clear-cache` deletes cached images
  (`--clear-cache 30` only those unused for 30 days).
- **Update:** `uvx lpc-character-mcp@latest --version`
- **App can't find `uvx`:** use the full path (`where uvx` on Windows, `which uvx` elsewhere).

## Example requests
- "Make a tanned blacksmith with a leather apron and a hammer, export for Godot"
- "Show me an animated preview of him hammering"
- "Generate 10 random villagers with seed 1, with Unity files"
- "Open this link and generate the character: https://liberatedpixelcup.github.io/...#sex=male&body=..."
- "Which aprons have an idle animation for the male body?"

## Tools
| Tool | What it does |
|---|---|
| `generate_character(items, body_type, animations, filename, layout, split, export, prefer_complete, output_dir)` | Builds the PNG, the credits, the animation report and (optionally) engine files |
| `preview_character(items, body_type, animation, animated)` | In-chat preview: animated GIF with the 4 directions |
| `search_items(query, category, body_type, animation, type_name, complete_only)` | Searches items with filters; complete items first |
| `get_item(item_id)` | Colors, variants, multi-color parts and the animations available per body |
| `list_categories` | Lists item categories |
| `random_character(body_type, seed, fixed_items)` | Rolls a random character |
| `generate_batch(count, body_types, seed, prefix, fixed_items, ..., output_dir)` | Generates many random NPCs at once |
| `from_site_url(url)` / `to_site_url(items, body_type)` | Reads / builds generator site links (including old links) |
| `update_definitions(clear_image_cache)` | Pulls new items and palettes from the official repository |
| `clear_cache(older_than_days, dry_run)` | Deletes cached images (or only those unused for N days) |

Example `items`:
```json
[
  {"id": "body/body", "color": "bronze"},
  {"id": "head/heads/human/heads_human_male"},
  {"id": "hair/short/hair_plain", "color": "dark_brown"},
  {"id": "torso/shirts/longsleeve/torso_clothes_longsleeve", "color": "white"},
  {"id": "torso/aprons/torso_aprons_overalls", "variant": "leather"},
  {"id": "legs/pants/legs_cuffed", "color": "white"},
  {"id": "feet/boots/feet_boots_basic", "color": "brown"},
  {"id": "tools/tool_hammer", "color": ["steel", "walnut"]}
]
```

### Colors
- `"color": "blonde"` — one color (see `colors` in `get_item`).
- `"color": ["steel", "walnut"]` — multi-part items (head and handle, armor and belt...).
  Parts are listed in `color_parts` from `get_item`; `null` keeps a part's default.
- Head, ears, nose and other skin items without a color inherit the body color.
- One item per type, like the site: asking for two hairstyles keeps the last one (and
  says so in `warnings`).

### Where to save
`output_dir` saves straight into a folder — e.g. your game's sprites folder:
"generate the blacksmith in C:/my-game/art/npcs and export for Godot". Otherwise files go
to `LPC_OUTPUT_DIR` or `~/lpc-characters`.

### Layout and parts
- `layout: "standard"` (default) — same as the site: 832px wide, every animation always on
  the same row (walk at y=512, slash at y=768...). Oversized animations go below y=3456.
- `layout: "compact"` — only the requested animations, stacked.
- `split` — also saves pieces: `"animation"` (one PNG per animation), `"frame"` (one PNG
  per frame in `<name>_frames/<animation>/<direction>_NN.png`) and/or `"item"` (one sheet
  per item, for swapping outfits in-game). Accepts a list: `["animation", "frame"]`.

### Oversized animations
Big weapons and tools (swords, spears, hammer, axe, bow...) use 128 or 192px frames. They
are added automatically when their base animation is requested (asking for `slash` with
the hammer also produces `tool_hammer`).

## Complete animations
Not every LPC item has art for all 15 animations (e.g. the apron has no `idle`, `run`,
`jump`...). In those animations the item simply disappears. To avoid surprises:

- **Every result warns you.** `generate_character` always returns `animation_check`:
  ```json
  "animation_check": {
    "complete": false,
    "incomplete_items": {
      "torso/aprons/torso_aprons_apron": {
        "missing": ["climb", "idle", "jump", "sit", "emote", "run", ...],
        "complete_alternatives": ["torso/aprons/torso_aprons_overalls", ...]
      }
    },
    "summary": "ATENÇÃO: nem todas as animações ficaram completas: Apron não tem ..."
  }
  ```
  The preview, batches and the web demo warn too.
- **`prefer_complete: true`** replaces each incomplete item with the closest item that has
  every animation, keeping the color (e.g. apron → overalls). Replacements are listed in
  `replaced`. The assistant is told to ask you first.
- **Search puts complete items first.** `search_items` lists them first, shows
  `missing_animations` for the others and accepts `complete_only: true`. `get_item` shows
  what is missing and suggests `complete_alternatives`.
- **Random characters only use complete items.**

Not counted as missing: face, nose, beard, glasses and necklaces in `climb` (the character
faces away), expressions in `hurt`, weapons/tools/shields — which by nature only appear in
their own animations (listed in `equipment_only_in`) — and animations the body itself
lacks (listed in `body_missing`).

## Exporting to engines
Pass `export` to `generate_character` (you can combine them):

| `export` | Files | How to use |
|---|---|---|
| `"godot"` | `<name>.tres` (SpriteFrames) | Generate with `output_dir` inside your project (the `res://` path is filled in automatically) or copy `<name>.png` and `<name>.tres` to `res://characters/`. Use the `.tres` as **Sprite Frames** of an `AnimatedSprite2D`. Animations: `walk_down`, `idle_left`, `tool_hammer_right`... Tested on Godot 4.6. |
| `"unity"` | `<name>.png.meta`, `<name>.controller` + `<name>_unity_anims/*.anim` | Generate with `output_dir` inside `Assets/` (or copy everything there). Sprites come pre-sliced (Multiple, Point filter, no compression) and the `.controller` has one state per animation (starts at `idle_down`): put it in the Animator of a SpriteRenderer object and call `animator.Play("walk_left")`. Tested on Unity 6. |
| `"web"` | `<name>.json` (atlas) + `<name>_demo.html` | TexturePacker-style (hash) atlas with `animations`: Phaser 3 `this.load.atlas(...)`, PixiJS `Assets.load(...)`. Tested on Phaser 3.80 and PixiJS 8.5. The demo plays the character with arrows/WASD, Shift and Space — open it from a local server (`python -m http.server`). |
| `"site"` | `<name>_site.json` | Paste it into the generator site's **Import from Clipboard (JSON)** button to keep editing there. |

## Art credits
Every generation writes `<name>_credits.txt` and `<name>_credits.csv` with authors,
licenses and links for **only the art that was used**. The sprites are LPC art
(CC-BY-SA 3.0, OGA-BY 3.0, GPL 3.0 and others) — if you ship a game, include these credits.

## Limitations
- Some types have no complete version at all (capes, backpacks, dresses, skirts). With
  `prefer_complete` they stay as they are and `animation_check` says so.
- The LPC muscular, child and pregnant bodies lack some animations (e.g. muscular has no
  `shoot` or `climb`); `animation_check` reports them in `body_missing`.
- Godot 3 is not supported (Godot 4 only). Unity was tested on Unity 6.
- Runs locally (stdio); it does not work with clients that only accept remote servers.

## Development
```
git clone https://github.com/kyuza1/lpc-character-mcp.git
cd lpc-character-mcp
pip install -e ".[dev]"
python -m pytest -q
```
From a clone, definitions, cache and output live inside the clone (`lpc/`, `cache/`,
`output/`). Tests run on GitHub Actions on Linux, Windows and macOS on every push and
every Monday (to catch changes in the official LPC repository). Releases are published to
PyPI automatically when a GitHub release is created. See [CHANGELOG.md](https://github.com/kyuza1/lpc-character-mcp/blob/main/CHANGELOG.md).

## License
Code under [MIT](https://github.com/kyuza1/lpc-character-mcp/blob/main/LICENSE). The downloaded art belongs to the LPC artists and follows their
licenses (see the generated credits files).
