<div align="center">

# higgsMCP

**AI Beauty Influencer Automation — Higgsfield MCP × Claude**

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

[**🌐 Live Landing Page**](https://hyunaeee.github.io/higgsMCP/) · [🇰🇷 한국어](#-한국어) · [🇺🇸 English](#-english)

![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688?logo=fastapi&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
![Higgsfield](https://img.shields.io/badge/Higgsfield-REST%20%2F%20MCP-b76eff)
![Claude](https://img.shields.io/badge/Claude-MCP-d97757?logo=anthropic&logoColor=white)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

| Character Gallery | Character Studio |
|:---:|:---:|
| ![Character gallery](docs/screenshots/home.png) | ![Character studio](docs/screenshots/character.png) |

</div>

---

## 🇰🇷 한국어

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

> 참고: [조코딩 — AI 뷰티 인플루언서 with Higgsfield](https://wootom.github.io/news/2026-06-29-jocoding-ai-beauty-influencer-higgsfield.html)

### ✨ 핵심 개념

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

### 🖥️ AdCast Studio — 원클릭 웹앱

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

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

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

자세한 내용: [web/README.md](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](docs/01-higgsfield-mcp-연결.md) 따라 Higgsfield 커넥터 추가
2. **설정** — `config/config.example.json` → `config/config.json` 복사 후 값 입력
3. **캐릭터 생성** — [docs/02-워크플로.md](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

```bash
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](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](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](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](https://hyunaeee.github.io/higgsMCP/)** · Built with Higgsfield MCP × Claude · [MIT License](LICENSE)

</div>