Filmsquare 도움말문서

5.0 내 Claude와 일하기5.2 Claude가 할 수 있는 일

Claude가 할 수 있는 일

Filmsquare가 내 Claude에게 주는 모든 MCP 툴, find_actions와 run_action이 나머지 API에 닿는 방법, 일부러 뺀 것을 알려 드려요.

업데이트 6분 분량.md

이 페이지 목차
  1. 이름 붙은 툴
  2. 미디어가 가는 곳
  3. find_actions와 run_action
  4. 예시
  5. API가 거부할 때
  6. 일부러 뺀 것
  7. 안전
  8. 프롬프트

내 Claude는 Filmsquare에서 내 역할로 API가 허용하는 일을 할 수 있어요. 이름 붙은 툴 열여덟 개가 평소 작업을 맡고, find_actions와 run_action 두 개가 나머지 모든 API 액션에 닿아요. 모든 호출은 API를 그대로 거쳐서 내 이름으로 나가요. 같은 역할 확인, 같은 검증, 같은 게이트예요.

이름 붙은 툴 #

툴하는 일필요한 것
whats_waiting내 컨펌을 기다리는 팀 단계와 읽지 않은 알림. 여기서 시작해요—
list_productions워크스페이스의 작품과 에피소드—
get_episode에피소드 하나. 씬과 컷을 편집 순서대로, 팀별 단계 전부(컨펌 완료, 누구를 기다리는지, 수정 요청, 미완료), 파이널을 렌더할 수 있는지episode_id
get_feedback컷, 테이크, 에피소드, 씬, 요소, 폴더, 에셋 버전, 캔버스, 캔버스 박스의 코멘트 스레드. 모든 메시지와 핀(프레임 단위 타임코드나 이미지의 영역)을 포함해요. 기본은 열린 스레드이고, 나머지는 status를 resolved나 all로 지정해요. target_type이 sheet이면 시트 최신 버전의 열린 코멘트(의도, 인용 또는 시트 전체, 제안 텍스트, 처리 여부)와 이전 버전의 코멘트가 어떻게 끝났는지target_type, target_id
reply_feedback스레드에 내 이름으로 답글(@name 멘션은 알림이 가요)을 달고, 코멘트가 처리되면 해결해요. 시트의 코멘트는 해결 대신 처리함으로 표시해요. 제안이 있으면 suggestion_outcome(적용, 수정 적용, 거절)이 필수이고, 확인은 사람이 해요thread_id, body
view_media스틸, 키프레임, 테이크를 Claude가 볼 수 있는 이미지로. 영상은 포스터 이미지와 다운로드 링크로 돌아와요asset_version_id
upload_file대화 속 파일을 컷이나 씬 레이어의 새 테이크로, 또는 작품 에셋으로 넣어요. 최대 10MB. pick: true이면 OK컷으로도 골라요(감독 이상)name, mime, data_base64
where_does_it_go파일이 어느 화면에 들어가야 하는지: 지도, 판단 트리, 실제 예시. 화면 이름을 말할 때 읽어요—
prepare_upload디스크에 있는 파일 최대 100개의 서명된 업로드 URL과 바로 쓸 수 있는 curl 명령. 바이트가 대화를 거치지 않아요. 영상은 모두 이걸로 올려요files
add_to_visualize올린 파일을 Storyboard → 3D나 Storyboard → Animatic에, 컷과 씬에 번호로 맞춰 한 번에 최대 100개 넣어요. 같은 걸 다시 보내도 바뀌는 건 없어요episode_id, items
get_script에피소드의 최신 시나리오 고와, 이미 있는 캐스트, 세트, 소품의 @handlesepisode_id
edit_script시나리오 전체를 보내지 않고 씬, 대사, 한 줄을 고쳐요. 정확히 일치하는 텍스트와 바꿀 내용을 새 버전으로 저장하고, 코멘트와 태그는 따라가요episode_id, base_rev, edits
submit_breakdownClaude의 브레이크다운을 Filmsquare에 넣어요. 씬, 연기가 있는 컷, 대사, 캐스트, 세트, 소품. 그러면 각본이 컨펌을 기다려요episode_id, breakdown
get_continuity에피소드의 연결 시트. 컷마다 재생되는 것, 요소와 그 레퍼런스, 각 OK컷이 무엇으로 만들어졌는지, 지금까지의 결과, 다시 체크할 컷. 먼저 무료 계보 체크를 돌려요episode_id
report_continuity눈으로 본 연결 체크를 기록해요. 어긋난 곳마다 OK컷에 코멘트가 달려요episode_id, seen, issues
submit_style스타일 가이드를 스타일 라이브러리(Create → Styles)에 넣어요. 새 스타일이거나, style_id를 주면 그 스타일의 다음 버전이에요. production_id를 주면 그 작품의 스타일이 돼요. 내 작업에는 레퍼런스 스틸을 6장까지 붙일 수 있어요(prepare_upload로 올려요). 남의 작업은 텍스트만 쓰고 공개하지 않아요. 사람이나 브랜드 이름은 거절돼요. 작업자 역할name, guide
request_signoff팀의 컨펌 담당자에게 에피소드 단계의 컨펌을 요청해요. 담당자에게 알림이 가요episode_id, department
sign_off한 단계에 대한 내 결정을 기록해요. approved 또는 changes_requested, 선택 사항으로 note. 그 단계의 컨펌 담당자만 할 수 있어요. expect_version(내가 본 단계 버전)을 주면 작업이 바뀐 경우 changed_since로 거부돼요. 내가 Claude에게 결정하라고 시켰을 때만episode_id, department, decision
studio_analytics소유자와 프로듀서용이에요. Analytics의 숫자로 보는 스튜디오 현황. view는 crew(기간 동안 사람별: 납품, 납품당 크레딧, 컨펌까지의 시간, 첫 통과율, 레인, 리두, 직접 작업과 에이전트 단독 시간, 스튜디오 중앙값, 단계별 시간), day, costs, report(발송될 모양 그대로의 리포트 메일 텍스트) 중에서요. 다른 사람은 거부되고 자기 숫자만 봐요view

