LPC Character Generator

LPC 角色生成器 — MCP

English · Português

一个用于构建 LPC 像素艺术角色精灵图集的 MCP 服务——使用的部件与 Universal LPC Spritesheet Character Generator 相同—— 并可导出为可直接用于 Godot、Unity 和 Web（Phaser/PixiJS）的文件。

用自然语言提出需求（“做一个晒黑的铁匠，穿着皮围裙，拿着锤子”），你的助手就会组装角色、在聊天中显示动画预览，并保存文件。

上面的每个角色都由此 MCP 生成——包括主题角色（骑士、维京人、巫师、骷髅、兽人、军团士兵、海盗、国王……）和随机角色。

聊天内预览（preview_character）是一个动画 GIF——这里展示的是铁匠敲打铁锤：

安装

你需要 uv 和 Git。 uv 会自动获取合适的 Python 和软件包——无需克隆，也无需安装依赖项。

1. 安装 uv（仅需一次）：
   • Windows：powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   • macOS/Linux：curl -LsSf https://astral.sh/uv/install.sh | sh
2. 准备服务（下载物品定义，约 10 秒，仅需一次）：

   uvx lpc-character-mcp --setup
   

3. 在你的助手中注册（见下文）。命令始终为 uvx lpc-character-mcp。

若要直接运行 GitHub 上的最新代码，请在任意示例中将 uvx lpc-character-mcp 替换为 uvx --from git+https://github.com/kyuza1/lpc-character-mcp lpc-character-mcp。

角色会保存到 ~/lpc-characters（Windows 上为 C:\Users\<you>\lpc-characters）。 设置 LPC_OUTPUT_DIR 可更改保存位置——例如改为 Godot/Unity 的精灵图文件夹。 lpc-character-mcp --where 会列出当前使用的所有文件夹。消息为英文；设置 LPC_LANG=pt 可切换为葡萄牙语。

Claude Code

claude mcp add lpc --scope user -- uvx lpc-character-mcp

Claude Desktop

**一键安装：**从 最新版本下载 lpc-character-mcp.mcpb 并打开它 （或将其拖入 Settings → Extensions）。安装过程中可以选择输出文件夹和语言。

也可以在 Settings → Developer → Edit config（claude_desktop_config.json）中手动添加：

{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}

Codex (OpenAI)

codex mcp add lpc -- uvx lpc-character-mcp

也可以编辑 ~/.codex/config.toml（Windows 上为 %USERPROFILE%\.codex\config.toml）：

[mcp_servers.lpc]
command = "uvx"
args = ["lpc-character-mcp"]
startup_timeout_sec = 60

使用 codex mcp list 检查。同一个文件也供 Codex VS Code 扩展使用。

Antigravity (Google)

在 Agent 面板中点击 … → MCP Servers → Manage MCP Servers → View raw config，并将配置添加到 mcp_config.json（~/.gemini/config/mcp_config.json； Windows 上为 %USERPROFILE%\.gemini\config\mcp_config.json）：

{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}

保存后，点击 MCP Servers 页面上的 Refresh。在 Antigravity CLI 中，使用 /mcp。

目录

收录于 Smithery、 Glama 和官方 MCP Registry， 名称为 io.github.kyuza1/lpc-character-mcp。会自动被读取注册表的客户端和目录收录。

其他 MCP 客户端

任何可运行 stdio 服务的客户端都能使用相同的 uvx lpc-character-mcp 命令。

不使用 uv（pip）

pip install lpc-character-mcp
lpc-character-mcp --setup

然后在助手中注册 lpc-character-mcp 命令（不带参数）。

提示

• 释放磁盘空间： lpc-character-mcp --clear-cache 会删除缓存图片 （--clear-cache 30 只删除 30 天未使用的图片）。
• 更新： uvx lpc-character-mcp@latest --version
• 应用找不到 uvx： 使用完整路径（Windows 上运行 where uvx，其他系统运行 which uvx）。

示例请求

• “制作一名晒黑的铁匠，穿着皮围裙、拿着锤子，并导出为 Godot 格式”
• “显示他打铁的动画预览”
• “使用种子 1 生成 10 名随机村民，并附带 Unity 文件”
• “打开此链接并生成角色：https://liberatedpixelcup.github.io/...#sex=male&body=...”
• “哪些围裙带有男性身体可用的待机动画？”

工具

