appsgolem-mcp (Node / TypeScript)

AppsGolem YouTube 커터 API를 위한 MCP 서버입니다. AI 에이전트(Claude Desktop, Claude Code, Cursor 등)가 YouTube 동영상에서 클립을 잘라내고 — 웹 커터가 지원하는 모든 형식으로 — 직접 다운로드 URL을 받을 수 있게 해줍니다. REST 로직은 작고 의존성이 낮은 클라이언트(src/client.ts)에 있으며, src/server.ts는 그 위의 얇은 MCP 도구 계층입니다.

요구 사항

• Node.js >= 18 (전역 fetch 사용).

• AppsGolem API 키(ag_live_…) — https://appsgolem.com/api-billing/ 대시보드에서 생성하세요. 크레딧은 선불제이며, 해당 페이지에서 팩 또는 구독을 구매할 수 있습니다.

Related MCP server: ytmcp

설치 / 연결 (수동 설치 불필요)

npx가 서버를 필요 시 가져와 실행합니다 — 전역 설치할 것이 없습니다.

Claude Desktop / Cursor — 클라이언트의 MCP 설정(예: claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "appsgolem": {
      "command": "npx",
      "args": ["-y", "appsgolem-mcp"],
      "env": { "APPSGOLEM_API_KEY": "ag_live_…" }
    }
  }
}

Claude Code — 한 줄 명령:

claude mcp add appsgolem -e APPSGOLEM_API_KEY=ag_live_… -- npx -y appsgolem-mcp

서버는 stdio를 통해 MCP를 사용합니다(해당 클라이언트들이 사용하는 전송 방식). APPSGOLEM_API_KEY가 없어도 시작 시 치명적이지 않습니다 — 서버는 여전히 시작되어 도구를 광고하며, 각 호출은 키를 설정하라고 알려주는 명확한 config_error를 반환합니다.

구성

가격

생성된 클립 1개 = 1크레딧. 2160p(4K) = 클립당 4 크레딧 — 단, audio_only는 1로 유지됩니다. 2시간 초과 소스는 작업당 +1이 추가되며, 지속 시간이 알려진 경우에만 적용됩니다(프로브가 지속 시간을 확인할 수 없으면 추가 요금이 생략됨). N개 클립의 배치/스티치는 클립당 N 크레딧입니다. 실패한 컷은 청구되지 않습니다.

도구

서버는 세 가지 도구를 노출합니다. MCP 입력 스키마 검증을 통과한 호출은 구조화된 결과를 반환합니다 — 성공 시 API 자체의 JSON, 핸들러/API 실패 시 { "error": … } — 프로토콜 수준 오류를 발생시키지 않으므로 에이전트는 항상 사용 가능한 객체를 얻습니다. (잘못된 도구 인수는 핸들러 실행 전에 MCP SDK에 의해 텍스트 전용 isError 결과로 거부됩니다.)

1. cut_youtube_video

YouTube 동영상에서 클립(또는 클립 배치)을 자릅니다. 기본적으로 클립이 생성될 때까지 대기하고 상태를 반환합니다(다운로드 토큰이 준비되면 download_url 포함). wait: false로 설정하면 즉시 제출하고 현재 작업을 반환합니다(디스패치 후 상태는 일반적으로 queued).

매개변수

반환값 (wait: true, 기본값) — 생성된 작업 상태. download_url은 다운로드 토큰이 준비되면 표시되며, 아직 준비되지 않았다면 다시 폴링하세요:

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "produced",
  "credits_reserved": 1,
  "created_at": "2026-08-22T12:00:00+00:00",
  "download_url": "https://appsgolem.com/v1/download/…/clip.mp4"
}

반환값 (wait: false) — 현재 상태(디스패치 후 일반적으로 queued)의 작업을 즉시 반환하며 download_url은 아직 없습니다. id로 get_cut_status를 폴링하거나(또는 poll_url 가져오기):

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "queued",
  "credits_reserved": 1,
  "poll_url": "/v1/cuts/e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
}

클립이 준비되기 전에 대기가 시간 초과되면 결과에 "still_processing": true와 작업 id가 포함됩니다 — 해당 id로 get_cut_status를 폴링하세요. 작업이 종료 실패에 도달하면 결과는 { "error": "cut_failed", "state": "failed" | "refunded", "id": … }입니다(크레딧은 청구되지 않음).

2. get_cut_status

id로 컷 작업을 확인합니다. cut_youtube_video(wait=false)로 시작한 작업이나 시간 초과된 작업을 폴링하는 데 사용합니다.

반환값 — 작업 상태. 생성/전달되면 다운로드 토큰이 준비된 경우 download_url도 포함됩니다(그렇지 않으면 다시 폴링):

{ "id": "e48db1a2-…", "state": "queued", "credits_reserved": 1, "created_at": "…" }

상태는 accepted → queued → produced → delivered로 진행되며, 오류 시 failed → refunded입니다.

3. get_account_balance

API 계정의 사용 가능한 크레딧 잔액과 현재 시간당 상한을 반환합니다. 매개변수 없음.

반환값

{ "balance": 412, "hourly_cap": 60 }

모드

예시 프롬프트

에이전트가 요청에서 매개변수를 선택하므로 일반 언어로 지시할 수 있습니다:

• "https://youtu.be/dQw4w9WgXcQ에서 0:30부터 1:15까지 1080p로 잘라줘." → cut_youtube_video(url, start="0:30", end="1:15")

• "그 동영상의 오디오를 2:00부터 5:00까지 mp3로 추출해줘." → mode="audio_only", audio_format="mp3"

• "10:00–10:45 하이라이트로 세로 쇼츠를 만들어줘." → mode="short", start="10:00", end="10:45"

• "0:05–0:12를 GIF로 바꿔줘." → mode="gif"

• "1:00부터 2:00까지 5초 간격으로 프레임 접촉 시트를 추출해줘." → mode="frames", interval_ms=5000, sheet=true

• "0:10–0:20과 1:00–1:10을 하나의 클립으로 이어줘." → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true

• "0:00–0:30을 빠른 스트림 복사로 잘라줘." → fast=true

• "API 크레딧이 얼마나 남았어?" → get_account_balance()

결과 및 오류 형태

핸들러의 모든 결과는 일반 객체입니다(MCP 인수 검증 실패는 예외 — 위 도구 참고 사항 참조). 실패 시 객체에는 error 코드가 있습니다(도구 호출 자체는 성공합니다):

API 수준 오류(예: 검증 400, 속도 제한 429)는 API 자체 오류 본문에 status 필드를 더해 반환됩니다. 서버가 Retry-After를 보내면 429에는 retry_after(초)도 포함되므로 에이전트가 백오프할 수 있습니다.

상대 download_url(API가 경로를 반환)은 해당 오리진에 유지되는 경우에만 구성된 API base를 기준으로 전체 URL로 해석됩니다. 이미 절대 URL이거나 다른 오리진을 참조하는 경우는 변경되지 않습니다.

개발

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs node --test (no network)
npm start          # run the stdio server locally (key needed for calls, not startup)

게시

npm publish(이 디렉터리에서)를 실행하면 npx appsgolem-mcp를 모든 사용자가 사용할 수 있게 됩니다. prepare 스크립트는 설치/게시 시 dist/를 자동으로 빌드합니다.