모든 툴은 선택 사항인 workspace도 받아요. 비워 두세요. 연결의 워크스페이스가 쓰여요.

department는 writing, breakdown, casting, voice, wardrobe, sets, props, animatic, music, draft, sound, edit, final 중 하나예요.

미디어가 가는 곳 #

화면 이름은 평소 말투로 Claude에게 알려 주세요(“3D에 넣어 줘”). Claude는 이렇게 처리해요.

가진 것가는 곳방법
한 컷의 클레이 렌더나 스틸(렌즈, 높이, 무빙 포함)Storyboard → 3D, 해당 컷add_to_visualize
컷, 테이크, 씬의 Blender 클립Storyboard → 3D, 그 클립이 덮는 대상add_to_visualize
씬, 시퀀스, 에피소드의 애니매틱Storyboard → Animaticadd_to_visualize
컷의 드래프트나 파이널 영상Storyboard → Shots, 테이크로upload_file
레퍼런스 이미지나 무드 보드Home → Filesupload_file

엉뚱한 곳에 들어간 건 다시 올리지 않고 옮겨요. run_action으로 moveTake나 moveAsset을 써요(감독 이상). 가져오기가 만든 OK컷은 이동과 함께 해제돼요. 누군가 OK컷으로 고른 테이크나 여기서 생성한 테이크는 제자리에 남아요.

find_actions와 run_action #

이름 붙은 툴이 없는 일은 모두 이 둘로 해요. 컷 만들기, OK컷 고르기, 드래프트 만들기, 견적, 요소와 버전, 폴더, 캔버스, 비용, 브리프, 스태프가 해당돼요.

  1. find_actions는 몇 단어로 API 자체의 카탈로그를 검색해요. “pick take”, “create shot”, “resolve thread” 같은 단어요. 맞는 액션을 메서드, 경로, 요약, 최소 역할, 입력과 함께 돌려줘요.
  2. run_action은 액션을 이름으로 실행해요. 액션 설명대로 path_params(워크스페이스는 제외), query, body를 넘겨요. API의 JSON으로 답해요.

find_actions는 현장 용어를 알아들어요. 스태프가 쓰는 단어를 API의 단어로 연결해 줘요. 검색어는 영어 기준이라 아래 표의 단어는 그대로 입력해요.

입력하는 단어함께 검색하는 단어
pick, chooseselect
note, notes, comment, comments, feedbackthread, message
replymessage
rendergeneration, generate
makecreate, generate
new, addcreate
remove, deletearchive
signsignoff
approvesignoff, approval
cast, character, propelement
setelement, location
production, productionsproject
crewmember, steps
costcosts, estimate
priceestimate
prompt, preview, dry rungenerate
kosten, schatting, prijs (네덜란드어)generate, estimate
mismatchcontinuity
model, modelsmodels, acceptance, routing

새 API 액션은 출시되는 즉시 find_actions에 나타나요. 새 툴은 필요 없어요.

예시 #

