# cascade-img [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/laffeyp/cascade-img  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cascade-img

## Description
LLM-operable Midjourney pipeline: 21 MCP tools to compose, generate, curate with vision, and log.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "cascade-img": {
    "command": "uvx",
    "args": ["cascade-img"]
  }
}
```

## Documentation & README

![cascade-img — direct Midjourney by conversation: a director writes a prompt card, a helper robot carries it to a colossal artist robot forging framed paintings, and hands the cut-out winner back](https://raw.githubusercontent.com/laffeyp/cascade-img/HEAD/.github/assets/readme-banner-alt.png)

[![CI](https://github.com/laffeyp/cascade-img/actions/workflows/ci.yml/badge.svg)](https://github.com/laffeyp/cascade-img/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cascade-img?color=%2334D058&label=pypi)](https://pypi.org/project/cascade-img/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](https://www.python.org/)
[![MCP Tools: 23](https://img.shields.io/badge/MCP_Tools-23-green.svg)](./AGENTS.md)

Generate Midjourney images by conversation instead of by hand. You describe what you want; your AI assistant composes the prompt, fires it, inspects the grid with vision, crops the best quadrant, cleans it up, and logs what worked.

```
You: "I need a flat-design mountain icon, centered, simple shapes, transparent background"

Agent: reads prompt log → composes prompt from parts → fires imagine →
       waits → inspects 2x2 grid with vision → picks best quadrant →
       crops it → removes background → saves → logs what worked
```

cascade-img is an MCP server with 23 tools that plugs into Claude, Cursor, Codex, or anything that speaks [MCP](https://modelcontextprotocol.io). Midjourney is the first backend; Flux, DALL-E, and Imagen are on the [roadmap](#roadmap). There's also a CLI.

> **Not a programmer?** Open an AI assistant that can run commands ([Claude Code](https://claude.com/claude-code), Cursor, or Cline), point it at this repo, and say: *"Read RUNBOOK.md and set up cascade-img on this machine, then let me make images by describing them to you."* It does the technical parts. You just need a Midjourney subscription and to copy a few values from Discord.

---

## Quick Start

**You need:** a [paid Midjourney subscription](https://midjourney.com), a Discord account with the MJ bot in a channel, and Python 3.12 or newer.

```bash
pip install cascade-img
```

Or from source:

```bash
git clone https://github.com/laffeyp/cascade-img
cd cascade-img/packages/python
pip install -e .
```

This puts three commands for operating cascade-img on your PATH: `cascade-mj-bridge` (the daemon), `cascade-mcp` (the MCP server), and `cascade-mj` (the CLI). Installing also adds a fourth command, `cascade-trace-check` — a diagnostics validator (not part of the generation loop) that replays a recorded event log and checks it against the vocabulary's declared event ordering and timing rules.

**Configure** — you need four values from the Discord desktop app (channel ID, server ID, imagine version, and your user token). Takes about five minutes. [RUNBOOK.md](https://github.com/laffeyp/cascade-img/blob/HEAD/RUNBOOK.md) walks through each one step by step.

```bash
cp "$(python -c 'import cascade_img, pathlib; print(pathlib.Path(cascade_img.__path__[0]) / ".env.example")')" .env
# Fill in the four values per RUNBOOK.md, then validate:
cascade-mj-bridge --check-env --pretty
```

**Start the daemon** in one terminal, then connect from another:

```bash
cascade-mj-bridge          # leave running — holds the Discord connection
```

**Connect your AI assistant** — add to your MCP config (Claude Desktop, Cursor, Cline):

```json
{
  "mcpServers": {
    "cascade-img": {
      "command": "cascade-mcp"
    }
  }
}
```

Or point your assistant at this repo and ask it to read [AGENTS.md](https://github.com/laffeyp/cascade-img/blob/HEAD/AGENTS.md) — it'll wire everything up.

**Or use the CLI:**

```bash
echo '{
  "mountain-icon": {
    "subject": "a flat-design icon of a mountain, centered, simple shapes",
    "aspect_ratio": "1:1"
  }
}' > assets.json

