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

구조

각 폴더는 하나의 책임을 가지며, 어떤 파일도 두 가지 역할을 겸하지 않습니다.

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입니다. 그래서 두 프런트엔드가 하나의 경로를 공유합니다.

모든 의존성(설정, 아티팩트 저장소, 브랜드 디렉터리)은 주입되며, 싱글턴으로 가져오지 않습니다 — 이를 통해 환경을 건드리지 않고 라우트, 도구, 서비스를 테스트할 수 있습니다.

사용법

처음부터 생성:

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는 훅이 두 경우를 구분할 수 있도록 존재합니다.

컴플라이언스

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가 수행하는 검색, 그리고 두 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()입니다. 이는 하나의 살아있는 단일 프로세스를 요구하며, 이것이 서버리스 플랫폼을 배제하는 이유입니다: 거기서 POST /register는 한 인스턴스에, GET /authorize는 클라이언트를 알지 못하는 다른 인스턴스에 도달할 것입니다. 로그인이 간헐적으로 실패하며, 증상이 원인과 같아 보이지 않습니다.

그래서 배포는 컨테이너이며, 모든 호스트에 적용되는 규칙은 단일 레플리카입니다. 그 이상으로 확장하려면 먼저 세 가지 인메모리 저장소를 Redis로 교체하세요.

루트의 Dockerfile은 모든 컨테이너 플랫폼에서 작동합니다. 아래 단계는 EasyPanel 기준이며, 다른 호스트에서는 인터페이스만 다를 뿐 내용은 같습니다.

도메인이 먼저입니다

Google은 OAuth 리다이렉트로 IP 주소를 허용하지 않으며, HTTPS를 요구합니다. 즉, 도메인은 마무리가 아니라 전제 조건입니다.

서브도메인의 A 레코드를 서버 IP로 지정하세요. 도메인이 없는 경우 와일드카드 DNS를 사용할 수 있습니다 — mcp.<ip-com-hifens>.sslip.io는 이름에 포함된 IP로 자동 해석되며, 80번 포트가 열려 있으면 Let's Encrypt가 정상적으로 발급합니다.

서비스

1. 서비스 생성 → App, 이 저장소를 소스로 하고 main 브랜치를 사용합니다.

2. 빌드: Dockerfile, 루트에 있습니다.

3. 환경:

   변수	값
   PORT	8787
   MCP_BASE_URL	https://<your-domain> — 끝에 슬래시 없음
   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 클라이언트, 승인된 리다이렉트를 정확히 추가합니다:

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

7. claude.ai → 커넥터: https://<your-domain>/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를 허용합니다. 더 작은 크기들은 세 가지 고정 크기만 허용합니다. 최종 스토리/릴스에는 gpt-image-2가 필요합니다.

• 편집에서 이미지는 input 배열에서 텍스트 앞에 옵니다.

• openai 프로바이더에는 연결된 재편집이 없습니다: previous_interaction_id는 Gemini의 Interactions API용입니다. 조정하려면 이미지를 참조로 다시 보내세요.

• URL 입력은 자체 User-Agent를 보냅니다: 여러 소스(Wikimedia 포함)는 식별 가능한 UA가 없는 요청에 400/403을 반환합니다.

• 텍스트가 있는 결과물: 먼저 카피를 정의한 다음, 해당 카피로 이미지를 요청하세요.