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_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의 레시피, 또는 초안)를 입력이 채워진 상태로 실행합니다. 주체 입력은 문자 또는 제품 id를 가져가고, 미디어 입력은 업로드 핸들을 가져가며, 텍스트 및 선택 입력은 일반 값을 가져갑니다. 스튜디오에서 생성을 클릭하는 것과 동일한 파이프라인입니다. 실행 id를 반환합니다. |
get_recipe_run | 레시피 실행 상태: 전체 상태, 각 단계 및 상태 및 결과, 완료되면 최종 결과 경로. |
wait_for_recipe_run | 레시피 실행이 완료되거나 시간 초과될 때까지 블록하고 최종 실행을 반환합니다. |
list_recipe_runs | 레시피의 최근 실행과 상태 및 결과입니다. |
cancel_recipe_run | 실행 중인 레시피를 중지합니다. 더 이상의 단계는 시작되지 않으며, 로컬 진행 중인 단계는 중단됩니다. |
list_subjects | 레시피의 주체 입력이 가져올 수 있는 모든 주체: 문자 및 제품, 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 | 새로운 문자를 만듭니다. 세 가지 경로를 지원합니다: describe(기능 선택에서 베이스 초상화 생성), upload(자신의 이미지를 베이스로 사용), vision-recreate(사용자 사진에서 에이전트 설명 기능). 생성 모드에서는 도구가 내부적으로 베이스 초상화가 준비될 때까지 폴링하고 준비된 문자 객체를 반환합니다. 업로드 모드에서는 문자가 즉시 준비됩니다. |
generate_character_image | 프롬프트로 기존 문자에 대한 장면 이미지를 생성합니다. 이 호출에 사용할 신원 편집 프리셋을 선택하기 위한 선택적 presetId를 허용합니다. 하나 이상의 작업 id를 반환하며 wait_for_result를 통해 폴링합니다. |
generate_character_video | 기존 문자에 대한 애니메이션 비디오 클립을 생성합니다. 선택적 framePresetId(프레임 단계의 신원 편집 프리셋)와 videoPresetId(애니메이트 단계의 i2v 프리셋)를 허용합니다. 프레임 및 애니메이션 단계 모두에 대한 작업 id를 반환합니다. |
generate_character_frame | 애니메이션하지 않고 문자에 대한 단일 정지 프레임을 생성합니다. 애니메이션하기 전에 프레임을 검토하거나 개선하려는 경우에 유용합니다. 선택적 presetId를 허용합니다. { jobIds: [...] }를 반환하며, 프레임 작업 id로 jobIds[0]을 사용합니다. |
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 | 문자와 관련된 데이터를 영구적으로 삭제합니다. |
연결 방식
에이전트는 stdio로 npx -y @simpligen/mcp를 사용하여 MCP 서버를 실행합니다. 서버는 페어링 토큰(SIMPLIGEN_TOKEN)으로 앱에 인증하고 앱의 로컬 포트를 자동으로 찾습니다. SimpliGen 앱이 실행 중이어야 합니다. 설정에서 "에이전트 연결" 섹션 아래에 토큰을 만듭니다.
맞춤형 통합을 구축 중인가요?
MCP 도구는 모든 언어에서 직접 호출할 수 있는 로컬 HTTP Control API로 전달됩니다. Control API 참조를 참조하세요.
지출 한도
각 토큰은 지출 상한선을 가질 수 있습니다. 빈 상한선은 무제한 클라우드 사용을 의미하고, 0은 로컬 생성만을 의미하며, 양수는 클라우드 지출을 해당 크레딧 수로 제한합니다. 로컬 생성은 항상 허용되며 상한선에 대해 계산되지 않습니다.