一个专门面向 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，而非宽高：
kind | 生成分辨率 | 成品分辨率 |
| 1536×960 | 2560×1600 |
| 1024×1280 | 2048×2560 |
| 1024×1024 | 2048×2048 |
分辨率管线（锁定）： 绝不在输出尺寸下生成——构图超过约 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——流程尾部的模型放大器。
工具 | 作用 |
| 接受 |
| 将现有图像（通常是未能直接通过策选的草稿）经过放大流程尾部处理到其 kind 对应的成品分辨率。 |
| 健康检查：ComfyUI 可达性/版本、显存、队列深度、固定工作流完整性、所需模型是否存在。 |
工具与固定工作流图之间的替换契约记录在 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。
家族惯例是在用户作用域注册服务器（新增 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。
Health check: API key present, which image models the key can reach, the output directory, and estimated session spend by tier. Call this first on a cold start.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It effectively discloses that this is an informational read of several system states and gives useful specifics. However, it does not describe the return format, failure behavior, or whether the call itself has any side effects or costs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences. The first packs the full scope of the health check into a comma-separated list, and the second delivers the call guidance. No filler words or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless health check with no annotations and no output schema, the description is nearly sufficient. It states what is checked and when to call it, which is enough to select and invoke the tool. The only gap is that it doesn't explicitly describe the shape of the returned status report, but that is minor for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so there is no parameter meaning to convey. The description adds nothing about parameters because none exist; the baseline of 4 for zero-parameter tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Health check') and enumerates the exact resources inspected: API key presence, image model reachability, output directory, and session spend. This clearly distinguishes it from the sibling image generation/editing tools without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to use the tool: 'Call this first on a cold start.' This gives clear usage context. It does not name alternatives or state when-not-to-use, but the distinct nature of the image-operation siblings makes the exclusion obvious enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Knock the background off a token image to real alpha and deliver it centred on a 512 square so Foundry scale 1.0 is right. Writes a magenta-composited *_preview.png beside it: READ THAT before trusting the edge. Returns coverage and residual-key numbers; a cut outside sane coverage falls back to the rembg AI matte automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Square canvas edge; default 512 (Foundry scale 1.0). 0 keeps the source canvas. | |
| trim | No | Tighten to the subject before fitting (default true); false letterboxes as-is. | |
| color | No | Chroma key colour: "green", "magenta", "blue", or #RRGGBB. Omit to sample the corners. | |
| erode | No | Shrink the matte N px to eat a fringe. | |
| method | No | auto (default): chroma if the plate is a flat key colour, with a rembg fallback when the cut fails verification. chroma: flat green/blue/magenta/solid plates, instant. rembg: AI matte for busy backgrounds, hair, and soft edges (first use downloads a ~176 MB model). | |
| output | No | Absolute output path (.png). Default: next to the source as <name>-cut.png. | |
| padPct | No | Transparent margin, % of the edge (4). | |
| keepShadow | No | chroma only: keep a cast shadow on the plate. | |
| sourceImage | Yes | Absolute path of the image to cut (PNG/JPEG/WebP). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does well: it discloses side-effect preview file creation, instructs the user to verify edges, mentions returned coverage/residual-key numbers, and reveals automatic fallback to rembg. It does not mention overwrite behavior or other filesystem side effects beyond the preview and output, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose and canvas behavior, preview verification warning, and output/fallback behavior. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no annotations and no output schema, the description is unusually complete: it covers processing, output artifact, verification workflow, fallback behavior, and key return values. The remaining gaps are the lack of exact 'sane coverage' thresholds and a precise response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline of 3 applies. The description reinforces the purpose of size and output but adds no extra parameter-level detail beyond what the input schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it removes the background from a token image and produces a transparent cutout centered on a 512-square canvas. This clearly distinguishes it from image generation, general editing, and status-checking siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied clearly through 'token image' and 'Foundry scale 1.0', and the method parameter guidance explains when to prefer chroma versus rembg. However, it never names alternatives or says when not to use this tool versus generate-image or edit-image.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing image with one instruction while keeping identity, pose, angle, and style. Flash for every kind (pro was no better at fixes and re-cropped once). Tokens get the chroma plate re-applied so they can be cut again. Returns the new file path, dimensions, and estimated spend.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Purpose preset. icon: 1:1 flash → 512 square. token: 1:1 flash, top-down full body on a chroma plate, cut to alpha on a 512 square (framing, plate, and cut are done for you). portrait: 3:4 at 2K. illustration: 16:9 at 4K → 2560×1600 (16:10 crop). Every kind defaults to flash; tier: "pro" is opt-in and needs confirmPro. | |
| slug | Yes | Kebab-cased into the filename: <kind>-<slug>-<id>.png. | |
| tier | No | Default flash (Nano Banana 2, ~7-15¢), never needs a confirm. "pro" (Nano Banana Pro, ~13-24¢, style-reference slots, stronger multi-figure scenes) needs confirmPro. | |
| confirmPro | No | Required true with tier: "pro". Offer pro to the owner as an option for portraits and illustrations ("pro is available for a bit extra"); never assume it. | |
| references | No | Optional extra references (attached after the source; indexes start at 2). | |
| instruction | Yes | The change, and only the change: "replace the greatsword with a war maul crackling with violet energy". For a flaw-fix pass, name every flaw precisely in one instruction ("the left peryton has four legs; give it two", "remove the second fireball") and end with "keep everything else identical". Everything else is kept by the tool's own wording. | |
| sourceImage | Yes | Absolute path of the image to edit (PNG/JPEG/WebP). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and meets it: it discloses that flash is the default for every kind, that pro offered no benefit for fixes and re-cropped, that token edits re-apply the chroma plate for future cutting, and that the response includes file path, dimensions, and estimated spend. These are meaningful behavioral details beyond what the input schema alone conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four information-dense sentences with no filler. The primary verb and scope are front-loaded, followed by tier behavior, the token-specific quirk, and return values. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 7 parameters, no annotations, and no output schema, the description covers the essential behavioral contract: return values, default tier behavior, the special token handling, and the 'keep everything else identical' philosophy. The schema covers parameter details, and the sibling context makes the tool's role clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters in detail. The description adds a little context around the instruction ('one instruction' and preserving attributes) but does not materially expand parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pairing ('Edit an existing image') and adds the key constraints: one instruction, preserving identity, pose, angle, and style. This clearly distinguishes edit-image from generate-image and cutout-image by establishing it operates on an existing image rather than creating or extracting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool applies: modifying an existing image while preserving its core attributes. Sibling names like generate-image imply the alternative of creating new images, but the description does not explicitly say 'use this instead of generate-image when the source already exists' or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate one Foundry art asset from a prompt via the Gemini image API. kind picks the model tier, aspect, size, framing text, and post-processing; the result is a finished PNG on disk. READ IT before showing anyone: count limbs per creature, check for duplicated spell effects or props, stray signatures, and reference faces on the wrong figure; obvious flaws are one edit-image call away. Every kind runs on flash by default; tier: "pro" refuses without confirmPro: true and states the cost. Returns the file path, dimensions, and estimated spend.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Purpose preset. icon: 1:1 flash → 512 square. token: 1:1 flash, top-down full body on a chroma plate, cut to alpha on a 512 square (framing, plate, and cut are done for you). portrait: 3:4 at 2K. illustration: 16:9 at 4K → 2560×1600 (16:10 crop). Every kind defaults to flash; tier: "pro" is opt-in and needs confirmPro. | |
| slug | Yes | Kebab-cased into the filename: <kind>-<slug>-<id>.png. | |
| tier | No | Default flash (Nano Banana 2, ~7-15¢), never needs a confirm. "pro" (Nano Banana Pro, ~13-24¢, style-reference slots, stronger multi-figure scenes) needs confirmPro. | |
| prompt | Yes | What a camera would see, in illustrator terms. Do not add framing or background text for icons and tokens; the preset appends it. | |
| confirmPro | No | Required true with tier: "pro". Offer pro to the owner as an option for portraits and illustrations ("pro is available for a bit extra"); never assume it. | |
| references | No | Reference images, attached in this order. Bind each in the prompt by its label or 1-based index ("Image 2 is Morgash"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and does so thoroughly: it discloses default and pro model tiers with cost ranges, that pro refuses unless confirmPro is true, that framing/plate/cut post-processing is applied automatically, and the return payload (path, dimensions, estimated spend). It even includes a quality-control caveat about inspecting for artifacts before sharing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact for a 6-parameter tool with no output schema and front-loads purpose plus the most consequential behavior: model tier, confirmPro refusal, and cost. Every sentence earns its place, including the post-generation checklist and return-value note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description explicitly states what the tool returns: file path, dimensions, and estimated spend. It covers cost behavior, confirmPro requirements, cross-tool routing to edit-image, and automatic post-processing, leaving the agent with the information needed to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents kind, slug, tier, prompt, confirmPro, and references in detail. The description adds a useful overview of what kind controls and the default-vs-pro behavior, but it does not materially exceed the parameter-level explanations already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: Generate a Foundry art asset from a prompt via the Gemini image API, and states the deliverable (finished PNG on disk). It also separates generation from the edit-image sibling by explicitly routing post-generation flaws to edit-image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use flash vs. pro tiers, when confirmPro is mandatory, and points flawed outputs to edit-image. It does not explicitly contrast generate-image with artificer-status or cutout-image, but the generation-vs-post-processing distinction is largely evident from the sibling names and the finished-PNG framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0cutout-imageedit-imagegenerate-image12 fields changedInput schema / properties / batchRemoved value: -{
- "default": 6,
- "description": "Draft mode only: images per batch.",
- "maximum": 8,
- "minimum": 1,
- "type": "integer"
-}Input schema / properties / confirmProAdded value: +{
+ "description": "Required true with tier: \"pro\". Offer pro to the owner as an option for portraits and illustrations (\"pro is available for a bit extra\"); never assume it.",
+ "type": "boolean"
+}Input schema / properties / denoiseRemoved value: -{
- "default": 0.7,
- "description": "Refine mode only. 0.7 (pinned by test) keeps the scene skeleton in dev style; ~0.55 clones composition but inherits the draft rendering style.",
- "maximum": 0.95,
- "minimum": 0.3,
- "type": "number"
-}Input schema / properties / kind / descriptionPrevious value: -"Purpose preset — fixes generation and output resolution. No raw dimensions."New value: +"Purpose preset. icon: 1:1 flash → 512 square. token: 1:1 flash, top-down full body on a chroma plate, cut to alpha on a 512 square (framing, plate, and cut are done for you). portrait: 3:4 at 2K. illustration: 16:9 at 4K → 2560×1600 (16:10 crop). Every kind defaults to flash; tier: \"pro\" is opt-in and needs confirmPro."Input schema / properties / kind / enumPrevious value: -[
- "handout",
- "scene-background",
- "portrait",
- "token"
-]New value: +[
+ "icon",
+ "token",
+ "portrait",
+ "illustration"
+]Input schema / properties / modeRemoved value: -{
- "default": "draft",
- "description": "draft: fast klein batch for curation. final: dev-quality render from the prompt alone, finished at output resolution. refine: dev img2img over sourceImage (a picked draft) — keeps its scene skeleton, re-renders in dev style, finished at output resolution.",
- "enum": [
- "draft",
- "final",
- "refine"
- ],
- "type": "string"
-}Input schema / properties / prompt / descriptionPrevious value: -"The full image prompt."New value: +"What a camera would see, in illustrator terms. Do not add framing or background text for icons and tokens; the preset appends it."Input schema / properties / referencesAdded value: +{
+ "description": "Reference images, attached in this order. Bind each in the prompt by its label or 1-based index (\"Image 2 is Morgash\").",
+ "items": {
+ "properties": {
+ "label": {
+ "description": "Short name used to bind the reference in the prompt, e.g. \"Morgash\".",
+ "type": "string"
+ },
+ "path": {
+ "description": "Absolute path of a PNG/JPEG on disk.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "description": "character: hold this face/figure (up to 4 on flash, 5 on pro). style: match palette, brushwork, light, camera angle; never copy the subject (works on both tiers in practice).",
+ "enum": [
+ "character",
+ "style"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "role"
+ ],
+ "type": "object"
+ },
+ "maxItems": 14,
+ "type": "array"
+}Input schema / properties / seedRemoved value: -{
- "description": "Fixed seed; random when omitted.",
- "minimum": 0,
- "type": "integer"
-}Input schema / properties / slug / descriptionPrevious value: -"Short kebab-case subject name used in output filenames, e.g. \"smugglers-cove\"."New value: +"Kebab-cased into the filename: <kind>-<slug>-<id>.png."Input schema / properties / sourceImageRemoved value: -{
- "description": "Refine mode only (required there): absolute path of the picked draft PNG.",
- "type": "string"
-}Input schema / properties / tierAdded value: +{
+ "description": "Default flash (Nano Banana 2, ~7-15¢), never needs a confirm. \"pro\" (Nano Banana Pro, ~13-24¢, style-reference slots, stronger multi-figure scenes) needs confirmPro.",
+ "enum": [
+ "flash",
+ "pro"
+ ],
+ "type": "string"
+}upscale-imagev0.1.0artificer-statusgenerate-imageupscale-imageScored across 4 tools
Each tool targets a distinct action: generate, edit, cutout, and status. There is no meaningful overlap, and an agent can confidently select the right tool for creating new art, modifying existing art, preparing tokens, or checking system health.
Three tools follow a clear verb-noun pattern: generate-image, edit-image, cutout-image. artificer-status is a noun-noun outlier, but it still fits the server's naming style and is not confusing.
Four tools is well-scoped for a focused Foundry VTT art asset pipeline. Each tool represents a necessary step—create, edit, cut out, and check status—without unnecessary bloat.
The toolset covers the core lifecycle of generating, editing, and preparing token art, plus a health/status check. Minor gaps exist around listing or deleting assets, but for the stated purpose it is functionally complete and has no dead ends.
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Generate logos, social posts, app screenshots, comic panels & visual-novel assets from prompts.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
