appsgolem-mcp (Node / TypeScript)

AppsGolem の YouTube カッター API 用の MCP サーバーです。AI エージェント（Claude Desktop、Claude Code、Cursor、…）が、Web カッターが対応している任意の形式で 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 — コマンド1つで追加します：

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 が1回加算されます。ただし、ソースの長さが判明している場合に限ります（プローブで判定できないときは追加料金はスキップされます）。N クリップのバッチ/ステッチは、クリップごとに N ずつかかります。失敗したジョブは一切課金されません。

ツール

サーバーは 3つ のツールを公開します。MCP 入力スキーマの検証を通過した呼び出しは、構造化された結果を返します。成功時は API 自体の JSON、ハンドラ/API の障害時は { "error": … } です。プロトコルレベルのエラーを出すことはないので、エージェントは常に有効なオブジェクトを受け取れます。（無効なツール引数は、ハンドラが実行される前に、MCP SDK によってテキストのみの isError 結果として拒否されます。）

1. cut_youtube_video

YouTube 動画からクリップ（または複数のクリップのバッチ）を切り出します。デフォルトではクリップの生成が完了するまで 待機 して、そのステータス（ダウンロードトークンの準備ができていれば download_url を含む）を返します。wait: false を設定すると、送信してすぐに現在のジョブを返します（その状態は通常、送信後に queued になります）。

パラメータ

戻り値（wait: true（デフォルt））** — 生成されたジョブのステータス。ダウンロード トークンが準備できると 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

アカウントの利用可能なクレジット残高と、現在の1時間あたりの上限を返します。パラメータはありません。

戻り値

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

モード

プロンプト例

エージェントはあなたのリクエストからパラメータを選ぶので、自然な言葉で指示できます：

• "Cut 0:30 to 1:15 from https://youtu.be/dQw4w9WgXcQ in 1080p." → cut_youtube_video(url, start="0:30", end="1:15")

• "Grab the audio of that video from 2:00 to 5:00 as an mp3." → mode="audio", audio_format="mp3"

• "Make a vertical short of the 10:00–10:45 highlight." → mode="short", start="10:00", end="10:45"

• "Turn 0:05–0:12 into a GIF." → mode="gif"

• "Extract a contact sheet of frames every 5 seconds from 1:00 to 2:00." → mode="frames", interval_ms=5000, sheet=true

• "Stitch 0:10–0:20 and 1:00–1:10 into one clip." → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true

• "Do a fast, stream-copy cut of 0:00–0:30 we." → "残りクレジットは、いくつ?" → get_account_balance()

結果とエラーの形状

ハンドラからのすべての結果は普通のオブジェクトです（MCP の引数検証の失敗は例外です。上記のツールの注を参照してください）。失敗した場合、オブジェクトは error コードを持ちます（ツール呼び出し自体は成功します）。

API レベルのエラー (例: バリデーション 400、レート制限 429) は、API 自身のエラーボディに加えて status フィールドを付けて返されます。429 には、サーバーが Retry-After を送信した場合に retry_after (秒) も含まれるため、エージェントはバックオフできます。

相対的な download_url (API がパスを返す) は、そのオリジン上に留まる場合にのみ、設定された API ベースに対して完全な 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/ を自動的にビルドします。