texel-mcp

Texel

Texel 是一种格式和一套工具链，可通过代码制作 Minecraft 纹理。纹理采用 JSON 规范：包含一个调色板，以及一个有序的绘制操作列表，操作针对模型中以名称标识的部件和面（head.front、rightArm.sides@overlay）。编译器会将规范转换为游戏读取的 PNG，每次生成的字节都完全相同；审查结果则会以 JSON 路径、修复提示、艺术评分和像素画建议的形式指出问题。这些工具专为 AI Agent 打造：包括 MCP 服务、命令行工具和 Agent Skill，且还打包为 Claude Code 插件。

它涵盖玩家皮肤（经典和纤细款），并通过布局支持另外 68 种纹理，包含 Java Edition 1.21 中的所有纹理布局：57 种生物纹理（僵尸、骷髅、苦力怕、马、羊驼、狐狸、蜜蜂、美西螈、灾厄村民、监守者、傀儡等）、盔甲层、带鞘翅的披风、物品、带顶部和侧面文件的方块（原木、草、熔炉）、植物、GUI 精灵图、粒子和绘画。纹理可以制作动画和发光效果；一组规范可构建资源包，Texel 也能对其进行检查。

Texel 是开源项目（MIT），目前仍在开发中，版本为 0.9.0。格式采用版本标记（version: 1），但次要版本之间仍可能发生变化。请将所有内容视为 Beta 版。网站 texel.dev.br 基于这套工具链构建。

上图是工具针对该规范返回的审查图。它是 wizard 示例，但去掉了 $schema、description、author 和 tags 字段，以及各图层的 note 注释；这些内容不会改变像素（两者编译出的 PNG 完全相同）：

{
  "version": 1,
  "name": "Star Wizard",
  "model": "classic",
  "palette": {
    "skin": "#e0ac7e", "robe": "#2f4fb0", "gold": "#e8c34a", "beard": "#dcdcdc",
    "eyes": "#3a6fd9", "boots": "#4a3324", "star": "#fff1a8"
  },
  "layers": [
    { "op": "material", "target": "all", "color": "skin", "kind": "skin" },
    { "op": "material", "target": "body+arms", "color": "robe", "kind": "fabric" },
    { "op": "material", "target": "legs", "color": "robe~-1", "kind": "fabric" },
    { "op": "material", "target": "arms", "region": "hands", "color": "skin", "kind": "skin" },
    { "op": "rect", "target": "arms.sides", "region": "cuffs", "color": "gold" },
    { "op": "material", "target": "legs", "region": "boots", "color": "boots", "kind": "leather" },
    { "op": "face", "id": "face", "skin": "skin", "eyes": "eyes", "brows": "beard", "beard": "full", "beardColor": "beard", "mouth": "smile" },
    { "op": "hair", "id": "hair", "color": "beard", "style": "long", "fringe": "parted" },
    { "op": "lighting" },
    { "op": "rect", "target": "body.sides", "region": "belt", "color": "gold" },
    { "op": "points", "target": "body.front", "points": [[3, 8], [4, 8]], "color": "gold~-2" },
    { "op": "points", "target": "body.front+back", "points": [[1, 2], [6, 4], [2, 6], [5, 10]], "color": "star" },
    { "op": "points", "target": "legs.front", "points": [[1, 1], [2, 4]], "color": "star" },
    { "op": "material", "id": "hood", "target": "body.back@overlay", "y": 0, "h": 3, "color": "robe~-1", "kind": "fabric" },
    { "op": "rect", "target": "body.front@overlay", "region": "collar", "color": "gold~-1" },
    { "op": "rect", "target": "arms.sides@overlay", "region": "cuffs", "color": "gold~1" }
  ]
}

它编译生成的 64 × 64 纹理是 docs/images/wizard.png。

安装

MCP 服务和 CLI 需要 Node 20 或更高版本。

Claude Code 插件。 此仓库是一个插件市场。插件会从单个打包文件启动 MCP 服务（无需 npm install），并添加 minecraft-skin-design 技能。文件会写入项目目录。

