fvtt-mcp-artificer

一个专门面向 Foundry 的图像生成 Model Context Protocol 服务器，用于 D&D 桌面美术，由 Claude Code 驱动。它封装了本机上的无头 ComfyUI 实例，并暴露一组少量 Foundry 形态的工具，让 Claude 可以编写提示词、生成插画批次、通过实际查看结果来策选，并把入选结果交给其姊妹服务器 fvtt-mcp-molten5e 中的 Foundry 管线（upload-asset → set-actor-art / add-journal-image / 场景背景）。

整个闭环在目标硬件（RTX 5090）上足以进行对话式交互：6 张草稿批次约 10 秒完成，一张 2560×1600 成品渲染约 19 秒，而完整的 提示词 → 草稿 → 策选 → 成品 → 游戏内日志 循环已在 notes/m3-loop-proof.md 中端到端验证。

为什么采用这种形态

这不是通用的 ComfyUI 桥接器，这是硬性规定。工具使用 Foundry 的词汇——角色肖像、token、handout、场景背景——并且可以自由调整以适配 Foundry 工作。它与 fvtt-mcp-molten5e 保持分离：那个服务器只负责 Foundry 内容创作，绝不能与图像生成耦合。本服务器从不与 Foundry 桥接器通信；两者之间的交接是磁盘上的文件加上 molten5e 的上传工具。

与家族其他项目相同的核心理念：工具负责执行，技能负责决策。 正确性（工作流执行、尺寸、放大管线、文件约定）存在于这里经过测试的工具中；判断力（提示词功力、策选品味、哪个 actor 或 journal 获得美术、家室风格）则属于稍后的 illustration-builder 技能。

Claude ──MCP──> fvtt-mcp-artificer ──HTTP──> ComfyUI (headless, local)
                      │
                      └── pinned workflow JSONs (draft / final / final-refine / upscale)

ComfyUI 以 API 模式无头运行；本服务器提交 workflows/ 下的固定工作流 JSON——绝不提交自由形式的工作流图——并通过节点 ID 替换 prompt/seed/batch/preset（以 class-type 漂移断言加以保护）。工具返回绝对文件路径；Claude 直接读取 PNG 进行策选。

Related MCP server: FoundryVTT MCP Server

用途预设，而非原始尺寸

generate-image 接受 kind，而非宽高：

分辨率管线（锁定）： 绝不在输出尺寸下生成——构图超过约 1.5 MP 后会退化。在预设的原始分辨率下生成，使用 4x-UltraSharp 模型放大 ×4，lanczos 降采样到成品尺寸，全部在一个固定工作流图中完成。

模型

• FLUX.1-dev fp8（Comfy-Org all-in-one）——最终品质的渲染，约 15–19 秒完成。

• FLUX.2-klein 4B（Apache 2.0）——草稿模型：4 步，约 1–2 秒/张，批量 6–8 张，挑选后用 dev 重新渲染。

• 4x-UltraSharp——流程尾部的模型放大器。

工具

工具与固定工作流图之间的替换契约记录在 workflows/README.md 中。

要求

• Windows + NVIDIA GPU。 在 RTX 5090 上开发并验证（Blackwell 需要 CUDA 12.8+ 的 PyTorch；当前 ComfyUI 便携版已附带该版本）。

• ComfyUI（独立便携版，v0.34+）以无头模式运行——启动约定见 scripts/launch-comfyui.ps1（API 模式监听 127.0.0.1:8188，固定 --output-directory）。

• ComfyUI models/ 目录中的模型文件（约 33 GB，全部无需门控）：checkpoints/flux1-dev-fp8.safetensors、diffusion_models/flux-2-klein-4b.safetensors、text_encoders/qwen_3_4b.safetensors、vae/flux2-vae.safetensors、upscale_models/4x-UltraSharp.safetensors。artificer-status 会报告缺失项。

• Node.js 22+ 用于运行 MCP 服务器本身。

构建

npm install
npm run build

测试：npm test（离线单元测试套件；固定工作流 JSON 作为测试夹具）。实时套件——真实 ComfyUI、真实渲染——由 npm run test:integration 门控。质量关卡：npm run typecheck、npm run check（biome）、npm run knip。

接入 Claude Code

家族惯例是在用户作用域注册服务器（新增 MCP 工具后必须重启 Claude Code）。可以使用 CLI：

claude mcp add -s user artificer -- node D:/path/to/fvtt-mcp-artificer/dist/index.js

或者将 .mcp.json.example 复制成 Claude Code 读取的 .mcp.json（或合并到 ~/.claude.json 的 mcpServers），路径使用绝对路径。在 Windows 上，如果 Node 不在 PATH 中，请将 command 指向完整的 node.exe 路径。

配置

将 .env.example 复制为 .env（已被 gitignore）：

• COMFY_URL——无头实例地址（默认 http://127.0.0.1:8188）。

• COMFY_OUTPUT_DIR——必须与 ComfyUI 启动时使用的 --output-directory 一致；服务器直接从该路径读取生成的 PNG。

• ARTIFICER_TIMEOUT_MS——每个任务的等待上限（默认 300000）。

许可证

MIT License——详见 LICENSE。