AI Agents
MCP 도구 참조
SimpliGen MCP 서버가 AI 에이전트에 제공하는 도구와 그 뒤의 로컬 Control API입니다.
SimpliGen은 MCP 서버(@simpligen/mcp)를 제공하며, 이는 AI 에이전트를 로컬의 토큰 인증 연결을 통해 실행 중인 SimpliGen 앱에 연결합니다. 에이전트가 MCP 도구를 호출하면 서버가 이를 앱의 로컬 Control API로 전달합니다. 설정 방법은 에이전트 연결을 참고하세요.
도구
| 도구 | 기능 |
|---|---|
list_capabilities | 에이전트가 생성할 수 있는 모든 프리셋(이미지 또는 동영상), 입력값과 옵션, 로컬 준비 상태, 클라우드 지원 가능 여부 및 크레딧 비용을 나열합니다. |
get_status | 엔진 상태, 클라우드 연결 여부, 크레딧 잔액, 활성 프로젝트, characters 기능 블록(활성화 플래그, 기본/편집/i2v 설치된 프리셋 수, enhancePresets 즉 설치된 업스케일 프리셋 수)을 보고합니다. |
start_engine | 로컬 엔진이 아직 실행 중이 아니면 시작합니다. 엔진 상태를 반환합니다. 콜드 부트가 호출 시간을 초과하면 engineStarting이 true이고 get_status는 준비 완료 시점을 보고합니다. 엔진이 이미 실행 중이면 아무것도 하지 않으며, 누락된 엔진을 설치하지 않습니다(커넥터 0.3.0 이상). |
stop_engine | 로컬 엔진을 중지하고 VRAM을 해제합니다. 클라우드 생성에는 영향을 주지 않습니다(커넥터 0.3.0 이상). |
restart_engine | 사용자 정의 노드를 설치하거나 제거한 후 또는 엔진이 중단되었을 때 로컬 엔진을 다시 시작합니다(커넥터 0.3.0 이상). |
list_projects | 프로젝트(생성 작업을 보관하는 컨테이너)를 나열합니다. |
create_project | 새 프로젝트를 만듭니다. |
upload_file | 로컬 이미지 또는 동영상을 업로드하고 generate에 전달할 핸들을 받습니다. |
list_loras | 설치된 사용자 LoRA(이름, 기본 모델, 트리거 단어)를 나열하여 generate에 전달할 수 있습니다. |
generate | 이미지 또는 동영상 생성을 시작합니다. local, cloud, 또는 auto를 선택합니다. 선택적으로 loras: [{ name, weight }](로컬 백엔드, inputs.supportsLoras가 true인 프리셋, 이름은 list_loras 참고) 및 negativePrompt(프리셋의 기본값 뒤에 추가되는 추가 항목, 클라우드 실행 시 프리셋 기본값이 그대로 사용됨)를 전달할 수 있습니다. options는 명명된 필드(steps, cfg, seed, resolution, aspectRatio, durationSeconds)와 프리셋이 list_capabilities → options.controls 아래에 선언한 모든 고급 제어(예: unlock, shift 또는 high_steps)를 최상위 키로 사용합니다(커넥터 0.2.0 이상). 작업 id를 반환합니다. |
get_prompt_guide | 프리셋의 프롬프트를 작성하기 전에 해당 프리셋(presetId)의 프롬프팅 가이드를 읽습니다. 모델이 프롬프트를 읽는 방식, 구조, 길이, 카메라 및 모션 표현, 부정, 캐릭터 표현 및 예시를 포함합니다. 응답에는 family, generic(모델별 가이드가 없을 때 true) 및 가이드 text가 포함됩니다. 커넥터 0.6.0 이상, generate는 에이전트에 먼저 이를 호출하도록 지시합니다. |
get_job | 작업 상태 및 결과(완료되면 출력 경로 포함)를 가져옵니다. |
wait_for_result | 작업이 완료, 실패 또는 시간 초과될 때까지 기다립니다. |
list_jobs | 최근 생성 작업을 나열합니다. |
cancel_job | 대기열에 있거나 실행 중인 작업을 취소합니다. |
prepare_preset | 로컬 프리셋의 모델 다운로드를 시작하여 실행 가능한 상태가 되도록 합니다. |
get_result_image | 완료된 작업의 이미지를 인라인으로 반환하여 조회합니다. 동영상 결과는 파일 경로를 반환합니다. |
list_recipe_blocks | 레시피 작성용 구성 요소를 나열합니다. 진입점(이미지 또는 동영상 생성, 이미지 편집, 업스케일) 및 단계로 사용 가능한 모든 프리셋과 각각의 포트 계약(필요한 입력, 생성되는 것, 맞는 진입점)을 포함합니다. |
compose_recipe | 상위 수준 사양(프리셋에 고정된 순서 단계 및 입력)에서 새 레시피를 작성하고 임시 저장합니다. SimpliGen이 포트, 단계별 미디어 체인 및 단계별 프롬프트 입력을 자동으로 연결한 후 검증합니다. 레시피 id와 검증을 반환합니다. |
validate_recipe | 저장하지 않고 레시피 사양(또는 원본 구성)의 드라이 실행을 수행하고 수정할 정확한 오류를 받습니다. |
list_recipes | 이 기기에 저장된 레시피 임시 저장본을 나열합니다. |
get_recipe | 저장된 레시피와 id별 전체 구성을 가져옵니다. |
publish_recipe | 저장된 레시피를 Creator Marketplace에 제출합니다(수동 검토 대기 중). 연결된 계정이 필요하며, 일회성 토큰 가격이 설정되지 않으면 무료로 게시됩니다. |
run_recipe | 설치된 레시피(UGC Studio 및 Product Studio의 레시피 또는 임시 저장본)를 입력이 채워진 상태로 실행합니다. subject 입력은 캐릭터 또는 제품 id를 사용하고, 미디어 입력은 업로드 핸들을 사용하며, 텍스트 및 선택 입력은 일반 값을 사용합니다. Studio에서 Generate를 클릭하는 것과 동일한 파이프라인입니다. 실행 id를 반환합니다. |
get_recipe_run | 레시피 실행 상태: 전체 상태, 각 단계별 상태 및 결과, 완료 후 최종 결과 경로. |
wait_for_recipe_run | 레시피 실행이 완료될 때까지(또는 시간 초과 후) 대기하고 최종 실행을 반환합니다. |
list_recipe_runs | 레시피의 최근 실행과 상태 및 결과. |
cancel_recipe_run | 실행 중인 레시피를 중지합니다. 더 이상 단계가 시작되지 않으며, 진행 중인 로컬 단계는 중단됩니다. |
list_subjects | 레시피의 subject 입력이 사용할 수 있는 모든 subject: 캐릭터 및 제품(id 포함). |
list_products | 이 기기에 저장된 제품. |
create_product | 업로드된 사진에서 제품을 저장합니다(이름, 설명, 카테고리). Product Studio 및 UGC 레시피에서 사용할 수 있습니다. 제품 id를 반환합니다. |
remove_product | 제품 및 해당 사진을 삭제합니다. |
list_characters | Character Studio의 모든 활성 캐릭터를 나열합니다. |
get_character | id별 단일 캐릭터의 세부정보 및 이미지를 가져옵니다. |
list_character_features | 모든 신원 특성(피부색, 머리 등)과 옵션을 나열하여 설명으로 캐릭터를 만들 때 사용합니다. |
list_character_presets | 각 캐릭터 역할에 사용 가능한 설치된 프리셋을 나열합니다. 기본 초상화 생성, 신원 편집, 이미지-동영상 애니메이션, 향상(업스케일)을 포함합니다. 각 향상 프리셋은 supportedScales 배열을 포함합니다. |
create_character | 새 캐릭터를 만듭니다. 세 가지 경로를 지원합니다. 설명(특성 선택에서 기본 초상화 생성), 업로드(사용자 이미지를 기본으로 사용), vision-recreate(사용자 사진에서 에이전트가 설명한 특성). 생성 모드에서는 기본 초상화가 준비될 때까지 내부 폴링을 수행하고 준비된 캐릭터 객체를 반환합니다. 업로드 모드에서는 캐릭터가 즉시 준비됩니다. |
generate_character_image | 프롬프트로 기존 캐릭터의 장면 이미지를 생성합니다. 선택적으로 presetId를 허용하여 이 호출에 사용할 신원 편집 프리셋을 선택합니다. 하나 이상의 작업 id를 반환하여 wait_for_result로 폴링합니다. |
generate_character_video | 기존 캐릭터의 애니메이션 동영상 클립을 생성합니다. 선택적으로 framePresetId(프레임 단계용 신원 편집 프리셋) 및 videoPresetId(애니메이트 단계용 i2v 프리셋)를 허용합니다. 프레임 및 애니메이션 단계 모두에 대한 작업 id를 반환합니다. |
generate_character_frame | 애니메이션 없이 캐릭터의 단일 정지 프레임을 생성합니다. 애니메이트하기 전에 프레임을 검토하거나 향상시키려 할 때 유용합니다. 선택적으로 presetId를 허용합니다. { jobIds: [...] }를 반환합니다. jobIds[0]을 프레임 작업 id로 사용합니다. |
animate_character | 완료된 프레임 또는 완료된 모든 이미지 작업에서 캐릭터를 애니메이트합니다. jobId(완료된 생성의 작업 id) 또는 filePath(절대 로컬 이미지 경로)를 전달합니다. 선택적으로 videoPresetId를 허용합니다. 동영상 작업 id를 반환합니다. |
set_character_preset | 캐릭터별 이미지 생성(imagePresetId) 및/또는 동영상 생성(videoPresetId)의 기본 프리셋을 설정합니다. 기본값을 지우려면 null을 전달합니다. generate_character_image 및 generate_character_video에 대한 후속 호출은 호출별로 재정의하지 않는 한 이 기본값을 사용합니다. |
enhance_character_media | 캐릭터 이미지 또는 동영상을 업스케일하거나 향상시킵니다. 소스는 완료된 작업(jobId), 업로드된 파일(filePath 핸들) 또는 캐릭터 기본 초상화(target: 'base')가 될 수 있습니다. scale(업스케일 계수), keepResolution(업스케일 후 더 선명한 동일 크기 결과를 위해 소스 치수로 크기 조정), applyAsBase(캐릭터 기본 초상화를 업스케일된 결과로 바꿈)를 허용합니다. 작업 id를 반환합니다. |
regenerate_character_base | 기존 캐릭터의 기본 초상화를 제자리에서 다시 생성하고, 선택적으로 다른 기본 프리셋으로 전환하거나 신원을 업데이트합니다. 새 캐릭터는 만들어지지 않습니다. 내부 폴링, 자동 수락, 준비된 캐릭터 객체를 반환합니다. 에이전트가 후속으로 작업 id를 폴링할 필요가 없습니다. |
remove_character | 캐릭터 및 관련 데이터를 영구히 삭제합니다. |
list_films | 프로젝트의 Video Studio 영화를 나열합니다(커넥터 0.5.0 이상, 아래의 모든 영화 도구와 동일함). |
create_film | 빈 영화 생성: 모양, 해상도, 렌더링 위치, 샷 유형별 프리셋. 타임라인을 반환합니다. |
get_film | 영화의 타임라인을 읽습니다. 템포, 캐스트, 번호, 초 및 마디로 측정된 시작 및 길이를 포함한 모든 클립, 샷 및 테이크 상태, 트랙, 마커 및 내보내기 범위. |
update_film_settings | 영화의 모양, 해상도, 렌더링 위치, 프리셋, Subject & style, 모든 클립이 상속하는 캐스트 및 위치를 변경합니다. |
add_track | 업로드된 오디오 파일을 타임라인에 배치합니다. 노래, 음악, 대사 또는 효과음. |
move_track | 트랙의 오디오를 이동하거나, 음소거하거나, 볼륨을 설정합니다. |
detect_tempo | 곡에서 영화의 템포 및 마디 선을 설정합니다. 그 이후로 시간은 마디로 주어질 수 있습니다. |
add_clip | 특정 시간에 빈 클립을 추가합니다. |
update_clip | 한 단계로 클립을 작성합니다. 샷(프롬프트, 길이, 말하거나 노래하는 줄, 누가 말하는지, 프레이밍), 캐스트, 위치, 시작 방식(새로 또는 이전 클립에서 계속, none 및 frame도 새로 및 계속으로 수락됨), 들을 트랙, 프리셋. |
move_clip | 클립을 새 시작점이나 다른 동영상 레인으로 이동합니다. |
trim_clip | 클립의 길이를 변경하거나 테이크 내의 시작 위치를 변경합니다. |
remove_clip | 클립을 제거합니다. |
apply_film_plan | 한 단계로 전체 임시 저장본을 배치합니다. 클립이 마디에 있고 샷, 캐스트, 링크를 포함합니다. 모든 문제가 한 번에 반환됩니다. 모든 것이 유효하지 않으면 아무것도 변경되지 않습니다. |
set_fades | 클립 또는 트랙을 페이드 인/아웃합니다. |
add_marker | 눈금자에 명명된 마커를 배치합니다. |
set_export_range | 영화의 일부 또는 전체만 내보냅니다. |
render_clips | 필요한 클립 또는 명명된 클립을 렌더링합니다. 시작된 것, 보류 중인 것, 클라우드 비용을 즉시 반환합니다. |
wait_for_renders | 클립이 렌더링되지 않을 때까지 기다리고 타임라인을 반환합니다. |
list_takes | 클립의 테이크를 나열합니다. |
use_take | 클립의 테이크 중 하나를 표시하는 것으로 만듭니다. |
export_film | 영화를 하나의 동영상으로 음악과 함께 스티칭하고 파일 경로를 반환합니다. |
list_locations | Library의 위치를 나열합니다. |
create_location | 업로드된 사진 또는 완료된 이미지 작업에서 위치를 저장합니다. |
Video Studio에서 영화를 열 때, 에이전트가 수행하는 모든 변경 사항이 즉시 나타나고 Ctrl+Z로 실행 취소됩니다. 완전한 예시는 에이전트가 뮤직 비디오를 만드는 방식을 참고하세요.
연결 방식
에이전트는 stdio를 통해 npx -y @simpligen/mcp로 MCP 서버를 실행합니다. 서버는 페어링 토큰(SIMPLIGEN_TOKEN)으로 앱에 인증하고 앱의 로컬 포트를 자동으로 찾습니다. SimpliGen 앱이 실행 중이어야 합니다. Settings의 "에이전트 연결" 섹션에서 토큰을 생성합니다.
사용자 정의 통합을 구축하고 있나요?
MCP 도구는 모든 언어에서 직접 호출할 수 있는 로컬 HTTP Control API로 전달됩니다. Control API 참조를 참고하세요.
지출 한도
각 토큰은 지출 상한을 포함할 수 있습니다. 빈 상한은 무제한 클라우드 사용을 의미하고, 0은 로컬 생성만을 의미하며, 양수는 클라우드 지출을 해당 크레딧 수로 제한합니다. 로컬 생성은 항상 허용되며 상한에 계산되지 않습니다.