transcriptor-mcp

Cada herramienta que acepta un video admite url. Esto es un enlace de una plataforma compatible o un ID de YouTube simple. Cada herramienta devuelve content (texto para el chat) y structuredContent (JSON tipado para tu código).

get_transcript

Texto plano limpio, sin marcas de tiempo, HTML ni nombres de hablantes. Sin lang, la herramienta devuelve la pista en el idioma original del video. La mayoría de las plataformas que no son YouTube no indican en qué idioma está un video; cuando la herramienta no puede determinar qué pista es, responde con la lista de pistas, y la llamas de nuevo con type y lang. Las entradas son las mismas que para get_raw_subtitles.

Respuesta: videoId, url (la página del video, tal como el servidor la resolvió), type, lang, text, is_truncated, total_length, start_offset, end_offset. Cuando hay más texto disponible, la respuesta también tiene next_cursor.

get_raw_subtitles

Contenido SRT o VTT sin procesar, en partes.

Entrada:

• type — official o auto. Sin lang, la herramienta elige una pista de este tipo
• lang — un código de idioma o nombre de pista, tal como get_available_subtitles lo lista. Sin esto, el idioma original del video, como para get_transcript
• response_limit — predeterminado 50000, mínimo 1000, máximo 200000
• next_cursor — el cursor de la respuesta anterior

Respuesta: los campos de get_transcript, más format (srt o vtt) y content.

get_available_subtitles

Respuesta: official y auto. Cada campo es una lista ordenada de códigos de idioma. Usa esta herramienta primero, luego da type y lang a las herramientas anteriores.

get_video_info

Metadatos extendidos de yt-dlp:

• identidad — videoId, title, description, webpageUrl
• autor — uploader, uploaderId, channel, channelId, channelUrl
• números — duration, uploadDate, viewCount, likeCount, commentCount
• clasificación — tags, categories, liveStatus, isLive, wasLive, availability
• imágenes — thumbnail y thumbnails

get_video_chapters

Respuesta: chapters. Cada elemento tiene startTime, endTime y title. Cuando el video no tiene capítulos, la lista está vacía.

get_video_frame

Entrada:

• timecode — "MM:SS" o "HH:MM:SS.mmm"
• seconds — una alternativa a timecode. Da uno de los dos, no ambos
• format — jpeg (predeterminado) o png
• width — predeterminado 1280, máximo 1920, nunca mayor que la fuente
• quality — 2 a 31, solo para jpeg

Respuesta: un bloque de imagen, más url, timestampSeconds, timestamp, mimeType, sizeBytes y width. Esta herramienta necesita ffmpeg. La imagen de Docker lo incluye.

get_playlist_transcripts

Entrada:

• url — una URL de lista de reproducción, o una URL de visualización con list=
• type, lang, format — lo mismo que get_raw_subtitles, excepto que lang es obligatorio: el idioma original se elige solo para un video a la vez
• playlistItems — un valor de -I de yt-dlp como 1:5, 1,3,7 o -1
• maxItems — el número máximo de videos

Respuesta: results. Cada elemento tiene videoId y text.

search_videos

Entrada:

• query — el texto de búsqueda
• limit — predeterminado 10, máximo 50
• offset — el número de resultados a omitir
• uploadDateFilter — hour, today, week, month o year
• response_format — json (predeterminado) o markdown

Respuesta: results. Cada elemento tiene videoId, title, url, duration, uploader, viewCount y thumbnail.

Transporte. El servidor acepta POST /mcp únicamente. GET y DELETE devuelven 405. El servidor no tiene estado y no envía Mcp-Session-Id.

El proceso de Node no verifica tokens de portador. Coloca un proxy inverso o una puerta de enlace delante para autenticación y TLS. El endpoint alojado funciona de esta manera.

API REST. Una segunda imagen ofrece la misma extracción sobre HTTP simple:

docker run --rm -p 3000:3000 artsamsonov/transcriptor-mcp-api:latest

La interfaz de Swagger está en http://localhost:3000/docs. Para una pila completa con la API y el servidor MCP, lee docker-compose.example.yml.

Desarrollo.

npm ci
npm run build
npm run start:mcp        # stdio
npm run start:mcp:http   # Streamable HTTP on port 4200
npm test

Necesitas Node.js 22 o posterior (20 todavía funciona, pero llegó al final de su vida útil en abril de 2026), y yt-dlp en tu PATH. La captura de fotogramas necesita ffmpeg, y WHISPER_MAX_DURATION_SECONDS necesita ffprobe (ambos se incluyen en el mismo paquete, y en la imagen de Docker). Otros scripts: lint, type-check, format, test:coverage, test:e2e:api y test:e2e:mcp.

Lanzamientos. El mantenedor los crea. Los pasos están en .claude/skills/release/SKILL.md. La versión proviene de package.json en tiempo de ejecución, a través de src/version.ts. Al enviar una etiqueta v*, CI compila ambas imágenes y publica la entrada del Registro MCP desde server.json.

Estructura. src/mcp.ts (entrada stdio), src/mcp-http.ts (HTTP Streamable), src/mcp-core.ts (herramientas, prompts, widgets), src/youtube.ts (yt-dlp), src/whisper.ts, src/cache.ts, src/index.ts (API REST), load/ (k6) y src/e2e/ (pruebas de humo de Docker).