AI 에이전트와 MCP 자동화

cbe-mcp는 외부 에이전트가 CBE 데스크톱 앱으로 프로젝트 생성, 기획, Sketch → Coloring → Book → Assets → Videos 작업을 수행하게 하는 로컬 MCP 서버입니다. 에이전트가 사용자 브리프를 바탕으로 기획안을 작성하고 CBE가 실행합니다. 작업 중에는 앱과 데스크톱 세션을 유지하세요.

앱 내부의 AutoMate 대시보드도 제작을 자동화합니다. 커서 시뮬레이션은 대화형 사용과 데모용이며, MCP는 결과 파일을 검사하고 진행 상황을 조회하는 무인 파이프라인을 사용합니다.

클라이언트 연결

CBE를 먼저 설치해 동봉된 MCP 실행 파일을 준비한 뒤, 로컬 stdio 서버를 클라이언트에 등록하고 다시 연결하세요. 아래는 Windows 패키지 설치 예시입니다.

{
  "mcpServers": {
    "cbe": { "command": "cbe-mcp" }
  }
}

명령을 찾지 못하면 Windows 설정의 앱 실행 별칭을 확인하거나 %LOCALAPPDATA%\Microsoft\WindowsApps\cbe-mcp.exe를 실제 사용자 경로로 풀어 지정하세요. 업데이트 때 바뀌는 Program Files\WindowsApps 안의 버전별 경로는 사용하지 마세요.

macOS에서는 일반적으로 /Applications/Coloring Book Engine.app/Contents/MacOS/cbe-mcp를 command로 지정합니다. 다른 위치에 설치했다면 경로를 바꾸세요. 자동 설치·실행은 Windows와 macOS에 구현되어 있습니다. Linux 설치 앱의 자동 설치·실행은 아직 sidecar에 구현되어 있지 않습니다. Linux 개발 실행에는 소스 체크아웃과 CBE_MCP_DEV=1이 필요합니다.

이 예시는 mcpServers JSON을 받는 클라이언트용입니다. 클라이언트별 등록 형식은 다를 수 있습니다. 공개 HTTPS MCP 주소가 아닌 로컬 stdio 서버이므로, 브라우저 전용 에이전트에는 별도의 호환 로컬 연결 수단이 필요합니다. 설정 JSON에 API 키나 라이선스 키를 넣지 마세요.

실행 전 준비 상태

먼저 cbe_status를 호출합니다. 실행 중인 앱에는 연결하지만 앱을 새로 실행하지는 않습니다. 필요하면 cbe_setup {}로 실행·연결합니다. sidecar가 이미 있는 환경에서는 cbe_setup {"install":true}로 앱 설치·업데이트를 요청할 수도 있습니다.

점검	확인할 응답
연결	`attached=true`, `attach_error` 없음
호환성	`protocol_compatible=true`; 거짓이거나 없으면 앱과 sidecar 버전 확인
라이선스	`onboarding.licensed=true`, Trial 여부는 `onboarding.trial`
작업별 AI	실행할 작업의 `onboarding.taskModes` 확인
API	선택한 제공자와 `onboarding.keys`; 저장된 키가 실제 요청 성공을 보장하지는 않음
OAuth	`onboarding.oauth.ready=true`; 로그인 필요 시 메시지에 따라 진행
로컬 AI	`onboarding.localSupported=true`, `onboarding.modelsAllComplete=true`
프로젝트	대상 프로젝트를 열고 브레인스톰·기획표·이미지 풀을 읽은 뒤 수정

onboarding.ready=true는 브리지가 응답했다는 뜻이며 전체 생성 준비 완료 판정이 아닙니다. 누락되거나 알 수 없는 필드는 통과로 판단하지 않습니다. 선택한 제공자나 로컬 런타임의 실제 작동 여부는 소규모 실행으로 확인해야 합니다.

기존 설정을 재사용하세요. 비밀 키는 앱 설정에 직접 입력하는 편이 좋습니다. MCP 인자로 전달하면 클라이언트 대화 기록에도 남을 수 있습니다. OAuth 로그인은 사용자의 직접 조작이 필요할 수 있습니다. 설정 작업이 시작되면 cbe_setup_status를 done=true까지 조회하되, error가 발생하면 원인을 해결하세요. 이후 cbe_status를 다시 확인합니다. 모델 다운로드 중에는 설정 작업을 중복 시작하지 않습니다.

