cascade-img

手作業ではなく、会話を通じてMidjourneyの画像を生成します。作りたいものを伝えると、AI アシスタントがプロンプトを作成して送信し、ビジョン機能でグリッドを確認し、最適な象限を切り抜いて仕上げ、効果のあった内容を記録します。

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は、Claude、Cursor、Codex、またはMCPに対応するあらゆるツールに接続できる、23個のツールを備えたMCP サーバーです。最初のバックエンドはMidjourneyです。Flux、DALL-E、Imagenはロードマップに掲載されています。CLIもあります。

プログラマーではありませんか？ コマンドを実行できるAI アシスタント（Claude Code、Cursor、Clineなど）を開き、このリポジトリを指定して、次のように伝えてください：「RUNBOOK.mdを読んで、このマシンにcascade-imgをセットアップしてから、画像の説明を伝えるだけで画像を作れるようにしてください。」 技術的な作業はアシスタントが行います。必要なのはMidjourneyのサブスクリプションと、Discordからいくつかの値をコピーすることだけです。

---

クイックスタート

必要なもの： 有料のMidjourneyサブスクリプション、チャンネルにMJボットがいるDiscordアカウント、Python 3.12以降。

pip install cascade-img

または、ソースからインストールします：

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

これにより、cascade-imgを操作するための3つのコマンドがPATHに追加されます：cascade-mj-bridge（デーモン）、cascade-mcp（MCP サーバー）、cascade-mj（CLI）です。インストール時には4つ目のコマンドcascade-trace-checkも追加されます。これは診断用のバリデーターであり、生成ループの一部ではありません。記録されたイベントログを再生し、語彙で宣言されたイベントの順序とタイミングのルールに照らして検証します。

設定 — Discordデスクトップアプリから4つの値（チャンネルID、サーバーID、imagineバージョン、ユーザートークン）が必要です。所要時間は約5分です。RUNBOOK.mdに、各手順が順を追って説明されています。

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

デーモンを起動し、別のターミナルから接続します：

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

AI アシスタントを接続 — MCP設定に追加します（Claude Desktop、Cursor、Cline）：

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

または、このリポジトリをアシスタントに指定して、AGENTS.mdを読むよう依頼してください。必要な設定をすべて行ってくれます。

または、CLIを使用します：

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

---

23 個のツール

カテゴリ	ツール	機能
オンボーディング	cascade_guide	1 回の呼び出しで運用マニュアル全体を返します。ループ、各ツール、失敗→アクションの対応表が含まれます。最初に呼び出してください。読み終えるまで、生成ツールとキュレーションツールは利用できません。
生成	imagine, generate_video, wait, status, bridge_health, mj_action	プロンプトを組み立てて実行し、結果を確認し、デーモンの状態をチェックし、Midjourney のアクション（アップスケール、バリエーション、パン）を実行します
キャッチアップ	channel_recent, adopt_message	Discord で人間が手動で行った操作を確認し、その結果をパイプラインに取り込みます。取り込まれたメッセージは通常のジョブとなり、キュレーションと mj_action の処理対象になります
プロンプトの構成	compose_prompt, compose_video	自由形式のテキストではなく、被写体、ムードボード、スタイル参照、アスペクト比、ネガティブ指定などの構造化された要素からプロンプトを作成します
キュレーション	crop_grid, alpha_key, auto_trim, palette_quantize, contact_sheet, sprite_sheet, score_grid, video_filmstrip, loop_seam_delta, promote	グリッドから象限を切り出し、背景を除去し、余白をトリミングし、スプライトシートを作成し、ビジョン機能で結果を評価して、優れた結果を最終出力に昇格させます
作業メモリ	log_append, read_prompt_log	エージェントが実行のたびに読み込む、追記専用のプロンプトログです。試したこと、うまくいったこと、うまくいかなかったことを記録し、セッションをまたいで保持します。

各呼び出しは {ok, result} または {ok: false, error: {code, remediation}} を返します。メッセージではなく、安定した code に基づいて分岐してください。ツールの全リファレンスは AGENTS.md を参照してください。

---

他との違い

ほかのオープンソースの Midjourney ツールは、生成の工程、つまりプロンプトを実行して画像を返すところに注力しています。cascade-img はその前後の作業も担います。

• ビジョンベースの自己キュレーション — エージェントが自身の出力を確認し、最適な象限を選択します
• 構造化されたプロンプト構成 — 生の文字列ではなく、要素（被写体、スタイル、アイデンティティ、制約）からプロンプトを作成します
• 作業メモリ — 追記専用ログをセッションをまたいで保持し、各実行でそれまでの内容を読み込みます
• キュレーションパイプライン — グリッドを切り出し、背景を除去し、スプライトシートを作成して、優れた結果を昇格させます
• MCP ネイティブ — Claude、Cursor、Codex など、MCP に対応するあらゆるものに接続できる 23 個のツール
• プラグイン可能なバックエンド — 現在は Midjourney に対応し、Flux／DALL-E／Imagen もロードマップに含まれています

