2d Games Assets Generator

2d-assets-mcp

在设计美术之前，先设计游戏的手感。

就像线框图能帮助设计师在动笔绘制之前直观了解用户流程一样，2d-assets-mcp 能帮助游戏开发者预览时序、每秒帧数（FPS）、碰撞边界和 UI 布局，而不必花费数小时制作最终美术素材。

这个 MCP（模型上下文协议） 服务可让任何 AI 助手（Antigravity、Claude Code、Codex、Devin，或任何兼容 MCP 的助手）直接在你的项目文件夹中生成高级 2D 模拟／占位素材，并以 PNG 格式保存。借助 2d-assets-mcp 节省时间、加快原型制作，完善游戏手感，等准备就绪后再用原创美术替换模拟素材。

这个 MCP 与游戏引擎无关，可与任何支持导入 PNG 的游戏引擎完美配合，例如：

• Godot
• Unity
• Unreal Engine
• GameMaker
• Construct
• RPG Maker
• 还有许多其他引擎！

节省时间，创建占位生命值条、精灵图集和你能想到的各种 UI 元素，并全面支持渐变、图案、透明度、文字旋转和自动缩放；整个过程只需聊天，无需打开图像编辑器。 它的设计初衷是帮助你先测试并迭代游戏手感：通过原型测试缩放、跳跃弧线和动画时序，不必等待最终美术素材，同时也能轻松调整。需要把占位按钮放大 20%？只需让你的 AI 客户端重新生成即可。

提示

2d-assets-mcp 带有适合 AI 使用的元数据 → 也就是说，每个生成的 PNG 都会在其 EXIF 数据中直接嵌入丰富的 JSON 元数据（尺寸、颜色、形状、渐变属性、图案详情、文字属性、描边属性、描述），因此不具备视觉能力的 AI 模型也能理解素材包含的内容。

生成素材示例

以下是此 MCP 服务生成的一些素材示例：

角色精灵与动画

英雄待机动画（8 帧，512x64）

带特效的 8 帧待机动画精灵图集

UI 元素

攻击按钮（128×48）

带红色渐变、圆角和“ATTACK”标签的按钮

生命值条（200×24）

填充 75% 的生命值条，采用绿色填充和深灰色轨道

游戏道具

金币（32×32）

带径向渐变、圆点图案叠加和“COIN”标签的圆形金币

草地和水面

树木

动画精灵图集

火焰动画（4 帧，192x48）

4 帧精灵图集

安全注意事项

素材内容

• 生成的素材是纯占位图形，不包含恶意代码。
• 嵌入的元数据是纯文本 JSON，不可执行。

由于此 MCP 服务会直接在你的计算机上写入文件以节省时间，请遵循以下安全最佳实践：

文件系统访问

• 服务器可以将文件写入 AI 助手指定的任意路径。
• 建议： 将 AI 客户端配置为严格限制对游戏项目目录的访问权限。
• 警告： 请求 AI 在项目目录之外生成资源时，请务必谨慎。

路径遍历

• 此服务器会验证路径，但使用 MCP 服务时仍应始终留意潜在的路径遍历尝试，并在确认操作前检查生成的文件路径。

最佳实践

• 在配置中使用绝对路径，以避免歧义。
• 仅允许 AI 访问游戏项目目录。
• 在提交到版本控制前检查生成的资源。
• 保持 Node.js 依赖项为最新版本。

核心功能

• 即时生成资源：一次工具调用生成一张 PNG，并完整配置视觉效果。
• 精灵表与批量模式：在一次请求中生成多帧，或将多帧合成为单个动画条精灵表。
• 丰富的视觉效果：支持纯色填充、线性／径向渐变、条纹／圆点／网格图案叠加、圆角、圆形、不透明度和描边控制。
• 动态 UI 元素：使用 fillPercent 和 trackColor 为部分填充的资源创建部分填充的进度条／生命值条。
• 自动缩放标签：文本会自动缩放以适应资源；如有需要，也可以通过显式设置 fontSize 覆盖此行为。
• 适用于非视觉 AI：无需加载图像像素，即可通过 read_image_metadata 读取嵌入的 JSON 元数据，非常适合非视觉 AI 工作流。
• 智能命名：输出文件会自动使用其尺寸命名（例如 player_idle_128x128.png），帮助无法查看图像的模型了解资源尺寸。

工具参考

此 MCP 服务为 AI 提供 3 个工具，用于生成和读取 2D 资源元数据。

1. generate_mock_asset

生成单个 PNG 资源并写入磁盘。支持渐变、图案、透明度、文本旋转和嵌入元数据。

说明

输出文件名格式

服务会在写入前自动将尺寸追加到文件名中：

player_idle.png  →  player_idle_128x128.png

2. generate_mock_asset_batch

在一次请求中生成多个资源。支持生成多个独立 PNG 文件，或合成为一张精灵图。

说明

精灵图布局

所有资源都排列在同一行中（传统动画条）。每个帧单元格的尺寸与批次中最大的资源相同；较小的资源会在其单元格内居中。输出文件名包含精灵图的总尺寸：

player_run.png  →  player_run_648x136.png

3. read_image_metadata

读取此服务生成的任意 PNG 文件中嵌入在 EXIF ImageDescription 字段里的 JSON 元数据。对于不具备视觉能力的 AI 模型很有用，因为无需解码图像，它们也能了解资源包含的内容。

元数据嵌入方式

元数据以 JSON 字符串的形式存储在 PNG 的 EXIF IFD0.ImageDescription 字段中，使用 sharp 库的 withMetadata API。