工具	功能
generate_character(items, body_type, animations, filename, layout, split, export, prefer_complete, output_dir)	生成 PNG、署名信息、动画报告和（可选）引擎文件
preview_character(items, body_type, animation, animated)	聊天内预览：显示包含 4 个方向的动画 GIF
search_items(query, category, body_type, animation, type_name, complete_only)	使用筛选条件搜索物品；完整物品优先
get_item(item_id)	颜色、变体、多色部件，以及各身体类型可用的动画
list_categories	列出物品类别
random_character(body_type, seed, fixed_items)	随机生成一个角色
generate_batch(count, body_types, seed, prefix, fixed_items, ..., output_dir)	一次生成多个随机 NPC
from_site_url(url) / to_site_url(items, body_type)	读取／构建生成器网站链接（包括旧链接）；from_site_url 也支持网站的“Export to Clipboard (JSON)”
update_definitions(clear_image_cache)	从官方仓库获取新物品和调色板
clear_cache(older_than_days, dry_run)	删除缓存图片（或仅删除 N 天未使用的图片）

示例 items：

[
  {"id": "body/body", "color": "bronze"},
  {"id": "head/heads/human/heads_human_male"},
  {"id": "hair/short/hair_plain", "color": "dark_brown"},
  {"id": "torso/shirts/longsleeve/torso_clothes_longsleeve", "color": "white"},
  {"id": "torso/aprons/torso_aprons_overalls", "variant": "leather"},
  {"id": "legs/pants/legs_cuffed", "color": "white"},
  {"id": "feet/boots/feet_boots_basic", "color": "brown"},
  {"id": "tools/tool_hammer", "color": ["steel", "walnut"]}
]

颜色

• "color": "blonde" — 单一颜色（参见 get_item 中的 colors）。
• "color": ["steel", "walnut"] — 多部件物品（头部和握柄、盔甲和腰带……）。 部件列于 get_item 返回的 color_parts 中；null 会保留部件的默认颜色。
• 头部、耳朵、鼻子等皮肤物品若未指定颜色，则继承身体颜色。
• 每种类型只能有一个物品，与网站一致：如果请求两种发型，则只保留最后一种（并会在 warnings 中说明）。

保存位置

output_dir 可将文件直接保存到文件夹中，例如游戏的精灵图文件夹： “将铁匠生成到 C:/my-game/art/npcs 并导出为 Godot 格式”。否则，文件会保存到 LPC_OUTPUT_DIR 或 ~/lpc-characters。

布局和部件

• layout: "standard"（默认）— 与网站相同：宽 832px，每个动画始终位于同一行（行走动画位于 y=512，挥砍动画位于 y=768……）。超大动画会放在 y=3456 以下。
• layout: "compact" — 仅包含请求的动画，并依次排列。
• split — 也会保存拆分素材："animation"（每个动画一张 PNG）、"frame"（每帧一张 PNG，存放于 <name>_frames/<animation>/<direction>_NN.png）和／或 "item"（每个物品一张图集，便于在游戏中更换服装）。接受列表：["animation", "frame"]。

超大动画

大型武器和工具（剑、长矛、锤子、斧头、弓……）使用 128 或 192px 的帧。请求其基础动画时会自动添加这些动画（例如，为锤子请求 slash 也会生成 tool_hammer）。

完整动画

并非所有 LPC 物品都有全部 15 种动画的素材（例如，围裙没有 idle、run、jump……动画）。在这些动画中，物品会直接消失。为避免意外：

• 每个结果都会发出警告。 generate_character 始终会返回 animation_check：

  "animation_check": {
    "complete": false,
    "incomplete_items": {
      "torso/aprons/torso_aprons_apron": {
        "missing": ["climb", "idle", "jump", "sit", "emote", "run", ...],
        "complete_alternatives": ["torso/aprons/torso_aprons_overalls", ...]
      }
    },
    "summary": "ATENÇÃO: nem todas as animações ficaram completas: Apron não tem ..."
  }
  

  预览、批次生成和网页演示也会发出警告。
• prefer_complete: true 会将每件动画不完整的物品替换为具有全部动画的最接近物品，同时保留颜色（例如，围裙 → 背带裤）。替换项会列在 replaced 中。助手会被告知先征求你的同意。
• 搜索会优先列出完整物品。 search_items 会将它们列在前面，为其他物品显示 missing_animations，并支持 complete_only: true。get_item 会显示缺少的动画，并推荐 complete_alternatives。
• 随机角色只使用动画完整的物品。

