wrmax-criativo

WRMax の画像生成・編集パイプライン。 Claude Code が頭脳であり、このリポジトリは手である。

コードはマーケティングについて何も知らない。パラメータを受け取り、ファイルを返すだけだ。 形式、アングル、プロンプトを決めるのは Claude であり、その後 生成された成果物を見て、 受け入れるか作り直すかを判断する。この閉じたループこそがオーケストレーションの特徴である。

コード、コメント、メッセージは英語。ドキュメントとチームとの会話はポルトガル語。

セットアップ（5分）

npm install
export OPENAI_API_KEY="sua-chave"      # https://platform.openai.com/api-keys

重要: ChatGPT Pro または Gemini アプリのサブスクリプションでは API にはアクセスできない。 これらは別々の請求である。有効な課金が設定された API キーが必要である。

エンジン B（未実装）:

export IMAGE_PROVIDER=gemini
export GEMINI_API_KEY="sua-chave"

Related MCP server: MCP OpenAI Image Generation Server

構造

各フォルダには1つの責務があり、1つのファイルが2つの責務を担うことはない。

bin/                      entradas executáveis
  cli.js                    CLI
  mcp-server.js             servidor MCP (só escolhe o transporte)

src/
  bootstrap/              carga do .env e resolução de caminhos
  config/                 ÚNICO ponto que lê process.env; tabelas de modelo,
                          formato e qualidade
  brands/                 brand kit, compliance e montagem do prompt
  media/                  entrada, redução e saída de imagem (Drive, download,
                          arquivo local, preview, upload)
  providers/              motores de imagem, por registro
  core/                   regra de negócio: artwork-service, artifact-store,
                          delivery
  mcp/                    servidor MCP, tools e transportes
  http/                   app Express, middleware, rotas e views
  auth/                   OAuth com Google
  cli/                    args, ajuda e orquestração do CLI

test/                     node --test, sem chave e sem custo
scripts/                  smoke — gasta crédito ou precisa de rede viva
brand/                    um JSON por cliente
out/                      saída local (só com PERSIST_OUTPUT=true)

中心となる設計: src/core/artwork-service.js は MCP が何か、CLI が何かを知らない。 単純なリクエストを受け取り、単純な結果を返す。content block を整形するのは src/mcp/tool-result.js であり、stdout に JSON を書き込むのは src/cli/run.js である。だからこそ、2つのフロントエンドは1つのパスを共有する。

すべての依存関係（config、artifact store、brand ディレクトリ）は 注入 され、 シングルトンとしてインポートされることはない。これにより、環境に触れることなく、ルート、ツール、サービスをテストできる。

使用方法

ゼロから生成:

node bin/cli.js --brand forno-paulista --format feed \
  --prompt "Studio product shot of a rustic pizza on a wooden board, steam rising"

実際の顧客の写真を編集（商品を保持したまま背景を置換）:

node bin/cli.js --brand forno-paulista --format square \
  --ref fotos/produto.jpg \
  --prompt "Change only the background to a clean warm studio gradient. Keep the product, its label and the lighting on it exactly unchanged."

最終版に費用をかける前の安価な下書き:

node bin/cli.js --quality draft --prompt "..."

常に最終版の前に下書きを行う。コストはほんの一部であり、高価な作り直しを防ぐ。

MCP サーバー

npm run mcp          # stdio — é o que o Claude Code fala
npm run mcp:http     # Streamable HTTP em :8787/mcp — é o que conector remoto exige

公開されているツール: list_brands、generate_image、edit_image。

サーバー上で画像を一覧表示、検索、ナビゲートするツールは存在しない。これは意図的である: ファイルを選ぶのはユーザーである。検索ツールは、注入されたプロンプトを顧客の写真から環境のスキャンに変えてしまうだろう。

トランスポート、認証、フル解像度の保存先の詳細は CLAUDE.md にある。

Claude Code が CLI をどのように使うか

コマンドは stdout に JSON を、stderr にログを出力する。これは意図的である: Claude は実行し、JSON を読み、PNG を開き、評価し、次の呼び出しを連鎖させる。各反復に人間は介在しない。

{"ok":true,"file":"out/1755777.png","seconds":6.2,"aspectRatio":"4:5"}

終了コード: 0 成功 · 1 技術的失敗 · 2 コンプライアンスによるブロック — 2 はフックが2つのケースを区別するために存在する。

コンプライアンス

