pyxel-mcp

Run a Pyxel script and capture a screenshot after N frames.

Args: script_path: Absolute path to the .py script to run. frames: Number of frames to render before capturing (default: 60). scale: Screenshot scale multiplier (default: 1). timeout: Maximum seconds to wait for the script (default: 10).

Get Pyxel installation info: package location, examples path, and API stubs path.

Render a Pyxel sound or music to WAV and return waveform analysis.

Runs the script to set up sounds (without starting the game loop), then renders the specified sound or music to WAV and analyzes the audio. Returns note sequence with timing, frequency, and volume data.

Args: script_path: Absolute path to the .py script to run. sound_index: Sound slot to render, 0-63 (default: 0). Ignored when music_index is set. duration_sec: Duration in seconds. 0 = auto-detect from sound length (10s for music). timeout: Maximum seconds to wait for the script (default: 10). music_index: Music slot to render, 0-7. When set (>=0), renders the full multi-channel music mix instead of a single sound.

Inspect sprite pixel data from a Pyxel image bank.

Reads pixel data, checks horizontal/vertical symmetry, and reports color usage. Use this to verify sprite quality and find asymmetries.

Args: script_path: Absolute path to the .py script to run. image: Image bank index, 0-2 (default: 0). x: X position in the image bank (default: 0). y: Y position in the image bank (default: 0). w: Width of the region to inspect (default: 8). h: Height of the region to inspect (default: 8). timeout: Maximum seconds to wait for the script (default: 10).

Capture screenshots at multiple frame points for animation verification.

Returns multiple images captured at specified frame numbers. Useful for verifying animations, transitions, and time-based effects.

Args: script_path: Absolute path to the .py script to run. frames: Comma-separated frame numbers to capture (default: "1,15,30,60"). scale: Screenshot scale multiplier (default: 1). timeout: Maximum seconds to wait for the script (default: 30).

Play a game by sending simulated input and capture screenshots.

Simulates keyboard/mouse input at specific frames and captures screenshots at specified frame points. Use this to test input-dependent game logic (menus, movement, shooting) without manual play.

Args: script_path: Absolute path to the .py script to run. inputs: JSON array of input events. Each event: {"frame": N, "keys": ["KEY_SPACE", ...], "mouse_x": X, "mouse_y": Y} Keys are held from their frame until a later entry changes them. Default state: no keys pressed, mouse at (0,0). frames: Comma-separated frame numbers to capture screenshots (default: "1,30,60"). scale: Screenshot scale multiplier (default: 1). timeout: Maximum seconds to wait for the script (default: 30).

Analyze screen layout, text alignment, and visual balance.

Detects text positions, checks horizontal balance, and identifies centering issues. Use this to verify UI layout quality.

Args: script_path: Absolute path to the .py script to run. frames: Frame number to analyze (default: 5). timeout: Maximum seconds to wait for the script (default: 10).

Read game object attributes at specific frames for debugging.

Captures the App instance (the class that calls pyxel.run()) and dumps its attributes as JSON. Supports single frame or comma-separated multi-frame timeline with automatic diff between frames.

Args: script_path: Absolute path to the .py script to run. frames: Frame number(s) to inspect, comma-separated (default: "60"). Use multiple frames for timeline diff: "10,30,60" attributes: Comma-separated attribute names to inspect (default: all). timeout: Maximum seconds to wait for the script (default: 10).

Validate a Pyxel script without running it.

Performs AST parsing and checks for common Pyxel anti-patterns. Much faster than run_and_capture for catching syntax errors and obvious mistakes before execution.

Args: script_path: Absolute path to the .py script to validate.

Capture screen as a compact color index grid.

Returns the screen contents as a 2D array of Pyxel palette indices (0-15). Much smaller than a screenshot image and enables programmatic comparison. Each row is a string of hex digits (0-f).

Args: script_path: Absolute path to the .py script to run. frames: Frame number to capture (default: 5). timeout: Maximum seconds to wait for the script (default: 10).

Compare screenshots at two frames and report pixel differences.

Captures the screen as color grids at two frames and computes a diff. Returns changed pixel count, percentage, and which screen regions changed. Use this for visual regression testing.

Args: script_path: Absolute path to the .py script to run. frame_a: First frame number (default: 1). frame_b: Second frame number (default: 30). timeout: Maximum seconds to wait for the script (default: 15).

Analyze color usage and contrast in a Pyxel screenshot.

Captures the screen and reports which of Pyxel's 16 colors are used, their distribution, background color, and potential contrast issues.

Args: script_path: Absolute path to the .py script to run. frames: Frame number to analyze (default: 5). timeout: Maximum seconds to wait for the script (default: 10).

Inspect tilemap content, tile usage, and layout.

Reads tilemap data and reports tile grid, usage statistics, bounding box of non-empty tiles, and imgsrc setting.

Args: script_path: Absolute path to the .py script to run. tilemap: Tilemap index 0-7 (default: 0). frames: Frame at which to read tilemap (default: 1). timeout: Maximum seconds to wait for the script (default: 10).

Visualize an entire Pyxel image bank as a single screenshot.

Renders the full 256x256 pixel contents of an image bank, showing all sprites and tiles at once. Useful for verifying sprite sheet organization and finding available space.

Args: script_path: Absolute path to the .py script to run. bank: Image bank index 0-2 (default: 0). scale: Screenshot scale multiplier (default: 1). timeout: Maximum seconds to wait for the script (default: 10).