cascade-mj mountain-icon --registry assets.json --upscale all --pretty
```

---

## The 23 Tools

| Category | Tools | What they do |
|----------|-------|-------------|
| **Onboarding** | `cascade_guide` | Returns the full operating manual in one call — the loop, every tool, the failure→action table. Call it first; the generation and curation tools are gated until it's read. |
| **Generation** | `imagine`, `generate_video`, `wait`, `status`, `bridge_health`, `mj_action` | Compose and fire prompts, poll for results, check daemon health, trigger Midjourney actions (upscale, vary, pan) |
| **Catch-up** | `channel_recent`, `adopt_message` | See what the human did by hand in Discord and claim those results into the pipeline — adopted messages become normal jobs that curation and `mj_action` work on |
| **Composition** | `compose_prompt`, `compose_video` | Build prompts from structured parts — subject, moodboard, style refs, aspect ratio, negatives — not freeform text |
| **Curation** | `crop_grid`, `alpha_key`, `auto_trim`, `palette_quantize`, `contact_sheet`, `sprite_sheet`, `score_grid`, `video_filmstrip`, `loop_seam_delta`, `promote` | Extract quadrants from grids, remove backgrounds, trim whitespace, build sprite sheets, score results with vision, promote winners to final output |
| **Working memory** | `log_append`, `read_prompt_log` | Append-only prompt log the agent reads before every run — what was tried, what worked, what didn't. Persists across sessions. |

Every call returns `{ok, result}` or `{ok: false, error: {code, remediation}}`. Branch on the stable `code`, not the message. Full tool reference in [AGENTS.md](https://github.com/laffeyp/cascade-img/blob/HEAD/AGENTS.md).

---

## How This Differs

Other open-source Midjourney tools focus on the generation step — fire the prompt, hand back the image. cascade-img does the work around that:

- **Vision-based self-curation** — the agent inspects its own output and picks the best quadrant
- **Structured prompt composition** — prompts built from parts (subject, style, identity, constraints), not raw strings
- **Working memory** — append-only log persists across sessions; each run reads what came before
- **Curation pipeline** — crop grids, remove backgrounds, build sprite sheets, promote winners
- **MCP-native** — 23 tools that plug into Claude, Cursor, Codex, or anything that speaks MCP
- **Pluggable backends** — Midjourney now, Flux/DALL-E/Imagen on the roadmap

---

## How It Works

One daemon, two stateless clients, all over local HTTP:

- **`cascade-mj-bridge`** — the daemon. Only process that talks to Discord. Holds the live connection and tracks in-flight jobs. Must stay running.
- **`cascade-mcp`** — the MCP server. Stdio by default (Claude Desktop / Cursor / Cline); `--http <port>` for HTTP. Stateless — start and stop freely.
- **`cascade-mj`** — the CLI. Takes an asset ID and a registry, composes the prompt, fires, waits, writes to the log.

Prompts are composed from structured parts, not written as raw strings:

```python
from cascade_img.prompt.composer import PromptComposer, Subject, StyleStack, IdentityStack