读取时会有意绕过标准 TIFF 字节遍历：不解析二进制 TIFF 结构，而是将原始 EXIF 缓冲区作为 UTF-8 字符串扫描，查找已知的 "generator":"2d-assets-mcp" 键，然后提取其周围的 JSON 对象。这使读取器不受不同 PNG 写入器带来的 TIFF 填充、字节序差异和特殊 IFD 布局的影响。

{
  "generator": "2d-assets-mcp",
  "type": "asset",
  "name": "player_idle",
  "width": 128,
  "height": 128,
  "color": "#4A90E2",
  "shape": "rounded-rectangle",
  "fillMode": "linear-gradient",
  "fillPercent": 100,
  "trackColor": null,
  "pattern": "none",
  "secondaryColor": "#2E5A8A",
  "gradientAngle": 45,
  "textRotation": 0,
  "textPosition": "center",
  "strokeColor": "#000000",
  "strokeWidth": 4,
  "description": "Player idle placeholder, blue rounded rectangle 128x128",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

{
  "generator": "2d-assets-mcp",
  "type": "spritesheet",
  "totalWidth": 648,
  "totalHeight": 136,
  "columns": 4,
  "rows": 1,
  "frameCount": 4,
  "frameWidth": 128,
  "frameHeight": 128,
  "margin": 8,
  "spacing": 8,
  "frames": [
    {
      "index": 0,
      "x": 8,
      "y": 8,
      "width": 128,
      "height": 128,
      "name": "frame_0",
      "color": "#4A90E2",
      "shape": "rounded-rectangle"
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z"
}

面向 AI 的示例提示词

连接到 AI 编码助手后，试试这些提示词来加快工作流：

单个素材

“在 C:\Users\me\project\assets\sprites\（Windows）、/home/me/project/assets/sprites/（Linux）或 /Users/me/project/assets/sprites/（macOS）中，为我的玩家角色创建一个 128×128 的蓝色圆角矩形占位图。标注为 ‘Player’，并添加径向渐变。”

生命值条

“在项目的 UI 文件夹中生成一个 200×24 像素的生命值条 PNG，填充 65%，使用细描边、红色填充和深灰色轨道。将文件命名为 health_bar.png。”

精灵图集

“为我的玩家创建一个包含 4 帧的奔跑循环精灵图集。每帧应为 64×64，使用不同深浅的蓝色，并标注为 Frame 1 到 Frame 4。将其保存到项目的精灵文件夹中。”

读取元数据

“读取项目精灵文件夹中 player_idle_128x128.png 的元数据。”

安装

选项 1：直接使用 npx（无需安装）

将其连接到任意 AI 编码助手的最快方式：

{
  "mcpServers": {
    "2d-assets": {
      "command": "npx",
      "args": ["-y", "2d-assets-mcp"]
    }
  }
}

选项 2：使用包管理器（pnpm、npm、yarn）手动安装

1. 克隆仓库

git clone https://github.com/crony-io/2d-assets-mcp.git
cd 2d-assets-mcp

2. 安装依赖项

pnpm install   # recommended
# or: npm install
# or: yarn install

3. 构建项目

pnpm run build
# or: npm run build
# or: yarn run build

4. 配置 MCP 客户端

{
  "mcpServers": {
    "2d-assets-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/2d-assets-mcp/dist/index.js"]
    }
  }
}

选项 3：使用 pnpm 或 npm 全局安装

本项目适用于任意 Node.js 包管理器。请选择你偏好的包管理器：

npm

npm install -g 2d-assets-mcp

pnpm

pnpm add -g 2d-assets-mcp

然后引用已安装的二进制文件：

{
  "mcpServers": {
    "2d-assets": {
      "command": "2d-assets-mcp"
    }
  }
}

Claude Code / Claude Desktop

将以下内容添加到 Claude Code/Claude Desktop 的 MCP 设置中：

{
  "mcpServers": {
    "2d-assets-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/2d-assets-mcp/dist/index.js"]
    }
  }
}

Devin

将以下内容添加到 Devin 的 MCP 设置（mcp_config.json）中：

{
  "mcpServers": {
    "2d-assets-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/2d-assets-mcp/dist/index.js"],
      "disabled": false
    }
  }
}

Cursor

在项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "2d-assets-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/2d-assets-mcp/dist/index.js"]
    }
  }
}

开发

前置条件

• Node.js 18 或更高版本
• pnpm 8 或更高版本 或 npm 9 或更高版本（任意包管理器均可）

设置

git clone https://github.com/crony-io/2d-assets-mcp.git
cd 2d-assets-mcp
# Choose your package manager:
pnpm install   # recommended
# or
npm install
# or
yarn install

脚本

添加新工具

1. 创建 src/tools/yourTool.ts，并导出 registerYourTool(server: McpServer) 函数
2. 在 src/server.ts 中导入并调用该函数
3. 将任何新的 Zod schema 添加到 src/schemas.ts，并将类型添加到 src/types.ts

许可证

MIT — 完整文本请参阅 LICENSE。

贡献

欢迎提交问题和拉取请求。提交 PR 前，请务必：

1. 运行 pnpm run check 或 npm run check（必须零错误）。
2. 将新工具放在 src/tools/ 下的独立文件中。
3. 在 src/types.ts 中导出新类型，并在 src/schemas.ts 中导出 schema。
4. 对于新增或变更的参数，请更新本 README 的 工具参考 部分。