local-gpu-imagegen

# Local GPU Imagegen

<!-- mcp-name: io.github.zc4578980-tech/local-gpu-imagegen -->

[English](README.md) | [简体中文](README.zh-CN.md)

An MCP-first control plane with cryptographic model identity, explicit approvals,
and durable run evidence for the ComfyUI setup you already use.

Run a supported ComfyUI workflow from Codex without modifying your setup.

```shell
uvx local-gpu-imagegen verify
uvx local-gpu-imagegen setup codex --apply
```

Setup stores a resolved, version-pinned launcher equivalent to
`uvx --from local-gpu-imagegen==0.8.3 local-gpu-imagegen serve`; it does not
depend on a console script from the temporary `uvx` environment. If an older
entry reports `client_setup_drift`, remove only that client entry and apply
setup again. Starting ComfyUI does not repair an MCP launcher failure; backend
readiness is checked after the client loads the server.

Ask Codex:

```text
Run this supported ComfyUI API workflow from Codex: <path>.
Use this prompt: <prompt>. Preserve every other workflow setting.
```

This path requires Python 3.11 or 3.12, Codex, an already-running local ComfyUI
instance, an already-installed model, and one ordinary `txt2img` API workflow
using the supported built-in topology. It uses your existing local image
backend and model with no silent model downloads or switches. It does not
install a backend, download a model, convert UI-format JSON, or execute a
workflow that requires unsupported custom nodes. An explicit Windows portable
managed-start option is documented below.

ComfyUI generates the pixels. Local GPU Imagegen controls authority,
reproducibility, review, and recovery around that generation.

[Five-minute Quickstart](docs/quickstart.md) | [Launch playbook](docs/launch-playbook.md) | [Alternatives](docs/alternatives.md)

## Bring Your Own ComfyUI Workflow

The retained Codex workflow-onboarding session inspected and registered a supported graph, then bound its exact model components; it did not submit a prompt or use the GPU. The image below comes from a separate retained Codex generation through the ordinary reviewed route. These are distinct evidence records, and neither proves image-quality superiority.

![A solitary lighthouse generated through the validated ordinary local SDXL route](docs/demo/real/final.png)

Original finalized 1024x1024 PNG from ordinary `sdxl-txt2img`; SHA-256 `36b5de509a2da8c75571aac436d45d8a31a7a8efc77439abee9e0918191572f4`. Inspect the [validated showcase manifest](docs/demo/real/showcase-manifest.json) for the route, prompts, settings, review, client binding, rights, and limitations.

This path requires an existing local image backend and model; there are no silent model downloads or switches.

`setup` is read-only without `--apply`. The apply path delegates to the client's official `mcp add` command; Local GPU Imagegen does not edit client configuration files directly or download a model.

**Trust proof:** the retained ordinary-route result came from one installed Codex session. Discovery did not load weights; trust and route identity were explicit; successful rounds were bounded; review used the original-resolution PNG; finalization was bound to the reviewed bytes; and the run state remains recoverable. The evidence proves this one result, not complete 9+3 acceptance, measured performance, or production readiness.

### Optional Managed ComfyUI Startup

Windows setup can register one existing portable root for managed startup:

```powershell
uvx local-gpu-imagegen setup codex --apply `
  --auto-start-comfyui `
  --comfyui-root "<ComfyUI_windows_portable>"
```

The opt-in command validates the fixed portable layout and registers
`python_embeded\python.exe -s ComfyUI\main.py` at `127.0.0.1:8188`. It does not
install ComfyUI or download a model. An already-running endpoint is reused but
never owned or stopped. A child started by the MCP process is stopped at MCP
exit only when its queue is empty; a non-empty queue is retained and reported.
Both modes use the existing backend and model with no silent model downloads
or switches. Workflow execution remains limited to supported built-in
topologies; managed startup does not remove or manage custom nodes already
present in the selected portable installation.

![Simulated brief-to-candidate protocol loop](docs/demo/preview-loop.gif)

> The animation is a deterministic simulated protocol demonstration, not model output or image-quality evidence. It remains secondary to the genuine result above. Model-free tests cover the protocol and backend contracts, not image quality, broader named-client generation, performance, or complete 9+3 acceptance.

For Claude Code, use `uvx local-gpu-imagegen setup claude-code --apply`. Remove the entries with `codex mcp remove local-gpu-imagegen` or `claude mcp remove --scope user local-gpu-imagegen`. Use `uvx local-gpu-imagegen doctor` to inspect local backend readiness. The setup contracts and equivalent stdio launches are verified; one Codex installed-client generation is retained, while Claude Code generation remains pending. See [Client compatibility](docs/client-compatibility.md).

