appsgolem-mcp (Node / TypeScript)

Un servidor MCP para la API de corte de YouTube AppsGolem. Permite que un agente de IA (Claude Desktop, Claude Code, Cursor, …) corte clips de videos de YouTube — en cualquier formato que admita el cortador web — y obtenga una URL de descarga directa. La lógica REST vive en un cliente pequeño y con pocas dependencias (src/client.ts); src/server.ts es la capa fina de herramientas MCP sobre él.

Requisitos

• Node.js >= 18 (usa fetch global).

• Una clave de API de AppsGolem (ag_live_…) — créala en tu panel en https://appsgolem.com/api-billing/. Los créditos son prepagados; compra un paquete o una suscripción allí.

Related MCP server: ytmcp

Instalar / conectar (sin instalación manual)

npx descarga y ejecuta el servidor bajo demanda — no hay que instalar nada globalmente.

Claude Desktop / Cursor — añade al archivo de configuración MCP del cliente (p. ej. claude_desktop_config.json):

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

Claude Code — un comando:

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

El servidor habla MCP sobre stdio (el transporte que usan esos clientes). La ausencia de APPSGOLEM_API_KEY no es fatal al inicio — el servidor igualmente arranca y anuncia sus herramientas; cada llamada devuelve entonces un config_error claro indicando que debes establecer la clave.

Configuración

Precios

1 clip producido = 1 crédito. 2160p (4K) = 4 créditos por clip — excepto audio_only, que sigue siendo 1. Una fuente de más de 2 h añade +1 una vez por trabajo, pero solo cuando se conoce su duración (el recargo se omite si la sonda no puede determinarla). Un lote/unión de N clips cuesta N por clip. Los cortes fallidos nunca se facturan.

Herramientas

El servidor expone tres herramientas. Una llamada que pasa la validación del esquema de entrada MCP devuelve un resultado estructurado — el propio JSON de la API en caso de éxito, o { "error": … } en cualquier fallo del manejador/API — y nunca lanza un error a nivel de protocolo, de modo que un agente siempre obtiene un objeto utilizable. (Los argumentos de herramienta no válidos son rechazados por el SDK de MCP antes de que se ejecute el manejador, como un resultado isError solo de texto.)

1. cut_youtube_video

Corta un clip (o un lote de clips) de un video de YouTube. Por defecto espera hasta que el clip se produce y devuelve su estado (incluyendo un download_url una vez que un token de descarga está listo); establece wait: false para enviar y devolver inmediatamente con el trabajo actual (su estado normalmente es queued después del envío).

Parámetros

Devuelve (wait: true, por defecto) — el estado del trabajo producido. download_url está presente una vez que un token de descarga está disponible; si aún no lo está, vuelve a sondear:

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

Devuelve (wait: false) — el trabajo inmediatamente, con su estado actual (normalmente queued después del envío) y sin download_url todavía; sondea get_cut_status con el id (o consulta poll_url):

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

Si la espera agota el tiempo antes de que el clip esté listo, el resultado lleva "still_processing": true y el id del trabajo — sondea get_cut_status con ese id. Si el trabajo alcanza un fallo terminal, el resultado es { "error": "cut_failed", "state": "failed" | "refunded", "id": … } (y no se cobra ningún crédito).

2. get_cut_status

Comprueba un trabajo de corte por su id. Úsalo para sondear un trabajo iniciado con cut_youtube_video(wait=false) o uno que agotó el tiempo.

Devuelve — el estado del trabajo; una vez producido/entregado también lleva un download_url cuando hay un token de descarga disponible (si no, vuelve a sondear):

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

Los estados progresan accepted → queued → produced → delivered, o failed → refunded en caso de error.

3. get_account_balance

Devuelve el saldo de créditos gastables de la cuenta de la API y el límite horario actual. Sin parámetros.

Devuelve

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

Modos

Ejemplos de indicaciones

Como el agente elige los parámetros a partir de tu solicitud, lo manejas en lenguaje natural:

• "Corta de 0:30 a 1:15 de https://youtu.be/dQw4w9WgXcQ en 1080p." → cut_youtube_video(url, start="0:30", end="1:15")

• "Extrae el audio de ese video de 2:00 a 5:00 como mp3." → mode="audio_only", audio_format="mp3"

• "Haz un short vertical del momento destacado de 10:00–10:45." → mode="short", start="10:00", end="10:45"

• "Convierte 0:05–0:12 en un GIF." → mode="gif"

• "Extrae una hoja de contactos de fotogramas cada 5 segundos de 1:00 a 2:00." → mode="frames", interval_ms=5000, sheet=true

• "Une 0:10–0:20 y 1:00–1:10 en un solo clip." → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true

• "Haz un corte rápido con copia de flujo de 0:00–0:30." → fast=true

• "¿Cuántos créditos de API me quedan?" → get_account_balance()

Formas de resultado y error

Cada resultado de un manejador es un objeto simple (los fallos de validación de argumentos MCP son la excepción — ver la nota de Herramientas arriba). En caso de fallo, el objeto tiene un código error (la llamada a la herramienta sigue teniendo éxito):

Los errores a nivel de API (p. ej. validación 400, límite de velocidad 429) se devuelven como el cuerpo de error propio de la API más un campo status; un 429 también incluye retry_after (segundos) cuando el servidor envía Retry-After, para que un agente pueda retroceder.

Un download_url relativo (la API devuelve una ruta) se resuelve a una URL completa contra la base de API configurada solo cuando permanece en ese origen; las URL ya absolutas y las referencias fuera de origen se dejan sin cambios.

Desarrollo

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)

Publicación

npm publish (desde este directorio) hace que npx appsgolem-mcp funcione para todos. El script prepare construye dist/ automáticamente al instalar/publicar.