prompt = PromptComposer().compose(
    Subject(
        text="a flat-design icon of a mountain",
        constraints=["centered", "simple shapes", "transparent background"],
    ),
    # Both optional. moodboard is a Midjourney personalization code;
    # sref/oref are reference-image URLs you'd set up in MJ first.
    style=StyleStack(moodboard="abc123def", sref="https://cdn.example.com/style.png"),
    identity=IdentityStack(oref="https://cdn.example.com/ref.png", ow=1000),
    aspect_ratio="1:1",
    version="7",
)
```

All three entry points emit structured JSON and follow the same `{ok, result | error: {code, remediation}}` envelope. Every failure carries a stable error code (e.g. `DISCORD_401`, `MJ_UUID_MISSING`, `UPSCALE_BUTTON_FAILED`) with a machine-readable remediation — so a caller branches on the code, not the message. The full catalog of log events and error codes is in [vocabulary/0.1.json](https://github.com/laffeyp/cascade-img/blob/HEAD/vocabulary/0.1.json), and a trace checker (`cascade-trace-check`) enforces event ordering over recorded runs.

<details>
<summary><strong>Midjourney terminology</strong></summary>

**prompt** — the text + flags you send Midjourney. **grid** — the 2x2 set of four candidates returned per prompt. **quadrant / U1-U4** — the four cells; "U2" means upscale the second. **upscale** — render one cell at full resolution. **aspect ratio (`--ar`)** — output shape. **sref** — an image whose *style* to borrow. **oref** — an image whose *subject identity* to keep across poses. **moodboard (`--p`)** — a saved personalization profile. **stylize (`--s`)** — how strongly MJ applies its own aesthetic.

</details>

---

## Documentation

| Doc | What it covers |
|-----|---------------|
| [AGENTS.md](https://github.com/laffeyp/cascade-img/blob/HEAD/AGENTS.md) | The LLM operator's guide. Read this when handing cascade-img to an agent. |
| [RUNBOOK.md](https://github.com/laffeyp/cascade-img/blob/HEAD/RUNBOOK.md) | Install, env capture, setup, reconnect lifecycle, every failure mode with error codes and fixes. |
| [CAPABILITIES.md](https://github.com/laffeyp/cascade-img/blob/HEAD/CAPABILITIES.md) | Every Midjourney feature cascade-img drives — prompt parameters, mj_actions, the V8.1/V7 split. |
| [ARCHITECTURE.md](https://github.com/laffeyp/cascade-img/blob/HEAD/ARCHITECTURE.md) | Internal architecture and design decisions. |
| [examples/](https://github.com/laffeyp/cascade-img/blob/HEAD/examples/) | Three walkthroughs: single image, batch, video. Read AGENTS.md first. |
| [CHANGELOG.md](https://github.com/laffeyp/cascade-img/blob/HEAD/CHANGELOG.md) | Release history. |

---

## Roadmap

| Version | What's in it |
|---|---|
| **v0.1** (current) | MJ backend (V8.1 + V7), prompt composer, curation tools, MCP server, CLI, prompt log |
| **v0.2** | Channel catch-up + message adoption — **landed on main**: `channel_recent` and `adopt_message` let the agent see what the human did by hand in Discord and act on it ([design](https://github.com/laffeyp/cascade-img/blob/HEAD/designs/channel-catchup-and-adoption.md)); still to come: more MJ commands (`/describe`, `/blend`, Vary Region inpaint, `/tune`), retro-U-press on adopted grids, internal refactoring |
| **v0.3** | TypeScript wrapper; first API backends — [Flux](https://bfl.ai/) via [Fal](https://fal.ai/) + [Flux Kontext](https://bfl.ai/models/flux-kontext), [Ideogram](https://ideogram.ai/) |
| **v0.4** | [Google Imagen](https://deepmind.google/models/imagen/), [Recraft](https://www.recraft.ai/) (native vector/SVG) |
| **v0.5** | [OpenAI gpt-image](https://openai.com/api/), [Stable Diffusion](https://stability.ai/stable-image) |
| **v1.0** | API stable, three+ backends in production |

Every backend implements one interface, so a later release can chain them — generate on one provider, refine on a second (e.g. Flux Kontext), upscale on a third.

---

## Repository Layout

```
cascade-img/
├── packages/python/        # the Python package (cascade_img)
│   ├── src/cascade_img/    #   prompt/, interfaces/, backends/, curation/, vocabulary/
│   ├── tests/              #   behavior tests
│   └── tools/              #   live smoke walk
├── examples/               # three walkthroughs of the operating loop
├── vocabulary/0.1.json     # event log-line catalog
└── *.md                    # README, ARCHITECTURE, RUNBOOK, AGENTS, CAPABILITIES, ...
```

---

## Disclaimer

This tool automates Midjourney through a Discord user account. A paid Midjourney subscription is required. Both Discord and Midjourney's Terms of Service prohibit user-account automation. This is the same mechanism used by every open-source MJ tool ([midjourney-proxy](https://github.com/novicezk/midjourney-proxy), [midjourney-api](https://github.com/erictik/midjourney-api), etc.) — there is no public Midjourney API. Use at your own risk.

The backend interface is pluggable — Flux, DALL-E, and Imagen are on the [roadmap](#roadmap).

## License

Apache-2.0. See [LICENSE](https://github.com/laffeyp/cascade-img/blob/HEAD/LICENSE).

<!-- mcp-name: io.github.laffeyp/cascade-img -->