appsgolem-mcp (Node / TypeScript)

Ein MCP-Server für die AppsGolem-YouTube-Cutter-API. Er ermöglicht es einem KI-Agenten (Claude Desktop, Claude Code, Cursor, …), Clips aus YouTube-Videos zu schneiden – in jedem Format, das der Web-Cutter unterstützt – und einen direkten Download-Link zurückzubekommen. Die REST-Logik lebt in einem kleinen, dependency-armen Client (src/client.ts); src/server.ts ist die dünne MCP-Tool-Schicht darüber.

Voraussetzungen

• Node.js >= 18 (nutzt das globale fetch).

• Ein AppsGolem-API-Schlüssel (ag_live_…) – erstelle einen in deinem Dashboard unter https://appsgolem.com/api-billing/. Guthaben wird im Voraus bezahlt; kaufe dort ein Paket oder ein Abo.

Related MCP server: ytmcp

Installation / Verbindung (keine manuelle Installation)

npx holt und startet den Server bei Bedarf – nichts muss global installiert werden.

Claude Desktop / Cursor – füge ihn zur MCP-Konfiguration des Clients hinzu (z. B. claude_desktop_config.json):

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

Claude Code – ein Befehl:

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

Der Server spricht MCP über stdio (den Transport, den diese Clients verwenden). Ein fehlender APPSGOLEM_API_KEY ist beim Start nicht fatal – der Server startet trotzdem und bewirbt seine Tools; jeder Aufruf gibt dann einen klaren config_error zurück, der dich auffordert, den Schlüssel zu setzen.

Konfiguration

Preisgestaltung

1 erstellter Clip = 1 Guthaben. 2160p (4K) = 4 Guthaben pro Clip – außer audio_only, das bei 1 bleibt. Eine Quelle, die länger als 2 h ist, addiert +1 einmal pro Auftrag, aber nur, wenn ihre Dauer bekannt ist (der Aufschlag entfällt, wenn die Analyse die Dauer nicht ermitteln kann). Ein Stapel/Zusammenschnitt von N Clips kostet N pro Clip. Fehlgeschlagene Schnitte werden nie berechnet.

Tools

Der Server stellt drei Tools bereit. Ein Aufruf, der die MCP-Eingabevalidierung besteht, gibt ein strukturiertes Ergebnis zurück – das eigene JSON der API bei Erfolg oder { "error": … } bei einem Handler-/API-Fehler – und löst niemals einen Fehler auf Protokollebene aus, sodass ein Agent immer ein brauchbares Objekt erhält. (Ungültige Tool-Argumente werden vom MCP-SDK vor dem Handler abgelehnt, als reines isError-Ergebnis.)

1. cut_youtube_video

Schneidet einen Clip (oder einen Stapel von Clips) aus einem YouTube-Video. Standardmäßig wartet es, bis der Clip erstellt ist, und gibt seinen Status zurück (einschließlich download_url, sobald ein Download-Token verfügbar ist); setze wait: false, um sofort zu senden und das aktuelle Ergebnis zu erhalten (sein Zustand ist nach dem Senden normalerweise queued).

Parameter

Rückgabe (wait: true, Standard) – der erzeugte Auftragsstatus. download_url ist vorhanden, sobald ein Download-Token verfügbar ist; falls noch nicht, erneut abfragen:

{
  "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"
}

Rückgabe (wait: false) – der Auftrag sofort, mit seinem aktuellen Zustand (nach dem Senden normalerweise queued) und noch ohne download_url; frage get_cut_status mit der id ab (oder rufe poll_url auf):

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

Wenn das Warten abläuft, bevor der Clip fertig ist, enthält das Ergebnis "still_processing": true und die Auftrags-id – frage get_cut_status mit dieser id ab. Wenn der Auftrag einen endgültigen Fehler erreicht, lautet das Ergebnis { "error": "cut_failed", "state": "failed" | "refunded", "id": … } (und es wird kein Guthaben berechnet).

2. get_cut_status

Überprüft einen Schneideauftrag anhand seiner id. Verwende es, um einen Auftrag abzufragen, der mit cut_youtube_video(wait=false) gestartet wurde oder dessen Zeit abgelaufen ist.

Rückgabe – der Zustand des Auftrags; sobald er erstellt/geliefert ist, enthält er außerdem eine download_url, wenn ein Download-Token verfügbar ist (sonst erneut abfragen):

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

Zustände durchlaufen accepted → queued → produced → delivered oder bei einem Fehler failed → refunded.

3. get_account_balance

Gibt das ausgabefähige Guthaben des API-Kontos und das aktuelle Stundenlimit zurück. Keine Parameter.

Rückgabe

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

Modi

Beispielaufforderungen

Da der Agent die Parameter aus deiner Anfrage auswählt, steuerst du ihn in natürlicher Sprache:

• „Schneide 0:30 bis 1:15 aus https://youtu.be/dQw4w9WgXcQ in 1080p." → cut_youtube_video(url, start="0:30", end="1:15")

• „Hol mir den Ton dieses Videos von 2:00 bis 5:00 als MP3." → mode="audio_only", audio_format="mp3"

• „Mach ein vertikales Short aus dem Highlight 10:00–10:45." → mode="short", start="10:00", end="10:45"

• „Mach aus 0:05–0:12 ein GIF." → mode="gif"

• „Extrahiere ein Kontaktbogen mit Frames alle 5 Sekunden von 1:00 bis 2:00." → mode="frames", interval_ms=5000, sheet=true

• „Füge 0:10–0:20 und 1:00–1:10 zu einem Clip zusammen." → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true

• „Mach einen schnellen Stream-Copy-Schnitt von 0:00–0:30." → fast=true

• „Wie viele API-Guthaben habe ich noch?" → get_account_balance()

Ergebnis- und Fehlerformen

Jedes Ergebnis eines Handlers ist ein einfaches Objekt (MCP-Argumentvalidierungsfehler sind die Ausnahme – siehe Hinweis zu den Tools oben). Bei einem Fehler enthält das Objekt einen error-Code (der Tool-Aufruf gelingt trotzdem):

API-Fehler (z. B. Validierungs-400, Rate-Limit-429) werden als eigener Fehler-Body der API plus ein status-Feld zurückgegeben; eine 429 enthält außerdem retry_after (Sekunden), wenn der Server Retry-After sendet, damit ein Agent eine Pause einlegen kann.

Eine relative download_url (die API gibt einen Pfad zurück) wird nur dann zu einer vollständigen URL gegen die konfigurierte API-Basis aufgelöst, wenn sie auf dieser Origin bleibt; bereits absolute URLs und Verweise außerhalb der Origin bleiben unverändert.

Entwicklung

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)

Veröffentlichung

npm publish (aus diesem Verzeichnis) macht npx appsgolem-mcp für alle funktionsfähig. Das prepare-Skript erstellt dist/ automatisch bei Installation/Veröffentlichung.