Metadata-Version: 2.4
Name: pyxel-mcp
Version: 0.9.2
Summary: MCP server for Pyxel, a retro game engine for Python. Enables AI to autonomously run, verify, and iterate on retro game programs.
Project-URL: Homepage, https://github.com/kitao/pyxel-mcp
Project-URL: Repository, https://github.com/kitao/pyxel-mcp
Project-URL: Bug Tracker, https://github.com/kitao/pyxel-mcp/issues
Author-email: Takashi Kitao <takashi.kitao@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,game-engine,mcp,model-context-protocol,pixel-art,pyxel,retro-game
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: numpy
Requires-Dist: pyxel>=2.8.9
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Description-Content-Type: text/markdown

# pyxel-mcp

MCP server for [Pyxel](https://github.com/kitao/pyxel), a retro game engine for Python. Enables AI to autonomously run, verify, and iterate on retro game programs.

## Features

### Run & Capture

- **`run_and_capture`** — Run a Pyxel script and capture a screenshot after N frames
- **`capture_frames`** — Capture screenshots at multiple frame points for animation verification
- **`play_and_capture`** — Play a game by sending simulated input and capture screenshots

### Inspect & Debug

- **`validate_script`** — Validate a Pyxel script without running it
- **`inspect_state`** — Read game object attributes at specific frames for debugging
- **`inspect_screen`** — Capture screen as a compact color index grid
- **`compare_frames`** — Compare screenshots at two frames and report pixel differences

### Visual Analysis

- **`inspect_sprite`** — Inspect sprite pixel data from a Pyxel image bank
- **`inspect_layout`** — Analyze screen layout, text alignment, and visual balance
- **`inspect_palette`** — Analyze color usage and contrast in a Pyxel screenshot
- **`inspect_bank`** — Visualize an entire Pyxel image bank as a single screenshot
- **`inspect_tilemap`** — Inspect tilemap content, tile usage, and layout
- **`inspect_animation`** — Check sprite sheet consistency across animation frames

### Audio

- **`render_audio`** — Render a Pyxel sound or music to WAV and return waveform analysis

### Utility

- **`pyxel_info`** — Get Pyxel installation info: package location, examples path, and API stubs path

## Getting Started

Just ask your AI agent (e.g. Claude Code) to create a Pyxel game. The agent will automatically discover and set up pyxel-mcp from the [MCP Registry](https://registry.modelcontextprotocol.io/).

## Manual Installation

1. Install the package:

```bash
pip install pyxel-mcp
```

2. Register `pyxel-mcp` as an MCP server in your AI agent. For Claude Code, add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "pyxel": {
      "type": "stdio",
      "command": "pyxel-mcp"
    }
  }
}
```

## MCP Registry

mcp-name: io.github.kitao/pyxel-mcp

## License

MIT