에이전트에게 줄 브리프

프로젝트명, 주제, 독자, 난이도, 스타일, 특별한 요소, 페이지 수(20–200), 판형, 저장 폴더, 실행할 단계를 알려 주세요. 참조 이미지는 로컬 파일 경로가 필요합니다.

6–9세용 숲속 동물 컬러링북을 20페이지, 8.5×11인치로 만들어 줘. 굵고 단순한 윤곽선에 페이지당 한 장면으로 구성해 줘. 기존 AI 설정을 사용하고 먼저 Sketch만 실행해 줘. 재개할 때 완성된 결과는 유지하고 프로젝트 경로, 실제 처리한 페이지 범위, 오류를 알려 줘.

에이전트는 상태 확인 → 프로젝트 생성·열기 → 선택적 참조 이미지 추가 → 브레인스톰 5개 필드 작성 → 페이지별 기획 → 파이프라인 순서로 진행합니다. 선화 프롬프트는 Single full-page scene. 같은 구도 선언으로 시작하고 색상 표현을 제외합니다. 개체 참조는 이미지 풀의 정확한 {Label} 토큰을 사용합니다. 색상 프롬프트는 생략하면 자동 작성할 수 있습니다.

유효한 Trial과 유료 라이선스 모두 MCP를 사용할 수 있습니다. Trial 콘텐츠 작업은 1–6페이지이며 내보내기에 워터마크가 적용됩니다. 20페이지 프로젝트를 만들었다고 20페이지 전체를 생성한 것은 아닙니다. 기획 조회 응답에서 편집 가능 범위를 확인하고 잠긴 행은 보존합니다.

실행·조회·복구

첫 실행은 작게 시작합니다. 아래 인자를 cbe_run_pipeline에 전달하세요.

{"stages":["sketch"],"skip_completed":true,"palette":1}

단계는 sketch, coloring, book, assets, videos입니다. 뒤 단계에는 앞 단계의 결과물이 필요합니다. 기본은 헤드리스 실행이라 마우스·키보드를 점유하지 않고 CBE 창이 뒤에 있거나 최소화돼도 계속 진행합니다. simulate=true는 촬영용 데모 모드로, 실제 커서와 키 입력으로 UI를 조작하므로 사용자가 명시적으로 원할 때만 씁니다. cbe_pipeline_status를 5–10초 간격으로 조회하고, 이전 응답의 nextCursor를 다음 cursor로 전달합니다. 최초 값은 0입니다.

성공은 done=true, running=false, 오류·취소 없음으로 판단합니다. 시작 응답이나 전체 진행률만으로 완료를 보고하지 않습니다.
오류는 errorDetails와 다음 행동 안내를 확인합니다. 인증·라이선스 오류를 반복 재시도하지 말고 원인부터 해결합니다.
skip_completed=true는 유효한 완료 파일을 유지하고 누락·손상 결과를 다시 만듭니다. 재생성이나 이미 진행 중인 API 요청에는 비용이 발생할 수 있습니다. false는 선택한 단계의 재생성을 요청합니다.
cbe_cancel은 작업 사이에 취소합니다. 진행 중인 작업이 끝날 수 있으므로 running=false까지 조회합니다.
sidecar만 재연결했다면 연결 후 조회를 이어갑니다. 앱을 재시작했다면 프로젝트를 다시 열고 재개 옵션으로 실행해 디스크에서 진행 상태를 복원합니다.

최근 실행 기록은 프로젝트의 .cbe/pipeline-run.json에 있습니다. logPath와 logError를 확인하세요. 파일 검사는 구조적 무결성 확인이며 그림 품질이나 출판 승인을 보장하지 않습니다. 배포 전 실제 PDF·이미지·영상을 검토하세요. 이 흐름에서 KDP 업로드나 출판을 수행하지는 않습니다.

표지 편집

별도 표지 작업에는 cbe_cover_templates, cbe_cover_design을 사용합니다. 변경 전에 상태를 읽고, 도구가 템플릿 변경 확인을 요구하면 그 절차를 따릅니다. 개별 생성 작업을 완료까지 조회한 뒤 저장·내보내기 하세요. 표지를 생성하는 중에는 파이프라인을 시작하지 않습니다. 상세 표지 작업 지침은 MCP 서버가 클라이언트에 제공합니다.