IlluGen

IlluGen MCP

让你的 AI Agent 构建、编辑和渲染 JangaFX IlluGen 节点图。

用简单的话描述纹理、VFX 翻页动画或程序化蒙版：你的 Agent 会创建 .illugen 项目、连接节点、检查并使用你自己的 IlluGen进行渲染。无需点击，也无需打开窗口。

快速开始 · 功能介绍 · 工具 · 工作原理 · 常见问题

_{真实的工具调用和耗时，真实的 IlluGen 渲染。使用 examples/demo_scenes.py 复现。}

快速开始

1. 要求

• 安装并激活了 IlluGen 1.2.x 的 Windows 系统（需要有效的 JangaFX 许可证：本项目不包含也不替代 IlluGen）。
• Python 3.10+。推荐使用 uv（无需手动安装）。

2. 添加到 Agent

Claude Desktop：一键安装

从最新版本下载 illugen-mcp-<version>.mcpb 并打开（或将其拖入 Claude Desktop › Settings › Extensions）。需要将 uv 添加到 PATH。如果 IlluGen 安装在其他位置，请在扩展设置中设置其路径。

Claude Code

claude mcp add illugen -s user -- uvx --from git+https://github.com/dokaNc/illugen-mcp illugen-mcp

Claude Desktop、Cursor、Windsurf、VS Code、Gemini CLI……（任何 MCP 客户端）：将以下内容添加到客户端的 MCP 配置中（claude_desktop_config.json、.cursor/mcp.json 等）：

{
  "mcpServers": {
    "illugen": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dokaNc/illugen-mcp", "illugen-mcp"]
    }
  }
}

pip install git+https://github.com/dokaNc/illugen-mcp
claude mcp add illugen -s user -- illugen-mcp

claude mcp add illugen -s user -e ILLUGEN_EXE="D:\Apps\IlluGen\IlluGen.exe" -- uvx --from git+https://github.com/dokaNc/illugen-mcp illugen-mcp

"env": { "ILLUGEN_EXE": "D:\\Apps\\IlluGen\\IlluGen.exe" }

3. 提出请求

重启 Agent，然后试试：

Check that IlluGen is reachable with illugen_status, then build me a tileable stone mask
and render it to C:\Users\me\Desktop\stone.

功能介绍

• 从头构建节点图：涵盖 IlluGen 1.2.1 的全部 157 种节点类型（Grayscale、Color、UV、Geometry、Islands、Utils、信号、导入/导出等），包含真实默认值、所有合法枚举值、取值范围、单位和说明。
• 安全连接节点：在 IlluGen 读取文件之前检查引脚类型（Grayscale、Color、UV、Normal、Islands、GeometryBuffer 等）；类型不匹配时，错误信息会建议使用转换节点。
• 处理普通参数之外的内容：曲线、颜色渐变、样条线／晶格控制点、带公开参数的子图、信号调制（Oscillator → Scale 等）、带框分组和备注。
• 从随附示例开始：复制 IlluGen 的 120 多个示例预设中的任意一个并进行修改。
• 真实验证：project_validate(engine=true) 会在 IlluGen 中加载项目、运行试导出，并报告被丢弃的节点或连接、日志错误，以及任何警告对话框的截图。
• 渲染：project_render 会对每个导出节点运行 File › Export（PNG、JPG、TGA、EXR、HDR、RAW、R16、R8、OBJ、FBX、翻页动画序列等），返回生成的文件和内嵌预览。
• 不打扰你的工作：渲染使用独立且不可见的 IlluGen 实例。你已打开的 IlluGen 会继续运行，不受影响；鼠标和键盘焦点也不会被抢占。

工具

典型流程：project_new → node_add … → link_add … → project_validate(engine=true) → project_render。

展示

熔岩（Voronoi 噪声 → 色阶 → 色彩渐变 → 辉光）、焦散（多边形分形 → 焦散 → 渐变）和能量网（Voronoi 边缘 → 渐变 → 辉光）：每个由 4 到 5 个节点构成，由 Agent 在约 15 秒内创建并渲染。 准确的节点图见 examples/demo_scenes.py。

示例提示词

Open the "brick_wall" preset, make it 2048x2048, make the bricks darker and render it.

Create a 64-frame looping smoke flipbook (8x8 atlas), export as TGA to D:\fx\smoke.

Build a subgraph "edge wear" (noise + levels + blur) with its seed exposed, use it twice with
different seeds and blend the results.

Explain what every node in C:\projects\lava.illugen does and suggest how to make it less noisy.

工作原理

• 直接编辑文件。 .illugen 项目以无损方式读写（未经更改保存的文件与原文件逐字节相同），因此离线编辑即时且安全。节点定义来自与 IlluGen 1.2.1 匹配的内置表。
• 使用 IlluGen 本身进行渲染。 服务会在自己的文件夹中启动一个私有的 IlluGen 副本，该副本不会显示在屏幕或任务栏上；服务会加载项目并触发 IlluGen 自带的导出快捷键。服务会通过 IlluGen 日志跟踪进度，并在完成后关闭它。不会影响你的设置和已打开的 IlluGen 窗口。
• 错误会返回给 Agent。 导出失败和加载警告会被检测到，并连同截图一起返回，以便 Agent 自行修复节点图。

服务写入的文件：项目和渲染结果会保存到你指定的位置，此外还会在 %LOCALAPPDATA%\illugen-mcp 中创建临时文件夹（可通过 ILLUGEN_MCP_HOME 覆盖）。

更新 IlluGen

内置节点表适用于 IlluGen 1.2.1。更新 IlluGen 后，从你的安装目录重新构建目录（需要几分钟，IlluGen 会在后台运行）：

uvx --from git+https://github.com/dokaNc/illugen-mcp python -m illugen_mcp.build_catalog

新目录会存储在 %LOCALAPPDATA%\illugen-mcp\data 中，并优先于内置目录。

常见问题

它能在 macOS 或 Linux 上运行吗？ 暂时不能：渲染需要使用 IlluGen 的 Windows 版本。离线编辑（project_*、node_*、link_*）完全由 Python 实现，应该也能在其他系统上运行，但目前只在 Windows 上经过测试。

它会影响我已打开的 IlluGen 吗？ 不会。每次渲染都会在独立的私有实例中运行，并使用各自的配置和恢复文件。

IlluGen did not finish starting 手动启动一次 IlluGen（激活许可证并关闭欢迎界面），使用 illugen_status 检查路径，并查看 %LOCALAPPDATA%\JangaFX\illugen\logs 中最新的日志。如果问题仍然存在，请附上该日志提交问题。

渲染提示 “Nodes failed to export”。 通常是图表问题（引脚类型不匹配、输入未连接）。随错误返回的截图会显示处于警告状态的节点；describe_node_type 会列出预期的引脚类型。

我更改了 IlluGen 的键盘快捷键。 支持：服务会从 IlluGen 的 config.ini 中读取快捷键。

开发

git clone https://github.com/dokaNc/illugen-mcp
cd illugen-mcp
pip install -e ".[dev]"
pytest                      # tests needing IlluGen are skipped automatically if it isn't installed
ruff check .

欢迎贡献：请参阅 CONTRIBUTING.md。

免责声明

IlluGen MCP 是一个独立的社区项目，与 JangaFX 无关联、未获其认可，也不受其支持。IlluGen 和 JangaFX 是其各自所有者的商标。你需要自行拥有 IlluGen 的授权副本；本项目既不包含也不会修改 IlluGen。

许可证

MIT