Pixel MCP Server

PixelMCP服务器

无头像素艺术引擎作为 模型上下文协议（MCP） 服务器。使LLM和AI代理能够完全通过结构化工具调用创建、动画化和导出生产就绪的2D游戏艺术——精灵、拼贴集和动画。

这是什么？

PixelMCPServer充当 “无头Aseprite” LLM调用MCP工具，而不是在GUI中单击，以：

• 绘制像素艺术 --图元（直线、矩形、圆、填充）、体像素写入和等轴测助手
• 管理调色板 --索引颜色（最多256个条目）、Lospec集成、颜色渐变
• 动画 --具有每帧定时、方向标签、乒乓球播放的多帧序列
• 构建瓷砖集 --瓦片提取、自动瓦片生成（blob47、4side、4corner）、每个瓦片碰撞数据
• 游戏引擎导出 --PNG、GIF、精灵表、纹理图集和原生Godot 4.x资源(SpriteFrames, TileSet)

服务器使用对代理友好的MCP协议，这意味着任何兼容MCP的客户端（Claude、Cursor、Cline等）都可以使用它。

关键设计决策

索引颜色

所有像素数据都存储调色板索引（0-255），而不是原始RGBA值。这使得即时全局颜色交换、基于调色板的效果和内存高效存储成为可能，这与Aseprite等经典像素艺术工具使用的方法相同。

基于多态动作的工具

现代代理框架施加了工具数量限制。服务器不是每次操作一个工具，而是公开 10个多态工具，每个都有一个 action 选择特定操作的参数。这使得工具数量低，同时提供了一个全面的创意界面。

JSON资产格式

资产存储为人类可读的JSON文件，其中包含像素数据 行整数数组 格式(data[y][x] =调色板索引）。这是针对人工智能工作流程的：格式是可检查的，对差异友好的，并且可以在没有专门解码器的情况下进行解析。当需要实际图像时，服务器的导出管道会生成标准格式。

明确的目标

每次工具调用都需要明确 asset_name, layer_id，以及 frame_index 参数——没有隐式的“活动层”或“当前帧”。这消除了LLM驱动的工作流中的歧义。

工具

批量操作

draw, transform，以及 effect 接受a 操作数组 --在一次调用中执行多个操作，共享一个撤消步骤。这在保持API一致性的同时，消除了运营中的往返行程。

数据模型

Project (on disk: pixelmcp.json)
  └── Asset Registry (logical name → file path)

Workspace (in memory, not persisted)
  ├── Loaded Assets
  ├── Undo/Redo History
  └── Active Selection

Asset (on disk: .json file)
  ├── Palette (up to 256 RGBA entries)
  ├── Layers (image, tilemap, shape, group)
  ├── Frames (each with duration_ms)
  ├── Cels (layer × frame → pixel data)
  └── Tags (animation sequences, layer groups)

MCP资源

支持它们的客户端的可视化预览资源（补充--LLM通过工具操作读取状态）：

MCP提示

用户调用的工作流模板（例如，通过斜线命令）为LLM的上下文设置种子：

• scaffold_character --引导角色角色角色创建（调色板、图层、方向标签、hitbox）
• scaffold_tileset --blob47自动文件平铺集创建指南
• scaffold_equipment --用合适的变体引导模块化设备
• analyze_asset --批评调色板的使用、条带、完整性
• export_for_godot --确定资产的正确导出操作

Godot集成

服务器生成一流的Godot 4.x资源：

• godot_spriteframes — SpriteFrames .tres 对于每个标签的动画， AtlasTexture 子资源、基于GCD的FPS、乒乓球扩展和可选的碰撞形状动画轨迹
• godot_tileset — TileSet .tres 随着 TileSetAtlasSource，每块碰撞多边形、导航多边形和地形对等位（blob47/4side/4corner）
• godot_static --用于非动画资源的复合PNG+导入sidecar
• 所有出口包括 .png.import 带有像素艺术默认值的sidecar（无损压缩，无mipmap）

文件格式

pixelmcp.json --项目文件

根配置。包含资产注册表、命名约定(export_pattern)，以及项目默认值（图块大小、导出比例、默认调色板）。无像素数据。

.json --资产档案

具有调色板、图层层次结构、框架、cels（作为调色板索引数组的像素数据）和标签的自包含艺术资源。支持图像层、平铺图层、形状层（碰撞几何体）、组层和链接的cels（无数据复制的共享帧）。

.json --调色板文件

共享调色板({ name, colors: [[r,g,b,a], ...] })用于跨资产颜色一致性。

入门指南

先决条件

• Node.js 18+
• npm

安装

git clone https://github.com/jsreed/PixelMCPServer.git
cd PixelMCPServer
npm install

构建与运行

npm run build    # Compile TypeScript
npm run start    # Run the MCP server on stdio

或用于开发：

npm run dev      # Run directly with tsx (no build step)

MCP客户端配置

克劳德桌面版 --添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "pixelmcpserver": {
      "command": "node",
      "args": ["/path/to/PixelMCPServer/dist/index.js"]
    }
  }
}

光标/线 --将相同的JSON格式放置在工具的MCP配置文件中（例如。， .cursor/mcp.json 或Cline的MCP设置）。

克劳德代码 --从任何目录运行一次：

claude mcp add pixelmcpserver -- node /path/to/PixelMCPServer/dist/index.js