하고 싶은 일검색어액션
렌더 전에 드래프트 가격 보기“estimate shot”estimateShotGeneration
렌더 전에 프롬프트, 모델, 크레딧 보기“dry run”{"kind": "video", "tier": "draft", "dryRun": true}와 함께 generateForShot
드래프트 렌더“generate shot”{"kind": "video", "tier": "draft"}와 함께 generateForShot
테이크를 OK컷으로 고르기“pick take”selectTake
드래프트를 파이널로 만들기“promote”promoteGeneration
코멘트로 리테이크“revise take”estimateReviseTake, 그다음 reviseTake
어떤 모델이 OK로 이어지는지 보기“model acceptance”getModelAcceptance
에피소드 비용“episode costs”getEpisodeCosts

렌더하기 전에 Claude는 생성 액션을 dryRun: true로 불러요. 컴파일된 프롬프트, 모델, 레퍼런스, 크레딧을 보여 주고 아무것도 만들지 않아요. 그다음 그 렌더 한 번에 한해 프롬프트를 바꿀 수 있어요. overrides.prompt는 프롬프트 텍스트를 바꾸고(레퍼런스 줄은 그대로라서 캐스트, 세트, 소품은 항상 함께 가요), overrides.promptAppend는 덧붙이고, overrides.negativePrompt는 피할 것을 추가해요. 대사는 대사 줄로 낭독하기 때문에 프롬프트 오버라이드를 받지 않아요.

드라이 런은 provider와 model_key로 답해요. 이걸 provider와 modelKey로 다시 넘기면 그 모델이 고정돼요. getGeneration은 테이크가 무엇으로 만들어졌는지 다시 읽어요. 프롬프트, 모델, 예상 크레딧, 기록된 크레딧이에요.

API가 거부할 때 #

거부는 API의 코드와 상세 내용이 담긴 툴 오류로 돌아와요. 예를 들어 The API refused: 409 gate_closed: finals render once casting, sets, animatic are signed off {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}처럼요. Claude가 읽고 무엇이 빠졌는지 알려 줘요. 자주 만나는 오류를 보세요.

일부러 뺀 것 #

Claude는 이런 것에는 닿을 수 없어요. 설계상 그래요.

  • API 키와 Claude 연결: 연결이 키를 만들거나 다른 연결을 허용할 수는 없어요. 로그인한 사람이 해요.
  • OAuth와 회원가입.
  • 웹훅: Filmsquare 밖으로 데이터를 보내는 기능이에요.
  • 제공사 콜백과 실시간 소켓(캔버스와 접속 표시).

파이널 게이트, 크레딧 확인, 요금제 한도는 Claude에게도 다른 누구와 똑같이 적용돼요.

안전 #

  • Claude는 나로 움직여요. 내 역할(또는 연결할 때 고른 더 낮은 역할)을 가지고, 한 일은 내 이름으로 나타나요.
  • 스태프의 자료는 지시가 아니에요. Claude가 Filmsquare에서 읽는 코멘트, 시나리오, 기타 텍스트는 스태프가 올린 자료예요. Filmsquare가 Claude에게 그렇게 알려 줘요. Claude가 무엇을 할지는 나만 결정해요.
  • 가격을 먼저 말해요. 테이크를 만들면 크레딧이 들어요. Claude는 아무것도 만들지 않는 dryRun: true로 생성 액션을 부르고, 테이크를 시작하기 전에 비용이 얼마인지 말하고, 시키지 않으면 파이널을 렌더하지 않도록 지시받아요.
  • 시키지 않으면 컨펌하지 않아요. sign_off는 내 이름으로 결정을 기록해요. Claude는 내가 결정하라고 시켰을 때만 쓰도록 지시받아요.

프롬프트 #

프롬프트 넷에 흔한 일의 작업 방식이 담겨 있어요. break_down_episode, process_feedback, work_on_step, check_continuity예요. 프롬프트와 작업 방식을 보세요.

Claude와 함께

MCP

