Un servidor de Model Context Protocol para generación de imágenes específico para Foundry, para arte de mesa de D&D, impulsado por Claude Code. Envuelve una instancia headless de ComfyUI en la máquina local y expone un pequeño conjunto de herramientas orientadas a Foundry para que Claude pueda redactar prompts, generar lotes de ilustraciones, curar los resultados mirándolos de verdad y entregar los ganadores al pipeline de Foundry en su servidor hermano, fvtt-mcp-molten5e (upload-asset → set-actor-art / add-journal-image / fondos de escena).
El ciclo completo es lo bastante rápido como para ser conversacional en el hardware objetivo (RTX 5090): un lote de borradores de 6 imágenes se genera en ~10 s, un render terminado de 2560×1600 en ~19 s, y el ciclo completo prompt → borrador → curar → final → diario en el mundo se probó de extremo a extremo en notes/m3-loop-proof.md.
Esto no es un puente genérico de ComfyUI, por decreto. Las herramientas hablan el vocabulario de Foundry — retratos de actor, tokens, handouts, fondos de escena — y se ajustan libremente para el trabajo con Foundry. Y se mantiene separado de fvtt-mcp-molten5e: ese servidor está limitado a la creación de contenido de Foundry y no debe acoplarse a la generación de imágenes. Este servidor nunca habla con el puente de Foundry; el traspaso entre ambos son archivos en disco más las herramientas de subida de molten5e.
La misma filosofía de casa que el resto de la familia: las herramientas hacen, las skills deciden. La corrección (ejecución del workflow, dimensiones, el pipeline de upscaling, convenciones de archivos) reside en las herramientas probadas; el criterio (elaboración del prompt, gusto de curación, qué actor o diario recibe el arte, estilo de casa) reside en una skill posterior illustration-builder.
Claude ──MCP──> fvtt-mcp-artificer ──HTTP──> ComfyUI (headless, local)
│
└── pinned workflow JSONs (draft / final / final-refine / upscale)ComfyUI se ejecuta headless en modo API; este servidor envía los workflow JSON fijados que están en workflows/ — nunca grafos de forma libre — con prompt/seed/batch/preset sustituidos (por ID de nodo, protegido por aserciones de deriva de tipo de clase). Las herramientas devuelven rutas de archivo absolutas; Claude lee los PNG directamente para curar.
Related MCP server: FoundryVTT MCP Server
generate-image recibe un kind, no ancho/alto:
kind | genera a | salida final |
| 1536×960 | 2560×1600 |
| 1024×1280 | 2048×2560 |
| 1024×1024 | 2048×2048 |
Pipeline de resolución (fijado): nunca generar al tamaño de salida — la composición se degrada más allá de ~1.5 MP. Genera a la resolución nativa del preset, upscaling por modelo ×4 con 4x-UltraSharp, downsampling lanczos al tamaño final, todo en un único grafo fijado.
FLUX.1-dev fp8 (Comfy-Org all-in-one) — renders de calidad final, ~15–19 s por render terminado.
FLUX.2-klein 4B (Apache 2.0) — el modelo de borradores: 4 pasos, ~1–2 s/imagen, lote de 6–8, elige y vuelve a renderizar con dev.
4x-UltraSharp — el upscaler de modelo en la cola del pipeline.
herramienta | qué hace |
|
|
| Termina una imagen existente (normalmente un borrador que ganó la curación directamente) a través de la cola de upscaling hasta la resolución de salida de su |
| Comprobación de salud: accesibilidad/versión de ComfyUI, VRAM, profundidad de la cola, integridad de los workflow fijados, presencia de los modelos requeridos. |
El contrato de sustitución entre las herramientas y los grafos fijados está documentado en workflows/README.md.
Windows + GPU NVIDIA. Desarrollado y probado en una RTX 5090 (Blackwell necesita PyTorch con CUDA 12.8+; la compilación portable actual de ComfyUI lo incluye).
ComfyUI (compilación portable independiente, v0.34+) ejecutándose headless — consulta scripts/launch-comfyui.ps1 para la convención de lanzamiento (modo API en 127.0.0.1:8188, con --output-directory fijado).
Los archivos de modelo en el árbol models/ de ComfyUI (~33 GB, todos sin restricciones de acceso): 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 informa de cualquier modelo que falte.
Node.js 22+ para el propio servidor MCP.
npm install
npm run buildPruebas: npm test (suite de pruebas unitarias sin conexión; los workflow JSON fijados son los fixtures). La suite en vivo — ComfyUI real, renders reales — está detrás de npm run test:integration. Puertas de calidad: npm run typecheck, npm run check (biome), npm run knip.
La convención de la casa registra el servidor en el alcance de usuario (nuevas herramientas MCP ⇒ reinicia Claude Code). O usa la CLI:
claude mcp add -s user artificer -- node D:/path/to/fvtt-mcp-artificer/dist/index.jso copia .mcp.json.example a un .mcp.json que Claude Code lea (o combínalo en mcpServers de ~/.claude.json) con rutas absolutas. En Windows, apunta command a la ruta completa de node.exe si Node no está en PATH.
Copia .env.example a .env (ignorado por git):
COMFY_URL — la instancia headless (por defecto http://127.0.0.1:8188).
COMFY_OUTPUT_DIR — debe coincidir con el --output-directory con el que se lanzó ComfyUI; el servidor lee los PNG generados directamente de esta ruta.
ARTIFICER_TIMEOUT_MS — límite de espera por trabajo (por defecto 300000).
Licencia MIT — consulta LICENSE para más detalles.
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.