以下情况不计为缺少动画：角色面朝相反方向时，climb 动画中的脸部、鼻子、胡须、眼镜和项链；hurt 动画中的表情；武器、工具和盾牌（它们本来就只会出现在各自的动画中，详见 equipment_only_in）；以及角色身体本身不具备的动画（详见 body_missing）。

许可证（Steam、App Store）

LPC 素材采用多种许可证。对于带 DRM 的商店（Steam、App Store……），只有 CC0 和 OGA-BY 素材是安全的。向 search_items、random_character、generate_batch 或 generate_character 传入 licenses: ["CC0", "OGA-BY"]，即可仅使用这些许可证的素材——所选角色身体的每个素材部分都必须提供其中一种许可证（比网站的要求更严格；网站只要求任意一个部分符合条件即可）。每个结果还会包含 license_check：

"license_check": {"drm_safe": true, "share_alike_required": false, "summary": "..."}

导出到游戏引擎

向 generate_character 传入 export（可以组合使用）。动画播放顺序与官方生成器相同（行走会跳过站立帧，待机／坐下／表情动画会停留在相应帧……），并且还包含网站的额外动画：1h_slash（单手挥砍）和 watering（使用浇水壶）。设置 zip: true 会将所有内容打包为 <name>.zip。

export	文件	使用方法
"godot"	<name>.tres (SpriteFrames)	将 output_dir 设为项目内的目录进行生成（会自动填入 res:// 路径），或将 <name>.png 和 <name>.tres 复制到 res://characters/。将 .tres 用作 AnimatedSprite2D 的 Sprite Frames。动画名称示例：walk_down、idle_left、tool_hammer_right……已在 Godot 4.6 上测试。
"unity"	<name>.png.meta、<name>.controller + <name>_unity_anims/*.anim	将 output_dir 设为 Assets/ 内的目录进行生成（或将所有内容复制到那里）。精灵会预先切片（Multiple、Point filter、不压缩），.controller 会为每个动画创建一个状态（初始状态为 idle_down）：将它放入 SpriteRenderer 对象的 Animator 中，并调用 animator.Play("walk_left")。已在 Unity 6 上测试。
"web"	<name>.json（图集）+ <name>_demo.html	TexturePacker 风格的（hash）图集，包含 animations：Phaser 3 使用 this.load.atlas(...)，PixiJS 使用 Assets.load(...)。已在 Phaser 3.80 和 PixiJS 8.5 上测试。演示中可使用方向键／WASD、Shift 和 Space 操控角色——请从本地服务打开（python -m http.server）。
"site"	<name>_site.json	将其粘贴到生成器网站的 Import from Clipboard (JSON) 按钮中，即可继续在那里编辑。

素材致谢

每次生成都会写入 <name>_credits.txt 和 <name>_credits.csv，其中包含仅限实际使用素材的作者、许可证和链接，以及可直接粘贴到游戏制作人员名单画面中的文本（credits.statement）。精灵属于 LPC 素材（CC-BY-SA 3.0、OGA-BY 3.0、GPL 3.0 等）——如果你要发行游戏，请注明这些素材的来源。

限制

• 某些类型完全没有完整版本（斗篷、背包、连衣裙、裙子）。启用 prefer_complete 后，它们会保持原样，animation_check 也会对此进行说明。
• LPC 肌肉型、儿童型和孕妇型身体缺少一些动画（例如，肌肉型没有 shoot 或 climb）；animation_check 会在 body_missing 中报告这些动画。
• 不支持 Godot 3（仅支持 Godot 4）。已在 Unity 6 上测试 Unity。
• 在本地运行（stdio）；不适用于只接受远程服务的客户端。

开发

git clone https://github.com/kyuza1/lpc-character-mcp.git
cd lpc-character-mcp
pip install -e ".[dev]"
python -m pytest -q

克隆后，定义、缓存和输出都位于克隆目录中（lpc/、cache/、 output/）。每次推送时，以及每周一，都会在 Linux、Windows 和 macOS 上通过 GitHub Actions 运行测试（以检测官方 LPC 仓库中的更改）。创建 GitHub 版本发布后，会自动将版本发布到 PyPI。请参阅 CHANGELOG.md。

许可证

代码采用 MIT 许可证。下载的美术资源归 LPC 美术创作者所有，并遵循其 许可证（请参阅生成的署名文件）。