{
  "markdown": "# pyxel-mcp\n\nAn MCP server for observing programs built with [Pyxel](https://github.com/kitao/pyxel). It runs trusted local scripts headlessly and returns structured state, pixels, assets, audio, and frame differences.\n\n[![PyPI](https://img.shields.io/pypi/v/pyxel-mcp)](https://pypi.org/project/pyxel-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/pyxel-mcp)](https://pypi.org/project/pyxel-mcp/)\n[![Tests](https://img.shields.io/github/actions/workflow/status/kitao/pyxel-mcp/test.yml?branch=main&label=tests)](https://github.com/kitao/pyxel-mcp/actions/workflows/test.yml)\n[![License](https://img.shields.io/pypi/l/pyxel-mcp)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.kitao%2Fpyxel--mcp-blue)](https://registry.modelcontextprotocol.io)\n\nThe server deliberately reports facts rather than a universal quality score. The agent using it chooses the checks that matter for the game.\n\n## Install\n\nWith Claude Code:\n\n```bash\nclaude mcp add pyxel -- uvx pyxel-mcp\n```\n\nFor another MCP client, run `uvx pyxel-mcp install` or add:\n\n```json\n   {\n     \"mcpServers\": {\n       \"pyxel\": {\n         \"command\": \"uvx\",\n         \"args\": [\"pyxel-mcp\"]\n       }\n     }\n   }\n```\n\nRestart the client after changing its configuration. The server writes this diagnostic to stderr:\n\n```text\n[pyxel-mcp] starting - 8 tools\n```\n\nPython 3.11+ is required, and Pyxel >= 2.9.6 is installed as a dependency. Script tools execute local Python in subprocesses to isolate Pyxel state, but they do not sandbox untrusted code. See [SECURITY.md](SECURITY.md).\n\n## Tools\n\nEvery `script` argument is a file path, not Python source.\n\n| Tool | Returns |\n|---|---|\n| `validate` | Syntax errors and recognizable Pyxel code patterns. |\n| `run` | Headless frames, scheduled input, logs, and `state`, `screen_image`, `screen_grid`, or `video` snapshots. |\n| `pyxel_info` | Installed versions, paths, examples, and resource URIs. |\n| `read_palette` | Palette colors and image-bank indices in use. |\n| `read_image` | Image-bank pixels and an optional PNG render. |\n| `read_tilemap` | Tile coordinates, source bank, usage counts, bounds, and an optional render. |\n| `read_audio` | A rendered sound or music WAV plus measurable audio data. |\n| `diff_frames` | Pixel differences between two PNG files. |\n\nAll tools declare input and output schemas. Every result includes `ok` and `errors`.\n\n## Example\n\nCapture state and the screen when a condition first becomes true:\n\n```json\n{\n  \"script\": \"/absolute/path/game.py\",\n  \"frames\": 600,\n  \"until\": \"score >= 1\",\n  \"snapshots\": [\n    {\"kind\": \"state\", \"frame\": \"end\", \"attrs\": [\"score\", \"player.x\"]},\n    {\"kind\": \"screen_image\", \"frame\": \"end\", \"output\": \"/tmp/goal.png\"}\n  ]\n}\n```\n\nUse absolute artifact paths. Read `log` even when `ok` is true, and inspect captured images directly when appearance matters.\n\n## Resources\n\n- `pyxel://run-snapshots-schema` — complete `run.snapshots` grammar.\n- `pyxel://validation-patterns` — categories reported by `validate`.\n- `pyxel://palette/default` — default palette table.\n- `pyxel://examples/{name}` — source for an example bundled with the installed Pyxel package; discover names with `pyxel_info`.\n\nFull game-building guidance lives in the separate [pyxel-skill](https://github.com/kitao/pyxel-skill) project; this package contains only the MCP server.\n\n## Update\n\n`uvx` caches packages. Force a refresh with:\n\n```bash\nuvx --refresh-package pyxel-mcp pyxel-mcp install\n```\n\n## Troubleshooting\n\n- If tools do not appear, look for the `starting - 8 tools` diagnostic and restart the client.\n- If `run` fails, inspect `errors`, `exit_status`, and `log`.\n- If a validation category is unfamiliar, read `pyxel://validation-patterns`.\n\n## MCP Registry\n\n`mcp-name: io.github.kitao/pyxel-mcp`\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3818,
  "sha": "711b3256e0f61cfd612f48fe36c354ea424bd8c08d3c9dd622fb2fc5844633ba",
  "repo_slug": "kitao/pyxel-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kitao_pyxel_mcp_4c079d4c/readme"
}