ssyubix-pixelart-mcp

ssyubix-pixelart-mcp

用于绘制像素艺术和组装 2D 游戏图块集的 MCP 服务（Python）。 基于 MCP Python SDK v1.x （稳定版）构建，采用 stdio 传输方式，设计用于在同一个 Agent 会话中与 unity-mcp-server 配合使用。

安装

从 PyPI 安装：

pip install ssyubix-pixelart-mcp

或从源代码安装：

git clone https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp
cd ssyubix-pixelart-mcp
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

运行

python -m pixelart_mcp.server
# or, if installed from PyPI:
ssyubix-pixelart-mcp

连接到 Claude Desktop / Claude Code

将以下内容添加到 claude_desktop_config.json（Claude Desktop），或通过 claude mcp add（Claude Code）添加：

{
  "mcpServers": {
    "pixelart": {
      "command": "/path/to/ssyubix-pixelart-mcp/venv/bin/python",
      "args": ["-m", "pixelart_mcp.server"]
    }
  }
}

工具列表（24）

绘制

• pixelart_create_canvas、pixelart_import_canvas、pixelart_set_pixel、pixelart_draw_line、pixelart_draw_rect、pixelart_draw_circle、pixelart_draw_polygon、pixelart_flood_fill

画布管理

• pixelart_clear_canvas、pixelart_flip_canvas、pixelart_duplicate_canvas、pixelart_get_canvas_info、pixelart_get_canvas_preview、pixelart_delete_canvas、pixelart_list_canvases

调色板

• pixelart_generate_palette、pixelart_extract_palette

尺寸建议

• pixelart_suggest_tile_size、pixelart_suggest_tilemap_layout

图块集

• pixelart_create_tileset、pixelart_set_tile、pixelart_export_tileset、pixelart_delete_tileset、pixelart_list_tilesets

术语：图块、图块集与图块地图

这些概念很容易混淆，混淆后会产生损坏或尺寸过小的输出——生产环境中就发生过一个真实问题：Agent 请求“图块地图”，却得到一张 32x32 画布（这是图块的尺寸），并将其作为整张地图交付，导致它在实际比例下看起来不正常。

• 图块：一个小正方形（例如 16x16px）——pixelart_create_canvas。
• 图块集：由许多不同图块组成并按网格排列的图像（例如草地、道路、水面等图块类型）——pixelart_create_tileset + pixelart_set_tile + pixelart_export_tileset。
• 图块地图：由许多图块铺在网格上组成的完整关卡／地图（构建方式与图块集相同，但每个位置都填入图块，以呈现实际关卡布局）——绝不能只是单个图块大小的画布。

典型工作流

单个素材／图块：

1. pixelart_suggest_tile_size（可选）——根据对象类别或屏幕分辨率，获取理想的图块尺寸建议。
2. pixelart_generate_palette——根据风格／氛围创建调色板。
3. pixelart_create_canvas → pixelart_set_pixel / draw_line / draw_rect / draw_circle / flood_fill——绘制单个图块。
4. pixelart_get_canvas_preview——继续操作前查看结果（放大后的 PNG）。

图块集或完整图块地图／关卡： 5. pixelart_suggest_tilemap_layout——根据明确指定的图块数量或目标屏幕／关卡尺寸，获取所需的网格（列／行）和总像素尺寸。 6. 使用该网格调用 pixelart_create_tileset → 对每个位置调用 pixelart_set_tile → 调用 pixelart_export_tileset。 7. export_tileset 的结果包含 PNG 和 JSON 元数据（图块尺寸、网格、PPU）——随后 Agent 可以调用 unity-mcp-server 工具，将图块切片并导入 Unity 项目。

运行测试

sh claude_tools/run_tests.sh

结构

pixelart_mcp/
  server.py      # entry point, registers 23 tools
  canvas.py       # pixel drawing primitives
  palette.py      # palette generator
  sizing.py       # tile size heuristics
  tileset.py      # tileset assembly & export
  models.py       # Pydantic input models
  tests/          # 58 unit tests
claude_tools/     # helper script (dump schema, run tests)
task.md           # status & work notes
PUBLISHING.md      # guide to publish to PyPI & official MCP Registry

如果 unity-mcp-server 不可用

pixelart_mcp 在技术上不依赖 unity-mcp-server—— 上述所有工具在没有它的情况下都能正常工作。区别仅在于最后一步： 没有 unity-mcp-server 时，必须手动将 pixelart_export_tileset 的结果（PNG + JSON 元数据）导入 Unity Editor。以下步骤（基于 Unity 官方手册）可供 AI 在协助非技术用户时参考：

1. 将导出的 PNG 文件复制到 Unity 项目中的 Assets 文件夹（或 Assets/Sprites 之类的子文件夹）。
2. 在 Project 窗口中，点击 PNG 文件。在 Inspector 面板中：
   • Texture Type → Sprite (2D and UI)
   • Sprite Mode → Multiple（因为一个图集中包含多个图块）
   • Pixels Per Unit → 输入 JSON 元数据文件中的 ppu 值
   • Filter Mode → Point (no filter)——保持像素艺术清晰，不模糊
   • Compression → None——防止颜色失真
   • 点击 Apply。
3. 点击 Inspector 中的 Sprite Editor 按钮，打开 Sprite Editor。
4. 在 Sprite Editor 中，点击 Slice 下拉菜单，选择 Grid By Cell Size， 然后输入 JSON 元数据中的 tile_width x tile_height 作为 Pixel Size。
5. 点击 Slice，然后点击 Sprite Editor 工具栏中的 Apply。
6. 完成——现在每个图块都是独立的精灵，可以直接拖入 Scene，或在 Tilemap 中使用。

所有必需的值（tile_width、tile_height、ppu）都会自动 包含在 pixelart_export_tileset 生成的 .json 文件中 ——AI 无需计算，只需读取这些值并引导用户完成上述步骤。

维护或开发本项目的 AI Agent

请先阅读 AGENTS.md——其中包含架构概览、必须遵循的规范、 添加新工具的检查清单，以及处理用户反馈和功能请求的工作流。

许可证

Apache License 2.0——详见 LICENSE 和 NOTICE 文件。

发布到 PyPI 和 MCP Registry

完整指南请参见 PUBLISHING.md（包含准确命令，需要个人凭据——PyPI token 和 GitHub OAuth 登录）。

SDK 版本说明

本服务基于 v1.x MCP Python SDK 构建（稳定，推荐用于生产环境）。截至 2026 年 7 月， SDK v2 仍处于预发布阶段——根据“仅使用稳定且当前的官方参考资料”这一政策，本项目未使用该版本。