---

動作の仕組み

1つのデーモンと2つのステートレスなクライアントが、すべてローカル HTTP 経由で動作します。

• cascade-mj-bridge — デーモンです。Discord と通信する唯一のプロセスです。ライブ接続を維持し、実行中のジョブを追跡します。常に起動しておく必要があります。
• cascade-mcp — MCP サーバーです。デフォルトでは Stdio（Claude Desktop / Cursor / Cline）を使用し、HTTP の場合は --http <port> を指定します。ステートレスなので、自由に起動・停止できます。
• cascade-mj — CLI です。アセット ID とレジストリを受け取り、プロンプトを構成して実行し、完了を待ってログに書き込みます。

プロンプトは、未加工の文字列ではなく、構造化されたパーツから構成されます。

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",
)

3つのエントリーポイントはすべて構造化 JSON を出力し、同じ {ok, result | error: {code, remediation}} エンベロープに従います。すべての失敗には、機械可読な対処法を含む安定したエラーコード（例：DISCORD_401、MJ_UUID_MISSING、UPSCALE_BUTTON_FAILED）が付与されるため、呼び出し元はメッセージではなくコードに基づいて分岐できます。ログイベントとエラーコードの全カタログは vocabulary/0.1.json にあり、トレースチェッカー（cascade-trace-check）は記録された実行のイベント順序を検証します。

Midjourney の用語

prompt — Midjourney に送信するテキストとフラグです。grid — プロンプトごとに返される4つの候補を並べた2x2のセットです。quadrant / U1-U4 — 4つのセルです。「U2」は2番目のセルをアップスケールするという意味です。upscale — 1つのセルをフル解像度でレンダリングすることです。aspect ratio (--ar) — 出力の縦横比です。sref — スタイルを借用する画像です。oref — ポーズが変わっても同じ被写体のアイデンティティを維持する画像です。moodboard (--p) — 保存済みのパーソナライズプロファイルです。stylize (--s) — MJ 独自の美的表現をどの程度適用するかを指定します。

---

ドキュメント

ドキュメント	内容
AGENTS.md	LLM オペレーター向けガイドです。cascade-img をエージェントに引き継ぐ際にお読みください。
RUNBOOK.md	インストール、環境の取得、セットアップ、再接続のライフサイクル、エラーコードと修正方法を含むすべての障害モードについて説明します。
CAPABILITIES.md	cascade-img が操作する Midjourney の全機能について説明します。プロンプトパラメーター、mj_actions、V8.1/V7 の違いが含まれます。
ARCHITECTURE.md	内部アーキテクチャと設計上の決定事項について説明します。
examples/	3つのウォークスルー（単一画像、バッチ、動画）です。最初に AGENTS.md をお読みください。
CHANGELOG.md	リリース履歴です。

---

ロードマップ

バージョン	内容
v0.1（現行）	MJ バックエンド（V8.1 + V7）、プロンプトコンポーザー、キュレーションツール、MCP サーバー、CLI、プロンプトログ
v0.2	チャンネルの遡及取得 + メッセージの採用 — main にマージ済み：channel_recent と adopt_message により、エージェントは Discord で人間が手動で行った操作を確認し、それに基づいて処理できます（設計）。今後の予定：MJ コマンドの追加（/describe、/blend、Vary Region inpaint、/tune）、採用したグリッドへの遡及 U 操作、内部リファクタリング
v0.3	TypeScript ラッパー、最初の API バックエンド — Fal 経由の Flux + Flux Kontext、Ideogram
v0.4	Google Imagen、Recraft（ネイティブのベクター/SVG）
v0.5	OpenAI gpt-image、Stable Diffusion
v1.0	API の安定化、本番環境で3つ以上のバックエンドを稼働

すべてのバックエンドが1つのインターフェースを実装するため、後のリリースではそれらを連携させ、あるプロバイダーで生成し、2つ目のプロバイダー（例：Flux Kontext）で調整し、3つ目のプロバイダーでアップスケールできます。

---

リポジトリの構成

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, ...

---

免責事項

このツールは、Discord ユーザーアカウントを通じて Midjourney を自動操作します。Midjourney の有料サブスクリプションが必要です。Discord と Midjourney の利用規約はいずれも、ユーザーアカウントの自動操作を禁止しています。これは、すべてのオープンソースの MJ ツール（midjourney-proxy、midjourney-api など）で使われているのと同じ仕組みです。Midjourney の公開 API はありません。ご自身の責任でご利用ください。

バックエンドインターフェースはプラグインで拡張できます。Flux、DALL-E、Imagen はロードマップに掲載されています。

ライセンス

Apache-2.0。詳細はLICENSEをご覧ください。