<div align="center">

higgsMCP

AI Beauty Influencer Automation — Higgsfield MCP × Claude

AI 뷰티 인플루언서 자동화 파이프라인 · 캐릭터 생성부터 광고 제작, Instagram 게시까지

🌐 Live Landing Page · 🇰🇷 한국어 · 🇺🇸 English

Character Gallery	Character Studio

</div>

---

🇰🇷 한국어

Higgsfield(이미지·영상·음성 통합 생성 플랫폼)를 Claude에 MCP로 연결해 AI 뷰티 인플루언서 캐릭터(Yuna)를 만들고, 콘텐츠 생성부터 Instagram 게시까지 자동화하는 프로젝트입니다.

참고: 조코딩 — AI 뷰티 인플루언서 with Higgsfield

✨ 핵심 개념

개념	설명
MCP 연결	Higgsfield 원격 서버를 Claude 커스텀 커넥터로 연결
Element / Soul	캐릭터 외형을 고정해 일관되게 재현하는 단위 (Yuna)
Product	화장품을 자산으로 등록해 자연스러운 제품 배치에 사용
Predict Virality	콘텐츠 확산 가능성을 사전 점수화
CLI 자동화	무인 콘텐츠 생성 + Instagram 자동 게시

🖥️ AdCast Studio — 원클릭 웹앱

버튼 한 번으로 AI 캐릭터 콘텐츠를 생성하는 다중 캐릭터 스튜디오입니다. (web/)

• 캐릭터 생성·관리 — 이미지 업로드 → 레퍼런스 등록 → 일관된 캐릭터 재현 (별도 학습 불필요)
• 제품 광고 — 제품 이미지를 올리면 캐릭터가 자연스럽게 들고 소개하는 광고 생성
• 프롬프트 쇼츠 — 원하는 내용으로 생성 + AI 바이럴 아이디어 추천
• 검증 & 개선 — 바이럴 점수 + 개선안 → 버튼 한 번으로 개선 재생성
• 이미지 → 영상 — 생성 이미지를 릴스/쇼츠용 영상으로

cp .env.example .env      # Higgsfield API 키 입력 (HF_KEY_ID / HF_KEY_SECRET)
docker compose up --build # → http://localhost:8100

자세한 내용: web/README.md

🔄 전체 워크플로 (4단계)

1. 캐릭터 셋업 — 후보 이미지 생성 → Yuna를 Element/Soul로 등록 → 다각도 보강
2. Before/After 영상 — 셀카 변형 → 메이크업 i2i 변환 → 전환 애니메이션
3. 제품 광고 — 제품 등록 → Element+Product 합성 → 음성 더빙 애니메이트
4. 자동화 운영 — CLI로 주기적 생성 → Instagram 자동 게시

📁 디렉터리 구조

higgsMCP/
├── web/                  # 🖥️ AdCast Studio 웹앱 (FastAPI + 정적 UI, Docker)
│   ├── backend/          #    app.py · higgsfield.py · verify.py · recommend.py ...
│   ├── frontend/         #    index.html · character.html · app.js · styles.css
│   └── Dockerfile
├── docs/                 # 📚 문서 + GitHub Pages 랜딩
│   ├── index.html        #    랜딩 페이지 (GitHub Pages)
│   ├── screenshots/      #    웹앱 스크린샷
│   ├── 01-higgsfield-mcp-연결.md
│   ├── 02-워크플로.md
│   ├── 03-캐릭터-기획.md
│   └── 04-instagram-게시-셋업.md
├── prompts/              # ♻️ 재사용 프롬프트 템플릿 (캐릭터/비포애프터/제품광고)
├── scripts/              # 🤖 CLI 자동화 (생성 → Instagram 게시 → 스케줄러)
├── assets/               # 🎨 캐릭터 Element·제품 자산·생성 결과물
├── config/               # ⚙️ 설정 템플릿
└── docker-compose.yml

🚀 시작하기

1. MCP 연결 — docs/01-higgsfield-mcp-연결.md 따라 Higgsfield 커넥터 추가
2. 설정 — config/config.example.json → config/config.json 복사 후 값 입력
3. 캐릭터 생성 — docs/02-워크플로.md의 1단계 수행
4. 자동화 — scripts/scheduler.py로 주기 실행