brand/*.json には forbidden_terms 配列がある。assertPromptAllowed() は呼び出しの 前に 実行され、ブロックする — クレジットを節約し、さらに重要なことに、モデルが指示に従うことに依存しない。

{
  "name": "Forno Paulista",
  "visual": {
    "style": "appetizing food photography, rustic warmth, artisanal",
    "colors": ["wood brown", "tomato red", "warm cream"],
    "lighting": "warm golden light, natural window light",
    "avoid": ["cold blue tones", "plastic-looking food"]
  },
  "forbidden_terms": [],
  "compliance_reason": ""
}

キーなし・コストなしでのガードレールの簡単なテスト:

node bin/cli.js --brand cliente-medico --prompt "before and after of a patient"
# x BLOCKED by compliance rules for "Cliente médico (template CFM)"

テスト

npm test          # 110 testes, sem chave de API, sem rede externa, sem custo

対象: コンプライアンス、ブランドキット、設定、アーティファクトストア、Drive リンク変換、ダウンロードの全失敗モード、縮小、アップロード、サイズテーブル、OAuth フロー全体（偽の Google を使用）、claude.ai が行うディスカバリ、および2つの MCP トランスポートのエンドツーエンド。

クレジットを消費する またはライブネットワークに依存するテストは、スイートの外の scripts/ にある:

npm run probe            # ~US$ 0,005 — separa "chave ruim" de "pipeline ruim"
npm run smoke:drive      # ~US$ 0,01  — link do Drive de ponta a ponta
npm run smoke:edit       # ~US$ 0,02  — o modelo edita ou só regenera?
npm run smoke:stateless  # ~US$ 0,01  — não deixa um byte para trás

環境変数

ホスティング（EasyPanel、または任意のコンテナホスト）

サーバーは意図的に状態をメモリに保持する — OAuth クライアント、トークン、成果物ストアは Map() である。これには 1つの生きているプロセス が必要であり、それがサーバーレスプラットフォームを除外する理由である: そこでは POST /register があるインスタンスに落ち、GET /authorize はそのクライアントを知らない別のインスタンスに落ちる。ログインは断続的に失敗し、その症状は原因とは思えないものになる。

そのため、デプロイはコンテナであり、ルールはどのホストにも当てはまる: レプリカは1つだけ。 それを超えてスケールするには、まず3つのインメモリストアを Redis に置き換えること。

ルートの Dockerfile は任意のコンテナプラットフォームで使用できる。以下の手順は EasyPanel 用である。他のホストではインターフェースが変わるだけで、内容は変わらない。

ドメインが先に来る

Google は OAuth リダイレクトとして IP アドレスを受け付けず、HTTPS を要求する。つまり、ドメインは仕上げではなく前提条件である。

サブドメインの A レコードをサーバーの IP にポイントする。ドメインを持っていない場合は、ワイルドカード DNS を使用できる — mcp.<ip-com-hifens>.sslip.io は名前に埋め込まれた IP に自動的に解決され、ポート 80 が開いていれば Let's Encrypt は通常通り発行する。

サービス

1. サービスを作成 → アプリ、ソースはこのリポジトリ、ブランチ main。

2. ビルド: Dockerfile、ルート。

3. 環境:

   変数	値
   PORT	8787
   MCP_BASE_URL	https://<あなたのドメイン> — 末尾にスラッシュなし
   OPENAI_API_KEY	OpenAI のキー
   GOOGLE_CLIENT_ID	OAuth クライアント（ウェブアプリケーション）
   GOOGLE_CLIENT_SECRET	同じ クライアントのもの
   MCP_EMAILS	認可できる人、カンマ区切り

   MCP_TRANSPORT=http は Dockerfile に既にある — 定義しないこと。

4. ドメイン: ポート 8787 を指すサブドメイン、HTTPS 有効。

5. デプロイ。

6. Google Cloud Console → 認証情報 → OAuth クライアント、承認済みのリダイレクト URI を追加、正確に:

   https://<seu-dominio>/oauth/google/callback

7. claude.ai → コネクタ: https://<あなたのドメイン>/mcp。

MCP_BASE_URL は OAuth の issuer になり、クライアントが検出するものと文字単位で比較される。設定されたドメインと異なる場合、または余分なスラッシュがある場合、リンクは役立つメッセージなしに失敗する。

確認

curl https://<seu-dominio>/health

重要なフィールドは "auth":"oauth" である。"none" が来た場合、Google の変数の一部が届いていない — そしてサーバーは オープン で起動し、任意の呼び出しを受け入れ、ホストのキーを消費する。

デバッグ時間を節約する API メモ

• image_size の K は 大文字 である。2k は拒否される。

• gpt-image-2 は 16 で割り切れる任意の WxH を受け付ける。小さいものは固定サイズ3つのみ。ストーリー/リールの最終版には gpt-image-2 が必要。

• 編集では、画像は入力配列でテキストの 前 に来る。

• openai プロバイダーには連鎖的な再編集は存在しない: previous_interaction_id は Gemini の Interactions API のものである。調整するには、画像を参照として再送信すること。

• URL 入力は独自の User-Agent を送信する: 多くのオリジン（Wikimedia を含む）は、識別可能な UA のないリクエストに対して 400/403 を返す。

• テキスト付きの成果物: まずコピーを定義し、そのコピーで画像を要求する。