@@ -0,0 +1,149 @@
+# MCP Server for diffusers-workflow — Scoping Doc
+
+## Background
+
+`diffusers-workflow` (dkackman/diffusers-workflow) is a declarative JSON
+workflow engine for Hugging Face Diffusers, with a local HTTP server
+(`dw.serve`, default port 8765) that exposes a full REST API: workflow
+CRUD, a job queue with SSE progress streaming, model management,
+introspection of diffusers pipeline signatures, and a gallery of past
+generations with embedded metadata.
+
+Today, workflow authoring and debugging, for the project developer,
+can happen via Claude Code in VS Code,
+with direct repo/filesystem access: "create a workflow that does X," or
+"workflow Y produces bad output, find out why" — Claude Code runs the
+workflow, reads logs, checks GPU memory, and proposes fixes to code or
+workflow config. It has even gone so far as to identify bad RAM causing
+intermittent generation failures.
+
+That flow works well for the developer (me), but it assumes a dev
+environment: a repo checkout, a terminal, VS Code, comfort reading stack
+traces. The next audience is **non-developer end users** of the packaged
+product, who won't have any of that. They'll have the app (web UI /
+`dw.serve`, or an embedded product surface), not a coding agent with shell
+access.
+
+## Goal
+
+Turn this from a dev-only workflow authoring/debugging tool into a **non-dev-friendly MCP server** that exposes the same "author a workflow / run it / diagnose why it
+failed or produced bad output" capability, but in a structured, bounded way that
+doesn't require shell access or a dev environment. The MCP server will wrap the existing `dw.serve` HTTP API, exposing a constrained tool surface for workflow authoring and debugging, suitable for non-developer users.
+
+The modes the underlying workflow can be authored and run today are::
+
+- a text editor and CLI `python -m dw.run workflow.json`
+- with command line REPL `python -m dw.repl`
+- via the HTTP API `dw.serve` and existing web UI
+
+So this adds a fourth mode, which would be cool if we turned this into an AI first product: an MCP server that can be driven by a Claude Code agent, or eventually a local LLM-backed agent, to author and run workflows without deep
+knowledge of diffusers, my workflow engine, or any of that complexity. The MCP server would expose a structured tool surface for workflow authoring and debugging, suitable for non-developer users.
+
+- via the MCP server (new) — structured tool surface
+
+Expose the same "author a workflow / run it / diagnose why it failed or
+produced bad output" capability as an **MCP server**, wrapping the existing
+`dw.serve` HTTP API. This lets any MCP-compatible client — Claude Code
+first, later Claude Desktop/claude.ai, and eventually a local-LLM-backed
+client — drive the engine through a bounded, structured tool surface
+instead of raw shell/API access.
+
+## Why MCP (not just keep using Claude Code)
+
+- Claude Code assumes a dev environment; end users won't have one.
+- MCP tools are a defined, constrained surface (structured in/out, no
+  arbitrary code execution) — appropriate once non-developers are the
+  audience, and safer than raw shell access.
+- The underlying HTTP API already exists and is already defensive
+  (path validation, traversal blocking, `Origin` header checks, JSON size
+  limits) — MCP adds a protocol layer in front of it, not new attack
+  surface.
+- Protocol-agnostic: same server can later be pointed at Claude Code, a
+  future embedded chat UI in the product, or a local-LLM-backed client.
+
+## Rollout sequence (decided)
+
+1. **Start with MCP server + Claude Code** as the client, for continued dev
+   use and to validate the tool surface.
+2. **Move to embedded-in-app** later, once the product is packaged for
+   non-developer users. This later phase will need its own auth story,
+   since the server currently binds to `127.0.0.1` with no authentication
+   (see Security, below) — fine for local/trusted-LAN use, not fine for a
+   hosted/remote product.
+3. **Local LLM support** stays a goal throughout — keep the option open
+   for users who won't have/want a paid Claude subscription. MCP is
+   protocol-agnostic, so this is a separate, later concern from the MCP
+   server itself, not a blocker to starting.
+
+## Proposed MCP tool set
+
+Mapped to existing `dw.serve` routes — no new server-side endpoints needed
+for the initial build.
+
+### Read-only / low-cost (build first)
+
+| Tool | Route(s) | Notes |
+| --- | --- | --- |
+| `list_workflows` | `GET /api/workflows` | descriptions, output kinds, variable counts |
+| `get_workflow(name)` | `GET /api/workflows/{name}` | full JSON |
+| `validate_workflow(json)` | `POST /api/validate` | schema + signature-level argument checks; no GPU cost — good pre-flight tool |
+| `get_schema` | `GET /api/schema` | workflow JSON schema |
+| `get_pipeline_signature(name)` | `GET /api/pipelines/{name}` | lets the agent check real pipeline arguments before proposing a config fix |
+| `list_classes(kind)` / `get_class(name)` | `GET /api/classes?kind=...`, `GET /api/classes/{name}` | broader introspection beyond pipelines |
+| `list_tasks` / `get_task(command)` | `GET /api/tasks`, `GET /api/tasks/{command}` | task-step argument schemas |
+| `list_models` | `GET /api/models` | hub cache inventory: sizes, revisions, last-used |
+| `get_memory` | `GET /api/memory` | worker VRAM/RAM stats — answers the GPU-diagnosis need directly, no new endpoint required |
+| `get_health` | `GET /api/health` | liveness |
+| `get_gallery_item(name)` | `GET /api/gallery/{name}/metadata` | pull back a prior run's exact workflow + seed, e.g. to reproduce a failure |
+
+### Diagnostic loop (build second)
+
+| Tool | Route(s) | Notes |
+| --- | --- | --- |
+| `run_workflow(workflow_path \| inline_workflow, arguments)` | `POST /api/jobs` | **Costs GPU time; one job runs at a time.** See confirm-gating below. |
+| `get_job(job_id)` | `GET /api/jobs/{id}` | full detail: spec, events, manifest, error — primary diagnosis payload |
+| `stream_job_events(job_id, after?)` | `GET /api/jobs/{id}/events` | SSE; `job_status`/`phase`/`memory`/`log` events cover exactly the "instrument the process" need (phase transitions: loading → generating → decoding → saving) |
+| `cancel_job(job_id)` | `POST /api/jobs/{id}/cancel` | cooperative cancel |
+| `rerun_job(job_id)` | `POST /api/jobs/{id}/rerun` | re-queue after a fix |
+| `move_job(job_id, direction)` | `POST /api/jobs/{id}/move` | reorder queued jobs |
+
+### Deferred / optional
+
+- `POST /api/models/download`, `DELETE /api/models`, `/api/system/diffusers*`
+  — model and dependency management; useful eventually, not needed for the
+  first author/run/diagnose loop.
+- Prompt library endpoints (`/api/prompts*`, `/api/enhance`) — relevant if
+  the agent should also help build/enhance prompts, not core to diagnosis.
+
+## Key design decisions
+
+1. **`run_workflow` is confirm-gated.** A run costs real GPU time (and
+   possibly money) and the engine is single-GPU/single-job-at-a-time. MCP
+   has no built-in elicitation/confirmation primitive, so the confirm step
+   should live in the client/agent behavior (state what's about to run and
+   get explicit go-ahead) rather than the tool silently firing.
+   `validate_workflow` is free and can run without confirmation first.
+
+2. **Security model carries over, doesn't change.** The server already
+   validates every path (`dw/security.py`), blocks traversal, rejects
+   non-local `Origin` headers, and confines file access to the configured
+   workflow/output/prompt directories. MCP wrapping this doesn't add new
+   risk for the local/Claude-Code phase. It does **not** solve remote
+   auth — the server binds to `127.0.0.1` by default with no
+   authentication; `--host 0.0.0.0` exists but is explicitly documented as
+   trusted-LAN-only. The embedded-in-app phase needs a real auth story
+   before any hosted/remote exposure.
+
+3. **Build order:** read-only tools first (workflow authoring assistant
+   usable almost immediately), then the run/diagnose loop once the
+   confirm-gating pattern for `run_workflow` is settled.
+
+## Open questions for implementation
+
+- Which MCP transport/SDK — Python `mcp` SDK (project is already Python)
+  talking to `http://127.0.0.1:8765/api/...` via `httpx`, run as a stdio
+  server for Claude Code.
+- Exact confirmation UX for `run_workflow` — client-side prompt text,
+  and whether to surface estimated cost/time if the API can supply it.
+- Whether GPU/worker diagnostics need anything beyond `/api/memory`, or
+  whether that's sufficient for the diagnostic loop as scoped.
@@ -456,6 +456,7 @@ def _run_once(self, arguments):
             output = output.to("cpu")
 
         attach_audio_sample_rate(self.pipeline, output)