내 Claude가 MCP로 이 일을 해요. 내 이름으로, 내 역할대로요:

  • find_actions

    API로 할 수 있는 모든 일을 검색해서, 맞는 액션을 입력값과 함께 돌려줘요.

    이렇게 요청해요: 단계의 컨펌 규칙을 바꾸는 액션을 찾아 줘.

  • run_action

    find_actions로 찾은 액션 하나를 내 역할과 권한으로, 내 이름으로 실행해요.

    이렇게 요청해요: 2화 5번 컷의 두 번째 테이크를 OK컷으로 골라 줘.

  • whats_waiting

    내 컨펌을 기다리는 단계와 읽지 않은 알림을 보여 줘요.

    이렇게 요청해요: Filmsquare에서 내가 처리할 게 뭐가 있어?

  • list_productions

    워크스페이스의 작품과 에피소드를 보여 줘요.

    이렇게 요청해요: Filmsquare에 어떤 작품과 에피소드가 있어?

  • get_episode

    에피소드의 씬과 컷을 편집 순서대로, 팀별 단계 전부, 파이널을 렌더할 수 있는지까지 보여 줘요.

    이렇게 요청해요: 2화는 어디까지 왔고, 각 단계는 누구를 기다리고 있어?

  • get_feedback

    컷, 테이크, 에피소드, 요소에 달린 코멘트 스레드를 핀마다 타임코드나 영역과 함께 읽어요.

    이렇게 요청해요: 2화에 아직 열려 있는 코멘트가 뭐야?

  • reply_feedback

    내 이름으로 코멘트 스레드에 답하고, 처리가 끝나면 해결로 닫아요.

    이렇게 요청해요: 4번 컷 코멘트에 새 드래프트에서 시선이 고쳐졌다고 답하고 해결해 줘.

  • view_media

    스틸, 키프레임, 테이크를 봐요. 영상은 포스터 이미지와 다운로드 링크로 돌아와요.

    이렇게 요청해요: 3번 컷의 OK컷 스틸을 보여 주고 레퍼런스와 맞는지 알려 줘.

  • upload_file

    가지고 있는 파일을 컷이나 씬의 새 테이크로, 또는 작품 에셋으로 추가해요(최대 10MB).

    이렇게 요청해요: 이 레퍼런스 사진을 작품 에셋에 올려 줘.

  • get_script

    에피소드의 최신 시나리오 고를 이미 있는 @핸들과 함께 읽어요.

    이렇게 요청해요: 2화 시나리오를 읽고 아직 @핸들이 없는 인물이 누구인지 알려 줘.

  • edit_script

    에피소드 시나리오의 씬, 대사, 한 줄을 고쳐 새 버전으로 저장해요. 시나리오 전체를 다시 보내지 않아도 돼요.

    이렇게 요청해요: 2화 S02의 도입부를 방금 이야기한 대로 고쳐서 새 버전으로 저장해 줘.

  • submit_breakdown

    브레이크다운을 Filmsquare에 넣어요: 씬, 컷, 대사, 캐스트, 세트, 소품.

    이렇게 요청해요: 2화 시나리오를 브레이크다운해서 제출해 줘. 이미 있는 핸들은 그대로 써.

  • get_continuity

    에피소드의 OK컷을 나란히 놓고, 컷마다 쓰인 요소 버전을 보여 줘요.

    이렇게 요청해요: 씬 S2의 OK컷을 연결 체크용으로 펼쳐 줘.

  • report_continuity

    한 연결 체크를 기록해요. 어긋난 곳마다 해당 컷의 OK컷에 코멘트가 달려요.

    이렇게 요청해요: 씬 S2의 연결을 체크하고 어긋난 곳을 보고해 줘.

  • submit_style

    스타일 가이드를 내 스타일 라이브러리(Create, Styles)에 넣어요. 새 스타일이거나 기존 스타일의 다음 버전이에요.

    이렇게 요청해요: 이 스틸들을 보고 스타일 가이드를 써서 보여 줘. 내가 진행하라고 하면 제출해.

  • request_signoff

    팀 단계의 컨펌 담당자에게 컨펌을 요청해요. 담당자에게 알림이 가요.

    이렇게 요청해요: 2화 다음 단계 컨펌 담당자에게 컨펌을 요청해 줘. 바뀐 내용도 코멘트로 적어서.

  • sign_off

    한 단계에 대한 내 결정을 기록해요: 컨펌 또는 수정 요청. 내가 결정하라고 시켰을 때만 써요.

    이렇게 요청해요: 2화 다음 단계를 내 이름으로 컨펌해 줘.

  • where_does_it_go

    파일이 어느 화면에 들어가야 하는지 알려 줘요: 지도, 판단 트리, 실제 예시를 보여 줘요.

    이렇게 요청해요: 이 블로킹 릴은 어디에 넣어야 해?

  • prepare_upload

    디스크에 있는 파일 최대 100개에 대해 서명된 업로드 링크와 바로 쓸 수 있는 curl 명령을 줘요.

    이렇게 요청해요: 이 폴더에 있는 영상을 올려 줘.

  • add_to_visualize

    올린 파일을 컷과 씬에 번호로 맞춰 콘티, 3D, 애니매틱 아래에 넣어요.

    이렇게 요청해요: Blender 작업은 3D에, 애니매틱은 애니매틱에 넣어 줘.

  • studio_analytics

    소유자와 프로듀서용이에요. 스튜디오가 어떻게 돌아가는지 스태프별, 하루 단위, 비용, 그리고 발송될 모양 그대로의 리포트 메일로 보여 줘요.

    이렇게 요청해요: 지난주 스태프 작업이 어땠고, 누가 도움이 필요해?

Claude 연결 5.1

이 페이지의 Markdown: /docs/ko/claude/tools.md