/plugin marketplace add Brunovncs/texel-mcp
/plugin install texel@texel

或者使用此提示词。 将其粘贴到你想搭配 Texel 使用的 Agent 中（Claude Code、Codex、Cursor、Claude Desktop 或任何支持 MCP 的客户端），它会为你安装 MCP 服务：

Install the Texel MCP server for me (https://github.com/Brunovncs/texel-mcp).

1. Check that Node.js 20 or later is installed (`node --version`). If it is not, stop and tell me.
2. Create the folder ~/.texel (%USERPROFILE%\.texel on Windows) and download the single-file
   server into it:
   https://raw.githubusercontent.com/Brunovncs/texel-mcp/main/plugin/server/texel-mcp.mjs
3. Check that it runs: `node <path to texel-mcp.mjs> --version` must print a version number.
4. Ask me which folder the skins should be saved in. If I don't care, skip the --workspace part
   below; files then go to the directory the client starts the server in.
5. Register it as an MCP server named "texel" in the client you are running in, using absolute
   paths:
   - Claude Code: claude mcp add --scope user texel -- node <path to texel-mcp.mjs> --workspace <folder>
   - Any other client: add this to its MCP configuration, keeping the servers already there:
     {"mcpServers": {"texel": {"command": "node",
       "args": ["<path to texel-mcp.mjs>", "--workspace", "<folder>"]}}}
6. Tell me what you changed and whether I need to restart the client. Once the tools are
   available, call texel_get_example and then texel_render on that example to confirm they work.

任何 MCP 客户端。 该软件包是 npm 上的 texel-mcp。此配置适用于 Claude Desktop、Cursor、VS Code 以及其他读取常见 mcpServers 格式的客户端：

{
  "mcpServers": {
    "texel": {
      "command": "npx",
      "args": ["-y", "texel-mcp", "--workspace", "/absolute/path/skins"]
    }
  }
}

在 Claude Code 中，相同操作为 claude mcp add texel -- npx -y texel-mcp。若要改用本地构建（参见构建和测试），请让客户端指向该文件："command": "node", "args": ["/absolute/path/texel-mcp/dist/texel-mcp.mjs", "--workspace", "/absolute/path/skins"]。plugin/server/texel-mcp.mjs 是依赖已打包的相同服务，可通过普通的 node 命令从任意位置运行。

CLI。 可运行 npx -y -p texel-mcp texel-cli build skin.json -o skin.png --sheet sheet.png，也可在构建目录中运行 node dist/texel.mjs ...。它没有依赖项。--help 会列出以下命令：build、review、patch、sheet、palette、family、import、diff、pack、check-pack、share、pull、live、format、layouts 和 init。退出代码：0 表示完成，1 表示规范、系列或资源包有错误，2 表示用法错误。

所有写入操作都在单个工作区目录中进行：--workspace、$TEXEL_WORKSPACE，或服务启动时所在的目录。解析后位于工作区之外的路径会被拒绝。docs/install.md 介绍了详细信息，包括如何手动安装技能。

规范

规范包含一个 palette（颜色名称，以及派生色调，例如 robe~-1，即更深、更冷一个色阶）、可选的 legend（每种颜色对应一个字符，用于像素行）和按顺序执行的 layers。每个图层都是 18 种操作之一。其中 12 种是基础绘制操作（fill、rect、clear、pixels、points、line、gradient、pattern、noise、shade、copy、mirror），一种用于修正对称性（symmetrize），另外五种属于更高级别：material（布料、皮革、金属、毛皮、针织等表面）、face、hair、lighting 和 bevel（原版 GUI 风格的凸起和凹陷边框）。任何标记为 "emissive": true 的操作也会绘制纹理的发光贴图 <name>_eyes.png。

图层的 target 是一个选择器，可指定部位、面和图层，例如 head.front、legs.sides、body.front+back@overlay 或 arms.top@both。坐标相对于每个面：从模型外部观察时，(0, 0) 是该面的左上角像素，绘制内容会裁剪到该面范围内。匹配多个面的选择器会对每个面分别执行一次操作，因此 { "op": "rect", "target": "legs.sides", "y": -2, "color": "boots" } 会沿着双腿的整个周围绘制最下面两行。命名区域（belt、cuffs、boots、hands、collar）可代替行号。

修改通过图层 id 应用补丁（{ "patch": [{ "do": "update", "id": "hair", "set": { "style": "ponytail" } }] }），因此修正时只会涉及其中指定的图层。同样的补丁也用于制作动画帧（"animation": { "frames": [{}, { "patch": [...] }] } 会编译成一个条带及其 .png.mcmeta；粒子则会为每帧生成一个文件）和系列成员：一个系列会将基础规范扩展为多个变体或轴的矩阵（队伍、等级、派系），方法是替换调色板、启用或禁用图层、按 id 修补基础图层并追加图层，因此系列成员可以是不同角色，而不仅仅是重新着色。现有 PNG 可以导入为可编辑规范，每个已绘制的面对应一个图层；import --pixelize 则会先将任意图片（概念设计图、高清皮肤）转换为与布局尺寸一致的纹理。

asset 指定纹理在资源包中的位置（生物默认使用其替换的原版文件）。pack 根据规范和系列构建资源包，并生成适用于 Minecraft 版本（1.21 至 1.21.11）的 pack.mcmeta；还可按需生成新物品或方块所需的模型、方块状态和物品定义。check-pack 会检查任意资源包的格式和版本、文件名、PNG、.mcmeta 动画和 GUI 缩放、实体纹理尺寸、缺失模型或纹理的引用，以及未使用的纹理。

完整参考文档见 docs/spec.md，JSON Schema 见 schema/skinspec.v1.json。docs/protocol.md 介绍了预期 Agent 遵循的工作流程（简述、起草、渲染、审核、修补、交付），docs/art-guide.md 介绍了如何让皮肤在 64 × 64 尺寸下呈现出良好效果。Agent 也可以通过 texel_read_docs 和 texel://docs/{page} 资源访问这些页面，并通过 texel_get_example 获取 examples/ 中的 19 个示例。

审查结果

每次渲染都会附带一份审查报告。如果调色板名称和面名称中各有一个拼写错误，答案中相关部分如下：

{
  "ok": false,
  "score": 38,
  "issues": [
    { "level": "error", "code": "bad-color", "path": "$.layers[1].color",
      "message": "unknown color or palette key \"clth\"", "hint": "did you mean \"cloth\"?" },
    { "level": "error", "code": "bad-selector", "path": "$.layers[2].target",
      "message": "unknown face \"frnt\"", "hint": "did you mean \"front\"?" },
    { "level": "warning", "code": "blank-face", "path": "head.front",
      "message": "the face (head.front) uses fewer than 3 colors and will read as blank",
      "hint": "draw eyes, brows and a mouth with a \"pixels\" op on head.front" }
  ]
}

错误和警告会指出导致问题的 JSON 路径或面，大多数还会附上说明修复方法的提示。错误代码在各个版本中保持稳定，其含义列于 docs/spec.md（代码中的 ISSUE_CODES）；有一项测试会确保列表与源码实际能报告的内容一致。方块纹理还会测量平铺效果：每条边的接缝处，相比纹理自身相邻区域的复制接缝，显得有多突兀（stats.seams、tile-seam）。score（0 到 100）只衡量技术规范性：错误、底层中的空洞、空白面、平坦表面、颜色过少。审查中的 art 部分有独立分数，由七项测量指标组成：R2 到 R7（面部可读性、各部分之间的明度对比、从上方照射的光线、表面纹理、经过设计的背面、利用叠加层表现深度），以及颜色数量；每项都会说明测量内容并给出提示。art.advice 会指出纹理中发现的经典像素艺术错误（枕头阴影、只会变暗的阴影、静态噪点、在立方体拐角处中断的色带），并标明这些问题出现在哪些面；它不会改变任何分数。next 列表会按优先级排列要修复的问题。

纹理是否符合需求（R1）从不进行测量。MCP 工具会返回审查图表（正面、背面、两侧和纹理，如上所示），让具备视觉能力的 Agent 自行判断；对于不具备视觉能力的模型，则会返回文本渲染结果。图表会补充纹理所需的内容：以 3 × 3 平铺并呈现为 3D 的方块、按游戏缩放方式调整大小的 GUI 精灵、每一帧动画，以及黑底上的发光像素。在支持 MCP Apps 的客户端中，texel_render 还会打开交互式 3D 预览。

工具

MCP 服务提供 16 个工具、用于文档、示例和架构的资源、ui://texel/viewer MCP App，以及 5 个提示词（design_skin、design_texture、continue_skin、design_family、critique_skin）。

工具	功能
texel_render	编译并审查规范（内联提供，或使用工作区 file）；返回审查报告、图表图像，以及可选的部分区域特写和纹理。
texel_patch	按图层 ID 应用补丁并渲染结果。提供工作区 file 时，会直接编辑文件并仅返回审查报告，因此每次迭代都无需重新发送规范。
texel_validate	仅返回错误和警告，不返回图像。
texel_save	将纹理在游戏中的所有文件（方块部件、动画条和 .png.mcmeta、粒子帧、_eyes）、.skin.json 源文件，以及可选的图表写入工作区。
texel_live	启动实时会话：在 127.0.0.1 上提供一个页面，实时显示每次渲染结果（texel.dev.br 工作室也可以跟踪该页面，以便编辑）。
texel_share	将规范存储到 texel.dev.br 并返回短链接；离线时则回退为较长的自包含链接。
texel_pull	加载共享链接对应的规范，以便继续编辑。
texel_render_family	展开一个系列并返回阵容图像及每个成员的分数。
texel_save_family	将系列中的每个成员以及 lineup.png 写入文件。
texel_import_png	将现有纹理 PNG 转换为可编辑的规范；使用 pixelize 时，也可转换任意图片。
texel_palette	将参考图像中的主要颜色提取为调色板和图例，并为每种颜色指定角色。
texel_pack	根据规范、系列及其所在文件夹构建资源包（.zip 或文件夹），并对其进行检查。
texel_check_pack	检查任意资源包，并针对每个问题提供文件、JSON 路径和修复提示。
texel_diff	显示两个规范之间有哪些面和像素不同，并提供遮罩图像。
texel_get_example	获取一个捆绑的示例规范，或示例系列。
texel_read_docs	以 Markdown 格式获取文档页面。

工作原理

绘制 Minecraft 纹理的难点不在于绘画，而在于映射。皮肤的右臂由分散在 64 × 64 图集上的 6 个矩形组成，其中一些是镜像的；叠加层则是在其他位置的另一组矩形；猪的身体侧躺着，因此它的“顶部”是动物的背部；每种生物都有自己的图集。直接在图集上写入像素的 Agent 必须把这张映射记在脑中，而且会出错，却无法察觉。

在 Texel 中，映射由编译器负责。每种布局都是数据：各部件的盒体尺寸和 UV 原点、哪些部件是镜像的、哪些部件是旋转的，以及哪些部件被透明区域裁掉。Agent 使用面自身的坐标访问 rightArm.front，编译器则会将每个像素映射到图集中的对应位置。审查、图集视图、3D 预览、import 和 diff 都会通过同一映射读取图集。这样一来，Agent 不擅长的空间任务就变成了它擅长的符号任务：命名部件、选择颜色、排列图层，以及根据指向 JSON 某一行的错误信息采取行动。

编译结果是确定性的。唯一的随机性来自 noise 和 material，而二者都使用带种子的生成器（种子默认为图层的位置），因此相同的规范会生成逐字节完全相同的 PNG。这样，规范就可以通过差异进行审查、纳入版本控制，并在构建中重新生成。

每种生物的布局都经过了对照反编译后的 Java 模型代码（texOffs 和 addBox）的检查，也通过了对 1.21.1、1.21.5 和 1.21.11 的原版纹理进行验证：原版文件中的每个不透明像素都必须落在某个面上，并且视图必须能显示该生物。布局遗漏的少数像素会列在对应的说明中（彩蛋、零散像素、在 1.21.5 中移到独立文件的鞍具）。

代码位于 src/core（编译器、布局、审查、视图、PNG 和 zip 编码与解码、资源包；无依赖且不使用 DOM）、src/mcp（服务端和 MCP App 查看器）、src/cli 和 src/live（实时会话和更新检查）。MCP 服务依赖 @modelcontextprotocol/server 和 zod；CLI 没有依赖。

性能测量

在 AMD Ryzen 5 7600（12 线程）、Windows 11、Node 22.13.1 上使用 npm run measure （scripts/measure.ts）进行测量：19 个内置示例中的每一个都在同一进程中编译了 210 次， 前 10 次作为预热，表格显示其余 200 次的中位数。“编译 + PNG”指将规格文本转换为编码后的 PNG。“完整渲染” 指 texel_render 的计算内容：编译、包含美术检查和建议的完整审查、审查表以及两张 PNG。规格大小为示例 文件经 JSON.stringify 压缩后的大小；PNG 按工具所用方式以 zlib 级别 9 编码。动画示例会编译每一帧。

示例	布局	纹理	规格（字节）	PNG（字节）	编译 + PNG	完整渲染
explorer	玩家	64 × 64	2 958	1 246	1.45 ms	19.75 ms
knight	玩家	64 × 64	3 006	1 090	1.47 ms	16.13 ms
robot	玩家	64 × 64	2 537	1 473	2.59 ms	16.01 ms
astronaut	玩家（纤细型）	64 × 64	3 134	865	1.29 ms	18.41 ms
wizard	玩家	64 × 64	1 908	2 968	3.22 ms	21.62 ms
cozy	玩家（纤细型）	64 × 64	1 639	2 949	3.07 ms	20.74 ms
winged-pig	玩家	64 × 64	3 272	2 467	3.40 ms	23.09 ms
miner-zombie	僵尸	64 × 64	1 518	2 198	2.02 ms	17.23 ms
creeper	苦力怕	64 × 32	1 156	1 058	0.98 ms	11.45 ms
mud-pig	猪	64 × 64	1 970	1 477	2.01 ms	16.60 ms
bronze-armor	人形生物（盔甲）	64 × 32	1 605	1 719	1.66 ms	13.38 ms
banner-cape	披风	64 × 32	1 236	1 300	1.32 ms	14.35 ms
ember-blade	物品	16 × 16	1 058	160	0.10 ms	4.21 ms
zebra	马	64 × 64	1 605	2 302	4.30 ms	24.30 ms
sky-evoker	灾厄村民（带 _eyes）	64 × 64	1 237	3 126	3.84 ms	28.58 ms
ash-log	方块柱	32 × 16	1 255	666	0.47 ms	11.49 ms
magma-pulse	方块，4 帧	16 × 16	1 275	472	1.12 ms	11.00 ms
stone-button	图形界面	200 × 20	735	1 569	2.87 ms	17.76 ms
spark	粒子，4 帧	8 × 8	958	110	0.10 ms	1.33 ms

所有示例的编译和编码耗时中位数为 1.66 ms，完整渲染耗时中位数为 16.6 ms。 不包括 MCP 服务的启动时间以及将图像表传输到客户端的时间。

规格文件并不比它生成的图像小：压缩后的规格大小中位数是其 PNG 大小的 1.33 倍， 范围为 735 至 3 272 字节。按每个令牌大约 4 字节粗略估算，每份规格约为 180 至 820 个令牌；这未经分词器验证，而且 JSON 通常每字节对应的令牌数多于散文。该格式的目的并非追求体积小。 PNG 是 Agent 无法手动编写或编辑的压缩二进制文件，而规格中的每一行都是可供阅读、修改和审查的决策。

通过三种方式检查了确定性。在单个进程中，每个示例的 210 次运行都生成了字节完全相同的 PNG（每个示例各有一个唯一的 SHA-256）。 测试会保留每个示例纹理的哈希值，因此如果现有规格的渲染结果发生变化，测试套件就会失败。对于 0.8.0， 从打包的 npm tarball 构建并安装的 CLI 为对比的四个示例（explorer、knight、creeper、ember-blade）生成了相同的哈希值。 以上测试均在一台 Windows 机器上运行；CI 工作流会在 Linux 上运行相同的测试套件，但尚未直接比较不同操作系统上的字节是否相同。

版本 0.9.0 的其他统计数据：19 个示例规格和 1 个示例系列（6 个成员）、69 种布局及 74 个别名（husk、stray、elytra、mooshroom、vindicator、elder_guardian、log 等）、18 个操作、116 个问题代码，以及分布在 14 个文件中的 180 项测试。

限制

• 仅支持 Java Edition。不支持 Bedrock 皮肤和 Bedrock 几何模型。
• 仅支持原版箱体模型。没有自定义 3D 模型或几何模型，也不支持高清皮肤：生物和皮肤纹理采用原版尺寸（物品、方块和植物可以是高清纹理）。
• 布局遵循 Java Edition 1.21 的模型代码：UV 映射已对照反编译代码以及 1.21.1、1.21.5 和 1.21.11 的原版纹理进行检查。本项目尚未在游戏中加载过使用这些布局制作的纹理；检查依据是代码和原版文件。尚无法绘制没有布局的生物（鱼、嗅探兽、微风人、嘎吱怪等）和鞍具。
• 视图和 3D 预览仅模拟 90° 转向。倾斜的部件（例如疣猪兽的头部、马的脖子或炽足兽的鬃毛）会以未倾斜的状态绘制，或不显示在视图中（各布局的说明会注明具体情况）。
• check-pack 知道 1.21 到 1.21.11 的资源包格式。它会检查结构和引用，而不会检查模型或纹理在游戏中的外观，也不会检查数据包。
• 美术评分和制作建议是启发式评估。它们尚未经过人工判断验证，也无法说明纹理是否符合需求。纹理看起来有多好，主要取决于编写规格的 Agent。
• texel_share、texel_pull 和短链接需要 texel.dev.br：分享链接存储在该站点。较长的 #z= 链接无需站点存储即可使用。实时会话则不行：本地服务会提供自己的页面，只有在编辑会话时才需要该站点的工作室。TEXEL_SITE 可将所有这些指向其他源站。
• CLI 和服务每天会向 texel.dev.br 请求一次 version.json，以便告知 Agent 是否有新版本。该请求最多等待 1.5 s，不携带任何用户或规格相关数据；设置 TEXEL_NO_UPDATE_CHECK=1 或 CI 时会跳过请求。

构建和测试

需要 Node 20 或更高版本。

npm install
npm run typecheck        # tsc --noEmit
npm test                 # vitest: 180 tests, including spawned CLI and MCP server bundles
npm run build            # dist/texel-mcp.mjs and dist/texel.mjs (the npm package)
npm run build:plugin     # plugin/server/texel-mcp.mjs and its THIRD_PARTY_NOTICES.md
npm run measure          # the numbers in Measurements

npm 构建会将 MCP SDK 和 zod 保留为依赖项。插件构建会将它们打包到一个文件中，因为 Claude Code 插件没有安装步骤；该文件会提交到仓库，如果它与源代码不再一致，CI 就会失败。文档、示例、架构和查看器都会嵌入这两种构建产物中。构建时的 SITE_URL 会更改构建产物和文档中内置的站点源站。

同时更新 package.json、plugin/.claude-plugin/plugin.json 中的版本以及技能的 metadata.version，并为其添加 CHANGELOG.md 章节；有测试会检查这两项。

许可证

MIT，详见 LICENSE。插件的单文件服务打包了 MCP TypeScript SDK（Apache-2.0，部分内容采用 MIT 许可证）和 zod（MIT）；它们的许可证见 plugin/server/THIRD_PARTY_NOTICES.md。

这不是 Minecraft 官方产品。未经 Mojang 或 Microsoft 批准，也与它们无关。