✅ 진행 상태

• [x] Higgsfield MCP 커넥터 연결 (OAuth 인증 완료)
• [x] Yuna 캐릭터 셋업 — Soul 학습 완료 (status=ready)
• [x] 정체성 재현 검증 (데일리 셀카)
• [x] AdCast Studio 웹앱 — 캐릭터 생성→쇼츠 생성→검증→추천 전 과정 실동작 확인
• [ ] Before/After 메이크업 영상 (워크플로 2단계)
• [ ] 제품 자산 등록 + 제품 광고 (워크플로 3단계)
• [ ] Instagram Graph API 토큰 발급
• [ ] 자동화 파이프라인 검증

---

🇺🇸 English

This project connects Higgsfield (an all-in-one image · video · voice generation platform) to Claude via MCP, creating an AI beauty influencer character (Yuna) and automating everything from content generation to Instagram publishing.

✨ Core Concepts

Concept	Description
MCP Connection	Higgsfield remote server connected as a Claude custom connector
Element / Soul	A unit that locks a character's appearance for consistent reproduction (Yuna)
Product	Register cosmetics as assets for natural product placement
Predict Virality	Pre-score content for viral potential
CLI Automation	Unattended content generation + automatic Instagram posting

🖥️ AdCast Studio — One-Click Web App

A multi-character studio that generates AI character content in one click. (web/)

• Character CRUD — upload images → register references → consistent reproduction (no training needed)
• Product Ads — upload a product image and the character naturally holds & presents it
• Prompt Shorts — generate from any prompt, with AI-recommended viral ideas
• Verify & Improve — virality score + improvement levers → regenerate in one click
• Image → Video — turn generated images into reels/shorts-ready videos

cp .env.example .env      # add your Higgsfield API key (HF_KEY_ID / HF_KEY_SECRET)
docker compose up --build # → http://localhost:8100

Details: web/README.md

🔄 Full Workflow (4 Stages)

1. Character Setup — generate candidates → register Yuna as Element/Soul → multi-angle reinforcement
2. Before/After Video — selfie variation → makeup i2i transform → transition animation
3. Product Ads — register product → composite Element+Product → voice-dubbed animation
4. Automated Ops — scheduled CLI generation → automatic Instagram publishing

📁 Directory Structure

higgsMCP/
├── web/                  # 🖥️ AdCast Studio web app (FastAPI + static UI, Docker)
│   ├── backend/          #    app.py · higgsfield.py · verify.py · recommend.py ...
│   ├── frontend/         #    index.html · character.html · app.js · styles.css
│   └── Dockerfile
├── docs/                 # 📚 Docs + GitHub Pages landing
│   ├── index.html        #    Landing page (GitHub Pages)
│   ├── screenshots/      #    Web app screenshots
│   └── 01~04-*.md        #    MCP setup · workflow · character planning · Instagram setup
├── prompts/              # ♻️ Reusable prompt templates (character / before-after / product ad)
├── scripts/              # 🤖 CLI automation (generate → post to Instagram → scheduler)
├── assets/               # 🎨 Character elements · product assets · outputs
├── config/               # ⚙️ Config templates
└── docker-compose.yml

🚀 Getting Started

1. Connect MCP — follow docs/01-higgsfield-mcp-연결.md to add the Higgsfield connector
2. Configure — copy config/config.example.json → config/config.json and fill in values
3. Create Character — run stage 1 of docs/02-워크플로.md
4. Automate — run periodically with scripts/scheduler.py

✅ Status

• [x] Higgsfield MCP connector connected (OAuth authenticated)
• [x] Yuna character setup — Soul training complete (status=ready)
• [x] Identity reproduction verified (daily selfies)
• [x] AdCast Studio web app — full flow verified: character creation → shorts generation → verification → recommendations
• [ ] Before/After makeup video (workflow stage 2)
• [ ] Product asset registration + product ads (workflow stage 3)
• [ ] Instagram Graph API token issuance
• [ ] Automation pipeline verification

---

<div align="center">

🌐 Landing Page · Built with Higgsfield MCP × Claude · MIT License

</div>