AiVideoEditor
무료로 시작하기
메뉴

검토 2026-11-10 · API 버전 2026-11-09 · Markdown 읽기

MCP 설정

UI와 REST API가 /api/v1을 통해 사용하는 것과 같은 공유 서비스를 감싸는 로컬 stdio MCP 서버예요. 어댑터는 product key를 설정된 AiVideoEditor API에만 보내요. Supabase나 제공자 자격 증명은 사용하지 않아요.

사전 요구 사항

이건 게시된 패키지나 호스팅 연결이 아니라 소스 체크아웃 어댑터예요. AiVideoEditor 저장소에 대한 승인된 접근을 확보하고, Node 22+를 설치하고, 저장소 루트에서 npm ci를 실행하세요. /app/developers에서 필요한 스코프와 수신처 접근만 담긴 워크스페이스 product key를 만드세요. draft-only 키는 게시하거나 예약할 수 없어요. 키를 채팅 프롬프트에 붙여넣지 마세요.

실행하기

export PUBLISHER_API_URL=https://app.example.com   # HTTPS; http://localhost is allowed for dev
export PUBLISHER_API_KEY=pk_v1_…                   # create in /app/developers
node packages/mcp/bin/publisher-mcp.mjs            # or: npm start --workspace packages/mcp

bin은 실제 실행 런처예요(TypeScript와 확장자 없는 임포트는 tsx로 해석돼요). 모든 진단은 stderr로 가요; stdout에는 프로토콜 트래픽만 흐름돼요. PUBLISHER_API_URL은 HTTPS여야 하고(일반 HTTP는 루프백 개발에서만) 자격 증명, 쿼리, 프래그먼트를 담지 않아야 해요.

범용 클라이언트 설정

{
  "mcpServers": {
    "autoposted": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/bin/publisher-mcp.mjs"],
      "env": {
        "PUBLISHER_API_URL": "https://app.example.com",
        "PUBLISHER_API_KEY": "pk_v1_…"
      }
    }
  }
}

런처에는 Node 22+와 워크스페이스 의존성(tsx, @modelcontextprotocol/sdk)이 필요해요. OAuth가 있는 호스팅 MCP 전송은 future work예요; 모든 데스크톱이나 호스팅 클라이언트가 붙여넣은 bearer 키를 지원한다고 가정하지 마세요.

도구

도구Read/Mutate참고
list_accountsread키의 계정 허용 목록을 존중해요
get_capabilitiesread형식, 제한, 동의 요구 사항
create_upload_intentmutate직접 업로드 지시를 반환해요; 미디어 바이트는 도구를 통과하지 않아요
finalize_uploadmutate세션 ID(+멀티파트 파트 영수증); 서버가 바이트/MIME을 직접 관찰해요
create_draftmutate원본 + 수신처 변형
validate_postread구조화된 수신처별 문제
schedule_postmutate시각 하나, ≤90일 이내, expectedVersion 필수
publish_postmutate202 의미론; 게시의 증거 아님
get_post_statusread수신처별 상태와 네이티브 링크
list_postsread커서 페이지네이션
cancel_deliverymutate아직 안전하게 접수되지 않았을 때만
retry_deliverymutate알려진 실패만; 절대 중복 없음
get_usageread남은 게시 카운터는 존재하지 않아요

필수 도구 인자

도구필수 인자
list_accounts없음
get_capabilities없음
create_upload_intentfilename, declaredMime, declaredBytes
finalize_uploadassetId, sessionId
create_draftcaption, destinations
validate_postpostId
schedule_postpostId, scheduledAt, timezone, expectedVersion
publish_postpostId
get_post_statuspostId
list_posts없음
cancel_deliverydeliveryId
retry_deliverydeliveryId
get_usage없음

선택적 인자에는 목록 도구의 페이지네이션, 변경 작업의 idempotencyKey, 멀티파트 확정의 multipart.parts, 초안 미디어와 수신처 변형이 있어요. tools/list가 반환하는 런타임 도구 스키마가 선택적 필드, 중첩 형태, 검증 제한의 기준이에요.

변경 도구는 선택적 idempotencyKey 인자를 받아요. 생략하면 서버가 하나를 생성하고 모든 결과에 그 키를 그대로 돌려줘요: 전송 실패도 포함돼요. 이때 작업이 이미 API에 도달했을 수 있어요(오류는 transport_outcome_unknown과 키를 담아요). 도구는 변경 작업을 절대 자동 재시도하지 않아요; 중복 작업 생성을 피하려면 같은(SAME) idempotency key로 재시도하세요.

에이전트 워크플로 예제

  1. list_accounts + get_capabilities → 유효한 수신처 선택.
  2. create_upload_intent → 바이트를 직접 업로드 → finalize_upload.
  3. create_draft → validate_post → 잘못된 수신처 수정 또는 선택 해제.
  4. publish_post(또는 schedule_post) → 전송 ID 기록.
  5. get_post_status(제한된 폴링 또는 고객 웹훅): requires_action 응답은 실행 가능한 지시로 취급, 예: TikTok 동의.

테스트된 클라이언트

  • 공식 @modelcontextprotocol/sdk TypeScript 클라이언트, 실제 서브프로세스 stdio를 문서화된 bin으로 테스트(initialize → tools/list → tools/call): packages/mcp/tests/stdio.test.ts에서 깨끗한 stdout과 시작 실패 확인을 포함해 테스트됨.
  • 인메모리 전송 위의 공식 SDK 클라이언트: 이것도 커버됨.
  • 데스크톱 클라이언트(Claude Desktop, Cursor 등): 아직 테스트 안 됨: 위의 범용 스니펫으로 설정하고 지원을 주장하기 전에 결과를 보고하세요.

클라이언트 호환성

클라이언트 또는 전송상태설정
공식 TypeScript SDK 서브프로세스 stdio자동 테스트 커버리지위에 표시된 저장소 런처
공식 SDK 인메모리 전송자동 테스트 커버리지테스트 하네스스 전용
Claude Desktop / 기타 데스크톱 클라이언트수동 검증 안 됨로컬 stdio 지원 클라이언트; 절대 런처 경로 사용
ChatGPT 호스팅 연결이 어댑터가 제공하지 않음호스팅 전송 필요; 로컬 stdio JSON은 호스팅 커넥터가 아님
OAuth가 있는 호스팅 MCP미구현별도의 제품 작업

문제 해결

  • 런처가 의존성을 해석하지 못함: 승인된 소스 체크아웃에서 npm ci를 실행하고 Node 버전을 확인하세요. 무관한 공개 패키지로 대체하지 마세요.
  • 클라이언트가 초기화되지 않음: 절대 런처 경로를 사용하고 stderr를 확인하세요. 디버깅 출력을 stdout에 쓰지 마세요.
  • 401: 설정된 product key가 현재 유효한지 확인하세요; 폐기됐다면 UI에서 대체 키를 만드세요. 403: 스코프와 계정 제한을 확인하세요.
  • transport_outcome_unknown: 반환된 idempotency key를 보관하고 그 키로 동일한 작업을 재시도하세요, 절대 새 키로 하지 마세요.
  • requires_action: 제공된 지시를 권한 있는 사람에게 전달하세요; 에이전트는 TikTok 사람 동의를 공급할 수 없어요.

자격 증명 처리

product key는 설정된 AiVideoEditor API에만 보내져요(Authorization: Bearer). 모델 제공자나 소셜 네트워크에는 절대 보내지지 않고, 절대 로그되지 않으며, URL이 검증되어 키가 리디렉션을 따라가거나 설정된 origin을 벗어날 수 없어요.