示例项目

这 example/ 目录包含一个演示文件格式的最小示例项目：

• example/pixelmcp.json --具有约定、默认值和两个注册资产的项目配置
• example/palettes/game.json --一个共享的12色调色板文件
• example/assets/hero.json --16×16字符精灵：2个图像/形状层，2个空闲帧 ping_pong facing-S动画标签，链接hitbox cel
• example/assets/coin.json --8×8项目精灵：4帧旋转动画(forward 环），用于反向椭圆形框架的链接cel

用服务器打开它：

{ "tool": "project", "action": "open", "path": "/path/to/PixelMCPServer/example" }

示例：创建Sprite

本演练显示了最小可行循环——初始化项目、创建资源、绘制像素和导出。

1.初始化项目

{ "tool": "project", "action": "init", "path": "/my/game/art" }

2.创建资产

{
  "tool": "asset",
  "action": "create",
  "name": "player",
  "width": 16,
  "height": 24,
  "palette": [
    [0, 0, 0, 0],
    [45, 30, 20, 255],
    [120, 85, 60, 255],
    [200, 160, 120, 255]
  ],
  "layers": [
    { "name": "body", "type": "image" },
    { "name": "eyes", "type": "image" }
  ],
  "frames": [{ "duration_ms": 150 }, { "duration_ms": 150 }],
  "tags": [{ "name": "idle", "type": "frame", "start": 0, "end": 1, "direction": "ping_pong" }]
}

3.绘制像素（批量-一个撤消步骤）

{
  "tool": "draw",
  "asset_name": "player",
  "layer_id": 0,
  "frame_index": 0,
  "operations": [
    { "action": "rect", "x": 4, "y": 8, "width": 8, "height": 12, "color": 2, "filled": true },
    { "action": "fill", "x": 5, "y": 9, "color": 3 },
    { "action": "circle", "x": 8, "y": 4, "radius": 4, "color": 2, "filled": true }
  ]
}

4.检查像素数据

{ "tool": "asset", "action": "get_cel", "asset_name": "player", "layer_id": 0, "frame_index": 0 }

5.保存

{ "tool": "workspace", "action": "save", "asset_name": "player" }

6.导出为PNG

{
  "tool": "export",
  "action": "png",
  "asset_name": "player",
  "output_path": "/my/game/art/exports/player.png",
  "scale_factor": 2
}

Godot导出

制作a SpriteFrames .tres 为Godot 4.x做好准备：

{
  "tool": "export",
  "action": "godot_spriteframes",
  "asset_name": "player",
  "output_dir": "/my/game/art/exports"
}

这写道 player.png, player.png.import，以及 player.tres --直接导入到您的Godot项目中。

项目结构

src/
├── index.ts              # Entry point — registers tools, starts stdio transport
├── errors.ts             # Shared error factory for domain errors
├── types/                # Interfaces & discriminated unions (no runtime logic)
├── classes/              # Stateful classes — Palette, Asset, Project, Workspace
├── commands/             # Command pattern (undo/redo) — one class per mutation category
├── io/                   # File I/O — read/write asset, project, and palette JSON files
├── algorithms/           # Pure functions — drawing, geometry, compositing, dithering, autotile
├── tools/                # MCP tool handlers — one file per tool (10 files, 1:1 with design spec)
├── resources/            # MCP Resource handlers — visual preview rendering (PNG/GIF)
└── prompts/              # MCP Prompt handlers — workflow templates

• types/ --纯接口和有区别的联合，没有运行时逻辑。进口的一切。
• classes/ --强制数据模型不变量的有状态类。无MCP意识。
• commands/ --撤销/重做命令类（每个变异类别一个：cel写入、层、帧、标记等）。
• io/ --文件序列化。模型处理 toJSON()/fromJSON(); io/ 手柄 fs 读/写。
• algorithms/ --没有模型依赖关系的纯函数。可独立测试。涵盖绘图图元（Bresenham、中点圆/椭圆、洪水填充）、几何体（行进方块、RDP简化）、效果（渐变、抖动、轮廓、自动AA）、合成、装箱、自动文件位掩码计算等。
• tools/ --薄MCP包装。每个文件导出 register*Tool(server) 这叫 server.registerTool() 使用Zod模式并委托给模型/算法。
• resources/ — pixel://view/... 用于视觉预览的URI处理程序。
• prompts/ --工作流模板生成器（scaffold_character、scaffold_tileset等）。
• 测试 托管为 *.test.ts 在源文件旁边。

发展

npm run test         # Run tests (Vitest)
npm run test:watch   # Watch mode
npm run lint         # ESLint (type-aware)
npm run typecheck    # tsc --noEmit
npm run format       # Prettier

技术栈

• 运行时间： Node.js（ES2022、ESM）
• 语言： TypeScript（严格模式）
• MCP-SDK： @modelcontextprotocol/sdk — McpServer 具有Zod模式验证的高级API
• 架构验证： 萨德
• 测试： 维测试
• Linting： ESLint（扁平配置， strictTypeChecked)+更漂亮

文档

• docs/design.md -体系结构规范和完整的API参考
• docs/implementation-plan.md --分阶段建造计划
• docs/research/ --支持研究（像素艺术工作流程、Godot资源元数据、示例LLM聊天场景）

许可证

无执照的