ArtCraft MCP 서버 및 자동화 스위트
Protocol: MCP
Language: Rust
Python: 3.10+
License: Apache-2.0
ArtCraft 생성 미디어 플랫폼의 모든 Model Context Protocol (MCP) 서버 구현, 자동화 CLI 도구, 에이전트 스킬, JSON-RPC 스키마 및 보조 브릿지 경로를 묶어 놓은 독립형 저장소입니다.
본 프로젝트는 AI 코딩 어시스턴트(Claude Desktop, Windsurf, Cursor, Antigravity, OpenClaw)가 자연어 명령이나 자동화된 스크립트를 통해 이미지, 비디오, 3D 메시, 가우시안 스플랫, TTS를 네이티브하게 생성하고 미디어 에셋을 관리할 수 있도록 지원합니다.
📁 프로젝트 구조
artcraft-mcp/
├── bin/ # 독립형, 실행 가능한 64비트 Windows 바이너리
│ └── artcraft-mcp.exe # 전체 기능의 ArtCraft MCP 서버
...
⚡ 빠른 시작 (Quick Start)
1. 원클릭 설정 (자동)
포함된 구성 스크립트를 실행하여 Claude Desktop, Windsurf 또는 Cursor 전반에 걸쳐 artcraft-mcp를 자동 감지하고 등록합니다:
2. 수동 설정
MCP 클라이언트 구성 파일(예: claude_desktop_config.json 또는 ~/.codeium/windsurf/mcp_config.json)에 추가합니다:
{
"mcpServers": {
"artcraft": {
...
🔑 인증 (Authentication)
서버는 다음 순서로 자격 증명(credentials)을 확인합니다:
ARTCRAFT_MCP_PRIVATE_SESSION_TOKEN: 전용 MCP 세션 Bearer 토큰 (mcp_session_private_...).
ARTCRAFT_API_KEY: 활성 세션을 위해 POST /v1/mcp/session/create를 통해 자동으로 교환됩니다.
ARTCRAFT_SESSION 및 ARTCRAFT_AVT: 세션 쿠키 환경 변수.
- 자격 증명 파일 (Credential Files):
~/Artcraft/credentials/에서 자동 감지됩니다:
artcraft_session.txt — 사용자 세션 쿠키
artcraft_avt.txt — 방문자(visitor) 쿠키
- ArtCraft 데스크톱 앱 스토어:
%LOCALAPPDATA%\ai.artcraft.app\.cookies에서 자동 감지됩니다.
🛠️ CLI 자동화 스위트
tools/ 내의 모든 스크립트는 외부 서버가 필요 없이 stdio JSON-RPC를 통해 bin/artcraft-mcp-server.exe와 직접 통신합니다:
크레딧 및 생성 비용 확인 (Check Credits & Generation Costs)
python tools/artcraft_cost_estimator.py --check-balance --video-model seedance_2p0 --duration 5
배치 이미지 및 비디오 생성 (Batch Image & Video Generation)
python tools/artcraft_runner.py \
--prompt "Cinematic cyberpunk alleyway at dusk, anamorphic lens, neon reflections" \
--model flux_1_dev \
...
Hunyuan 3D 메시 및 가우시안 스플래팅 생성 (Hunyuan 3D Mesh & Gaussian Splat Generation)
python tools/artcraft_3d_runner.py \
--image "path/to/character.png" \
--mode both \
...
4분면 카메라 오빗 패스 (4-Quadrant Camera Orbit Pass)
python tools/artcraft_angle_matrix.py \
--image "path/to/subject.png" \
--prompt "Maintain facial details during camera orbit" \
...
🤖 AI 에이전트 스킬 (AI Agent Skills)
에이전트 스킬 및 프롬프트 가이드는 skills/artcraft-mcp/에 제공됩니다:
SKILL.md: LLM 에이전트를 위한 행동 지침, 매개변수 스키마 및 오류 처리 방법.
references/: 다음 항목들에 대한 모델 기능 테이블, 종횡비 규칙 및 지속 시간 제한:
- 이미지 (Image): Flux 1 Dev/Schnell, Flux Pro 1.1 Ultra, Nano Banana Pro, Seedream 4/4.5/5, Midjourney 7/8.
- 비디오 (Video): Kling (3.0/2.6/2.1), Veo (3/3.1), Seedance (2.0/1.5), Sora 2, Grok Imagine Video.
- 3D 및 스플래팅 (3D & Splat): Hunyuan 3D 2.0/2.1, WorldLabs Marble Gaussian Splatting.
🖥️ 컴패니언 API 브릿지 (Companion API Bridge)
MCP 서버를 관리되는 서브프로세스로 통합하는 애플리케이션의 경우, companion/mcp_routes.py가 FastAPI 엔드포인트를 제공합니다:
GET /api/mcp/health — 프로세스 상태 및 PID 확인.
POST /api/mcp/start — stdio 파이프를 사용하여 바이너리 시작 (Spawn).
POST /api/mcp/stop — 프로세스를 우아하게 종료하거나 강제 종료 (Terminate or kill).
POST /api/mcp/token — API 키/쿠키를 MCP 세션 토큰으로 교환.
📜 문서화 (Documentation)