+        warn_if_safety_checker_blanked(output)
 
         return output
 
@@ -1056,6 +1057,31 @@ def get_component(pipeline, component_name):
     return component
 
 
+def warn_if_safety_checker_blanked(output):
+    """Say so when a safety checker replaced a generated image with a black one.
+
+    Stable Diffusion 1.5's checker false-positives readily, and it returns a
+    solid black image rather than an error. Run to run that reads as the seed
+    having no effect - the same result every time - so the reason belongs in
+    the log where the identical images do.
+
+    Args:
+        output: The pipeline output, which may carry nsfw_content_detected
+    """
+    flags = getattr(output, "nsfw_content_detected", None)
+    if not flags:
+        return
+
+    blanked = sum(1 for flag in flags if flag)
+    if blanked:
+        logger.warning(
+            f"The safety checker blanked {blanked} of {len(flags)} generated "
+            "images - they are solid black, and no seed will change that. "
+            "Pass 'safety_checker': null in from_pretrained_arguments to "
+            "load the pipeline without it."
+        )
+
+
 def attach_audio_sample_rate(pipeline, output):
     """Record the vocoder's sample rate on an output that carries generated audio.
 
 
@@ -678,8 +678,11 @@ def gallery(limit: int = 200):
                 {
                     "name": name,
                     # Quoted: a name carrying '#', '?' or '%' would otherwise
-                    # break the src the gallery renders it into
-                    "url": f"/outputs/{quote(name)}",
+                    # break the src the gallery renders it into. The mtime
+                    # rides along because a rerun overwrites the same name -
+                    # on an unchanging URL the browser would keep showing the
+                    # image it cached from the previous run
+                    "url": f"/outputs/{quote(name)}?v={int(stat.st_mtime)}",
                     "kind": kind,
                     "size": stat.st_size,
                     "mtime": stat.st_mtime,
 
@@ -67,6 +67,12 @@ def run(self, previous_results, previous_pipelines, step_action):
             iterations = get_iterations(step_action.argument_template, previous_results)
             logger.debug(f"Generated {len(iterations)} argument combinations")
 
+            # The metadata above was read from the definition, where an
+            # argument may still be a 'previous_result:' reference - now that
+            # the iterations exist, record what the step actually ran with
+            if result.metadata is not None:
+                _realize_metadata_arguments(result.metadata, iterations)
+
             # Execute the action for each set of arguments
             if not iterations:
                 logger.warning(f"Step {step_name} has no iterations to execute")
@@ -130,3 +136,38 @@ def _collect_metadata(self):
             metadata["arguments"] = dict(task_def.get("arguments", {}))
 
         return metadata
+
+
+# What json.dumps can embed without falling back to str() - anything else
+# (a PIL image, a tensor, a video's frames) keeps its reference in metadata
+JSON_SCALARS = (str, int, float, bool)
+
+
+def _realize_metadata_arguments(metadata, iterations):
+    """Replace the embedded arguments with the values the step really ran with.
+
+    Step metadata is collected from the definition, so an argument written as
+    "previous_result:expand" is still a reference there - a gallery showing it
+    would display the reference instead of the prompt the pipeline saw. The
+    iterations hold the resolved values, so lift the JSON-safe ones back into
+    the metadata. When iterations disagree (a step fanned out over several
+    prior results) every distinct value is kept, in order.
+    """
+    arguments = metadata.get("arguments")
+    if not arguments or not iterations:
+        return
+
+    for key in list(arguments):
+        values = []
+        for iteration in iterations:
+            if not isinstance(iteration, dict) or key not in iteration:
+                values = []
+                break
+            value = iteration[key]
+            if not isinstance(value, JSON_SCALARS):
+                values = []
+                break
+            if value not in values:
+                values.append(value)
+        if values:
+            arguments[key] = values[0] if len(values) == 1 else values
@@ -8,6 +8,7 @@
 
 from dw.pipeline_processors.pipeline import (
     Pipeline,
+    warn_if_safety_checker_blanked,
     configure_components,
     declared_component_names,
     enable_cache_on_transformer,
@@ -449,3 +450,34 @@ def test_remote_text_encoder_does_not_edit_the_definition(self, monkeypatch):
 
         assert arguments["text_encoder"] is None
         assert "text_encoder" not in definition["from_pretrained_arguments"]
+
+
+class TestSafetyCheckerWarning:
+    """A blanked image looks like a repeated result - it has to say so."""
+
+    def test_warns_when_the_safety_checker_blanked_an_image(self, caplog):
+        output = MagicMock()
+        output.nsfw_content_detected = [False, True]
+
+        with caplog.at_level("WARNING", logger="dw"):
+            warn_if_safety_checker_blanked(output)
+
+        assert "safety checker" in caplog.text.lower()
+        assert "1 of 2" in caplog.text
+
+    def test_silent_when_nothing_was_flagged(self, caplog):
+        output = MagicMock()
+        output.nsfw_content_detected = [False, False]
+
+        with caplog.at_level("WARNING", logger="dw"):
+            warn_if_safety_checker_blanked(output)
+
+        assert caplog.text == ""
+
+    def test_silent_for_a_pipeline_without_a_safety_checker(self, caplog):
+        output = MagicMock(spec=[])
+
+        with caplog.at_level("WARNING", logger="dw"):
+            warn_if_safety_checker_blanked(output)
+
+        assert caplog.text == ""
@@ -490,6 +490,30 @@ def test_gallery_lists_media_and_reads_metadata(server, tmp_path):
         assert read_embedded_metadata(str(outputs / "meta.jpg"))["step_name"] == "gen"
 
 
+def test_gallery_urls_change_when_a_file_is_rewritten(server, tmp_path):
+    """A rerun overwrites the same name - the URL must move or the browser
+    keeps showing the image it already cached."""
+    import os
+    from PIL import Image
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        path = outputs / "test_image-gen.0-0.0.png"
+        Image.new("RGB", (4, 4), "red").save(path)
+
+        first = client.get("/api/gallery").json()["files"][0]["url"]
+        assert first.startswith("/outputs/test_image-gen.0-0.0.png?")
+        assert client.get(first).status_code == 200
+
+        # the same file, rewritten - as a second run of the workflow does
+        Image.new("RGB", (4, 4), "blue").save(path)
+        os.utime(path, (0, os.stat(path).st_mtime + 10))
+
+        second = client.get("/api/gallery").json()["files"][0]["url"]
+        assert second != first
+        assert client.get(second).status_code == 200
+
+
 def test_embed_metadata_carries_the_workflow_definition(tmp_path):
     """A run with embed_metadata writes an image the gallery can reopen."""
     from unittest.mock import patch