검토 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_accounts | read | 키의 계정 허용 목록을 존중해요 |
get_capabilities | read | 형식, 제한, 동의 요구 사항 |
create_upload_intent | mutate | 직접 업로드 지시를 반환해요; 미디어 바이트는 도구를 통과하지 않아요 |
finalize_upload | mutate | 세션 ID(+멀티파트 파트 영수증); 서버가 바이트/MIME을 직접 관찰해요 |
create_draft | mutate | 원본 + 수신처 변형 |
validate_post | read | 구조화된 수신처별 문제 |
schedule_post | mutate | 시각 하나, ≤90일 이내, expectedVersion 필수 |
publish_post | mutate | 202 의미론; 게시의 증거 아님 |
get_post_status | read | 수신처별 상태와 네이티브 링크 |
list_posts | read | 커서 페이지네이션 |
cancel_delivery | mutate | 아직 안전하게 접수되지 않았을 때만 |
retry_delivery | mutate | 알려진 실패만; 절대 중복 없음 |
get_usage | read | 남은 게시 카운터는 존재하지 않아요 |
필수 도구 인자
| 도구 | 필수 인자 |
|---|---|
list_accounts | 없음 |
get_capabilities | 없음 |
create_upload_intent | filename, declaredMime, declaredBytes |
finalize_upload | assetId, sessionId |
create_draft | caption, destinations |
validate_post | postId |
schedule_post | postId, scheduledAt, timezone, expectedVersion |
publish_post | postId |
get_post_status | postId |
list_posts | 없음 |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | 없음 |
선택적 인자에는 목록 도구의 페이지네이션, 변경 작업의 idempotencyKey,
멀티파트 확정의 multipart.parts, 초안 미디어와 수신처 변형이 있어요.
tools/list가 반환하는 런타임 도구 스키마가 선택적 필드, 중첩 형태, 검증
제한의 기준이에요.
변경 도구는 선택적 idempotencyKey 인자를 받아요. 생략하면 서버가 하나를
생성하고 모든 결과에 그 키를 그대로 돌려줘요: 전송 실패도 포함돼요. 이때
작업이 이미 API에 도달했을 수 있어요(오류는 transport_outcome_unknown과 키를
담아요). 도구는 변경 작업을 절대 자동 재시도하지 않아요; 중복 작업 생성을
피하려면 같은(SAME) idempotency key로 재시도하세요.
에이전트 워크플로 예제
list_accounts+get_capabilities→ 유효한 수신처 선택.create_upload_intent→ 바이트를 직접 업로드 →finalize_upload.create_draft→validate_post→ 잘못된 수신처 수정 또는 선택 해제.publish_post(또는schedule_post) → 전송 ID 기록.get_post_status(제한된 폴링 또는 고객 웹훅):requires_action응답은 실행 가능한 지시로 취급, 예: TikTok 동의.
테스트된 클라이언트
- 공식
@modelcontextprotocol/sdkTypeScript 클라이언트, 실제 서브프로세스 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을 벗어날 수 없어요.