Skip to content
Back to search

game-sprite-gen-mcp

MCP server & CLI that turn text prompts into game-ready sprite-sheet animations via any OpenAI-compatible image API — auto background removal, per-frame QC, retries, and GIF preview.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oliwenfly--game-sprite-gen-mcp/badge.svg)](/listings/oliwenfly--game-sprite-gen-mcp)

HTML

<a href="/listings/oliwenfly--game-sprite-gen-mcp"><img src="/api/listings/oliwenfly--game-sprite-gen-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 114 lines
  1. # game-sprite-gen-mcp
  2. 一句提示词,直接生成可用的**序列帧动画素材**:自动出网格图、去背、逐格质检、不合格重试,最后导出对齐好的瓦片图、单帧、manifest 和 GIF 预览。通过 MCP 让 AI 客户端直接调用,不用你自己启动任何服务。
  3. ![fox_hit 序列帧瓦片图](example-fox-hit.png)
  4. ## 3 步开始用
  5. > **注意:全文示例路径 `D:/game-sprite-gen-mcp` 只是举例,不是固定值。请把它替换成你自己实际放源码的目录,其他地方不用改。**
  6. >
  7. > **另一个硬性前提:本机必须已经安装 Python 3.10+**,详见第 1 步。
  8. ### 1. 下载源码
  9. 下载或解压到任意目录,例如 `D:/game-sprite-gen-mcp`。
  10. > **硬性前提:本机必须已安装 Python 3.10+。** 源码不带 Python,入口脚本只会自动安装依赖包,不会安装 Python 本身。没装的话先去 https://www.python.org/downloads/ 下载安装,安装时勾选 **Add Python to PATH**。装完在命令行运行 `python --version`(macOS / Linux 用 `python3 --version`),能显示 3.10 以上的版本号就可以继续。
  11. > **记住这个路径**,第 3 步的 MCP 配置里要原样填上它。
  12. ### 2. 修改配置
  13. 源码目录下如果没有 `config.json`,新建一个(内容参考 `config.example.json`),或者直接把 `config.example.json` 改名为 `config.json`,然后按下面说明修改。必填的只有 `apiKey`,其余字段都有默认值。
  14. ```json
  15. {
  16. "baseUrl": "https://api.openai.com",
  17. "model": "gpt-image-2.5",
  18. "quality": "auto",
  19. "apiKey": "sk-你的Key",
  20. "outDir": "generated/sprites",
  21. "timeoutMs": 180000,
  22. "transparent": false
  23. }
  24. ```
  25. | 字段 | 默认值 | 说明 |
  26. | --- | --- | --- |
  27. | `apiKey` | 空 | 生图 API Key,必填 |
  28. | `baseUrl` | `https://api.openai.com` | 接口根地址,支持任意 OpenAI 兼容的生图网关 |
  29. | `model` | `gpt-image-2.5` | 生图模型 |
  30. | `quality` | `auto` | 质量参数,如 `low` / `medium` / `high` / `auto` |
  31. | `outDir` | `generated/sprites` | 默认输出目录,相对路径以源码目录为基准;工具调用也可传 `out_dir` 覆盖 |
  32. | `timeoutMs` | `180000` | 单次请求超时,单位毫秒 |
  33. | `transparent` | `false` | 模型是否直接返回透明 PNG,详见下方说明 |
  34. `transparent: true` 会在请求里带 `background: "transparent"`(并强制 `output_format: "png"`),模型直接出透明图,本地去背自动跳过。gpt-image-2.5 及之后支持;旧模型或第三方网关可能不支持该参数而报错,此时保持 `false`,走本地去背兜底。
  35. 也可以用环境变量临时覆盖:`SPRITEGEN_API_KEY`、`SPRITEGEN_BASE_URL`、`SPRITEGEN_MODEL`、`SPRITEGEN_QUALITY`、`SPRITEGEN_TIMEOUT_MS`、`SPRITEGEN_TRANSPARENT`。一般不用配。
  36. `config.json` 在 `.gitignore` 里,不会被提交。
  37. ### 3. 把这段粘到 AI 客户端的 MCP 配置里
  38. ```json
  39. {
  40. "mcpServers": {
  41. "spritegen": {
  42. "command": "python",
  43. "args": ["D:/game-sprite-gen-mcp/mcp_server.py"]
  44. }
  45. }
  46. }
  47. ```
  48. **只需要改 `args` 里的路径**:把示例中的 `D:/game-sprite-gen-mcp` 换成你第 1 步实际放源码的目录,其他原样照抄。
  49. - Windows:`command` 写 `python`
  50. - macOS / Linux:`command` 写 `python3`
  51. 重启 AI 客户端,然后直接对 AI 说:
  52. > 用 spritegen 生成 4 帧狐狸奔跑的序列帧,透明背景,名字叫 fox_run
  53. 第一次启动时入口脚本会自动安装 `mcp`、`pillow`、`httpx` 三个依赖(需联网,十几秒),以后不会再装。如果自动安装失败,它会把手动安装的命令打印出来。**不要手动运行这个脚本**,AI 客户端会自己拉起进程,关掉客户端进程就结束。
  54. 配置只认源码目录里的 `config.json`,改完立即生效,不用重启服务。
  55. ## AI 能调用的工具
  56. | 工具 | 说明 |
  57. | --- | --- |
  58. | `generate_animation` | **一步到位**:生图 → 去背 → 逐格质检 → 重试 → 合图,返回瓦片图和 manifest |
  59. | `build_spritesheet` | 把已有网格图做成对齐图集(不调用生图接口) |
  60. | `inspect_spritesheet` | 逐格质检,返回 bbox、尺寸、中心、空帧和偏差 JSON |
  61. | `remove_background` | 去除纯色背景(四角洪水填充,保留内部同色像素) |
  62. | `generate_image` | 纯生图,返回文件路径与尺寸 |
  63. | `edit_image` | 用本地图片作参考改图,适合保持角色一致 |
  64. 工具返回文本 JSON,并附带预览图,AI 客户端里能直接看到结果。
  65. ## 产物在哪
  66. 不传 `out_dir` 时,产物写到源码目录下的 `generated/sprites/`;也可以在工具参数里传绝对路径改到别处。
  67. ```
  68. generated/sprites/fox_run/
  69. source.png 去背后的原始网格图
  70. frame-0.png ... 对齐后的单帧
  71. spritesheet.png 横向瓦片图
  72. contact.png 联系图,便于目视检查
  73. preview.gif GIF 预览(透明区域压白底)
  74. manifest.json 引擎无关的图集描述,pivot 可直接用作锚点
  75. ```
  76. ## 已知限制
  77. - 帧间一致性取决于生图模型;复杂动作可能还是要用 `edit_image` 逐帧修正。
  78. - 去背是纯色键控,渐变背景和带阴影的背景去不干净;可让提示词强调 `flat uniform single-color`。
  79. - GIF 预览把透明区域压成白色,仅用于检查,不是交付格式。
  80. ## License
  81. MIT,见 [LICENSE](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.