Before PyPI publication, install the verified wheel or a source checkout, then use the equivalent `local-gpu-imagegen verify` and `local-gpu-imagegen setup ...` commands.

## Why This Project

- **Run supported workflows from your Agent:** inspect and register ordinary ComfyUI API graphs instead of rebuilding them as one-off scripts.
- **Reuse or explicitly manage your backend:** ComfyUI is the primary existing-workflow path; an opt-in Windows portable supervisor removes manual startup without taking ownership of an existing process. AUTOMATIC1111/Forge and Diffusers remain compatibility paths.
- **Make runs reproducible:** freeze workflow, model identity, prompts, settings, seed, budget, and output hashes in a durable manifest.
- **Use the installed CLI:** verify readiness and delegate setup to the official Codex or Claude Code command without requiring a source checkout.
- **Keep model authority explicit:** discovery never loads weights, and generation cannot silently download or switch a model.
- **Retain structured evidence:** routes, budgets, attempts, image hashes, reviews, and recovery actions remain machine-readable and durable.
- **Keep acceptance with the user:** original-resolution review and later byte-bound finalization separate a generated image from an accepted final.
- **Agent-guided workflow:** a bundled Agent Skill turns a natural-language brief into a catalog-gated, confirmed run.
- **Three delivery Profiles:** standalone illustrations, presentation visuals, and UI visual assets share one deterministic run and review contract.
- **Auditable hot revision:** an immutable child run records a preserve/change contract and uses prompt refinement, img2img, or explicitly confirmed inpainting.
- **Dependency-light MCP layer:** protocol checks and tests use the Python standard library and require no GPU.
- **Focused scope:** image generation is kept separate from planning, memory, and unrelated agent features.

### Experimental Composition Controls

The golden path uses ordinary `sdxl-txt2img`. The `sdxl-regional-txt2img` and `sdxl-two-stage-copy-subject` routes remain experimental, are not part of the golden path, and provide no fallback from the ordinary route. Their retained negative evidence does not establish a visual-quality improvement.

### Image Quality Boundary

Model and workflow quality remain user supplied. Local GPU Imagegen adds explicit execution, review, recovery, and evidence; it does not modify diffusion algorithms or guarantee that a prompt workflow improves an image. Review now treats a change to the requested product medium, subject, practical use, or asset slot as semantic substitution and a failed constraint, even when the replacement looks cleaner.

See [Image quality control](docs/image-quality-control.md) and the frozen [workflow no-regression gate](docs/quality-feasibility-gate-report.md). The retained gate ended in `FAIL_WORKFLOW_REGRESSION`; no public image-quality superiority claim is supported.

## Source Checkout And Backend Setup

### 1. Verify The MCP Server

Python 3.11 or 3.12 is enough for this check. No GPU, model, or AI client is required.

```powershell
python .\scripts\verify_mcp.py
```

Expected result:

```json
{
  "ok": true,
  "transport": "stdio",
  "python": "<current-python>",
  "server": {"name": "local-gpu-imagegen", "version": "0.8.3"},
  "protocolVersion": "2024-11-05",
  "tools": [
    "local_gpu_branch_run",
    "local_gpu_cleanup_run",
    "local_gpu_confirm_mask",
    "local_gpu_discover_models",
    "local_gpu_finalize_run",
    "local_gpu_generate_image",
    "local_gpu_generate_round",
    "local_gpu_get_run",
    "local_gpu_imagegen_check",
    "local_gpu_list_profiles",
    "local_gpu_prepare_mask",
    "local_gpu_recommend_models",
    "local_gpu_record_review",
    "local_gpu_register_workflow",
    "local_gpu_set_model_trust",
    "local_gpu_start_run",
    "local_gpu_inspect_workflow"
  ]
}
```

### 2. Choose A Backend

| Backend | Best when | Setup | Network behavior |
|---|---|---|---|
| WebUI | AUTOMATIC1111 or Forge is already installed | Start it with API access enabled | Prompts/images go to the configured WebUI URL |
| ComfyUI | You already run ComfyUI and want reviewed graph execution | Start it yourself, or opt into `setup --auto-start-comfyui --comfyui-root <root>` for one existing Windows portable install | Prompts/images go only to the loopback or separately confirmed endpoint |
| Diffusers | You want a self-contained Python pipeline | Create the project `.venv` with `scripts/install.ps1` | Model/LoRA downloads are blocked unless explicitly allowed |

Check current readiness:

```powershell
python .\scripts\check_gpu.py
```

The command returns JSON. `ready: false` is a valid diagnostic state, not a protocol failure.

Managed startup is explicit and Windows-portable-only. It forces Python `-s`
isolation so