DeepSRT

Resume YouTube videos using the DeepSRT API.

GitHub
50

Documentación

Servidor MCP DeepSRT

Un servidor de Model Context Protocol (MCP) que proporciona funcionalidad de resumen de videos de YouTube y extracción de transcripciones mediante la integración con la API de DeepSRT y el acceso directo a los subtítulos de YouTube.

TL;DR

{
  "mcpServers": {
    "deepsrt": {
      "type": "stdio",
      "command": "bunx",
      "args": [
        "@deepsrt/deepsrt-mcp@latest",
        "--server"
      ]
    }
  }
}

Arquitectura

graph TB
    subgraph "MCP Client"
        Client[Claude Desktop / Cline]
    end
    
    subgraph "DeepSRT MCP Server"
        Server[MCP Server]
        SummaryTool[get_summary]
        TranscriptTool[get_transcript]
        
        Server --> SummaryTool
        Server --> TranscriptTool
    end
    
    subgraph "External APIs"
        YouTube[YouTube InnerTube API]
        DeepSRT[DeepSRT Worker API]
        Captions[YouTube Caption API]
    end
    
    Client --> Server
    SummaryTool --> YouTube
    SummaryTool --> DeepSRT
    TranscriptTool --> YouTube
    TranscriptTool --> Captions

Flujo de Secuencia

sequenceDiagram
    participant User
    participant MCP as MCP Client
    participant Server as DeepSRT MCP Server
    participant YouTube as YouTube InnerTube API
    participant DeepSRT as DeepSRT Worker API
    participant Captions as YouTube Caption API

    Note over User,Captions: Summary Generation Flow
    User->>MCP: Request video summary
    MCP->>Server: get_summary(videoId, lang, mode)
    
    Server->>Server: Extract video ID from URL
    Server->>YouTube: POST /youtubei/v1/player
    Note right of YouTube: Get video metadata<br/>and caption tracks
    YouTube-->>Server: Video details + caption tracks
    
    Server->>Server: Select best caption track<br/>(manual > auto-generated)
    Server->>Server: Extract transcript argument<br/>from caption URL
    
    par Summary Request
        Server->>DeepSRT: GET /transcript2?action=summarize
        Note right of DeepSRT: X-Transcript-Arg header<br/>contains caption URL params
        DeepSRT-->>Server: Generated summary
    and Title Translation
        Server->>DeepSRT: GET /transcript2?action=translate
        DeepSRT-->>Server: Translated title
    end
    
    Server->>Server: Format markdown response<br/>with metadata + summary
    Server-->>MCP: Formatted summary response
    MCP-->>User: Display summary

    Note over User,Captions: Transcript Extraction Flow
    User->>MCP: Request video transcript
    MCP->>Server: get_transcript(videoId, lang)
    
    Server->>Server: Extract video ID from URL
    Server->>YouTube: POST /youtubei/v1/player
    YouTube-->>Server: Video details + caption tracks
    
    Server->>Server: Select best caption track<br/>for preferred language
    Server->>Captions: GET caption XML from baseUrl
    Captions-->>Server: Raw XML transcript
    
    Server->>Server: Parse XML transcript<br/>- Extract timestamps<br/>- Decode HTML entities<br/>- Format text
    Server->>Server: Generate markdown response<br/>with timestamps
    Server-->>MCP: Formatted transcript
    MCP-->>User: Display transcript with timestamps

Arquitectura Técnica

Componentes Principales

1. Capa del Servidor MCP

  • Soporte de Ejecución: Ejecución tanto en Node.js como en Bun
  • Manejo de Protocolo: Gestión de solicitudes/respuestas del Model Context Protocol (MCP)
  • Registro de Herramientas: herramientas get_summary y get_transcript
  • Manejo de Errores: Gestión integral de errores con mensajes amigables para el usuario

2. Canal de Procesamiento de Video

  • Analizador de URL: Soporta múltiples formatos de URL de YouTube e IDs de video directos
  • Integración con InnerTube: Acceso directo a la API de YouTube sin claves de API
  • Detección de Subtítulos: Detección automática de pistas de subtítulos disponibles
  • Selección de Calidad: Prioriza subtítulos manuales sobre los generados automáticamente

3. Procesamiento de Transcripciones

  • Analizador XML: Maneja el formato <timedtext> de YouTube
  • Decodificador de Entidades: Convierte entidades HTML a texto legible
  • Formateador de Marca de Tiempo: Convierte milisegundos al formato [MM:SS]
  • Filtro de Contenido: Elimina notación musical y segmentos vacíos

4. Generación de Resúmenes

  • Integración con DeepSRT: Llamadas directas a la API de worker.deepsrt.com
  • Soporte Multilingüe: Soporta zh-tw, en, ja y otros idiomas
  • Selección de Modo: Formatos de resumen narrativo y de viñetas
  • Traducción de Título: Traducción automática del título al idioma de destino

Características Clave

Sin necesidad de precaché

  • Funciona inmediatamente para cualquier video de YouTube con subtítulos
  • Extracción y procesamiento de transcripciones en tiempo real
  • Sin dependencia de sistemas de caché externos

Selección Inteligente de Subtítulos

  • Orden de Prioridad: Manual > Generado automáticamente > Cualquier disponible
  • Preferencia de Idioma: Respeta el idioma preferido del usuario
  • Estrategia de Respaldo: Degradación elegante a opciones disponibles

Manejo Robusto de Errores

  • Gestión de tiempo de espera de red (tiempo de espera de 30 segundos)
  • Traducción de errores de API a mensajes amigables
  • Manejo elegante de videos sin subtítulos
  • Validación integral de parámetros de entrada

Salida Multiformato

  • Formato Markdown: Texto enriquecido con encabezados y metadatos
  • Datos Estructurados: Información del video, duración, detalles del autor
  • Transcripciones con Marca de Tiempo: Información precisa de tiempo
  • Resúmenes Localizados: Contenido en el idioma preferido del usuario

Características de Rendimiento

  • Inicio Rápido: Inicialización del servidor en menos de 1 segundo
  • Procesamiento Eficiente: Llamadas API paralelas para resumen + traducción de título
  • Eficiente en Memoria: Análisis XML en streaming, sin almacenamiento en búfer de grandes datos
  • Optimizado para Red: Una sola solicitud por video para metadatos + subtítulos

Actualizaciones Recientes

v0.1.9 (Última)

  • ✅ Corregidos fallos críticos en la lógica de pruebas: Las pruebas ahora validan correctamente las respuestas de la API en lugar de verificar propiedades inexistentes success
  • ✅ Mejorado el manejo de errores: Mejor manejo elegante de la limitación de velocidad de la API de YouTube (HTTP 429)
  • ✅ Suite de pruebas robusta: Las 56 pruebas ahora pasan de manera consistente con una resiliencia adecuada a errores
  • ✅ Integración API verificada: Confirmado que las APIs de DeepSRT y YouTube funcionan correctamente cuando no hay limitación de velocidad
  • ✅ Soporte multilingüe: Validada la generación de resúmenes en zh-tw, en, ja
  • ✅ Listo para producción: La suite de pruebas maneja las limitaciones reales de la API de manera profesional

v0.1.3

  • ✅ Corregido el análisis de argumentos de CLI: Ahora soporta formatos --key=value y --key value
  • ✅ Corregido el modo viñetas: --mode bullet ahora funciona correctamente y genera resúmenes con viñetas
  • ✅ Mejorada la compatibilidad con bunx: La ejecución directa con bunx @deepsrt/deepsrt-mcp funciona sin instalación

v0.1.2

  • ✅ Corregida la ejecución de CLI: Se hizo que CLI sea el binario predeterminado para la ejecución directa con npx/bunx
  • ✅ Configuración de paquete actualizada: Resolución binaria adecuada para diferentes métodos de ejecución

v0.1.1

  • ✅ Pruebas integrales añadidas: Pruebas unitarias, de integración y de extremo a extremo
  • ✅ Herramienta CLI mejorada: Interfaz de línea de comandos completa con ayuda y ejemplos
  • ✅ Extracción directa de transcripciones: Sin necesidad de precaché, funciona con cualquier video de YouTube

Características

  • Generar resúmenes para videos de YouTube
  • Extraer transcripciones completas con marcas de tiempo de videos de YouTube
  • Soporte para modos de resumen narrativo y de viñetas
  • Soporte multilingüe (predeterminado: zh-tw)
  • Acceso directo a subtítulos de YouTube (sin necesidad de clave de API)
  • Integración perfecta con entornos habilitados para MCP

Cómo Funciona

Generación de Resúmenes

  1. Integración Directa con YouTube

    • Extrae información del video y subtítulos directamente de YouTube usando la API de InnerTube
    • Obtiene el contenido de la transcripción del sistema de subtítulos de YouTube
    • Envía los datos de la transcripción a la API de DeepSRT para el resumen

  2. Procesamiento en Tiempo Real

    • Sin necesidad de precaché: funciona inmediatamente para cualquier video con subtítulos
    • Selecciona automáticamente los mejores subtítulos disponibles (manuales preferidos sobre los generados automáticamente)
    • Soporta múltiples idiomas y modos de resumen

Extracción de Transcripciones

  1. Acceso Directo a YouTube

    • Las transcripciones se extraen directamente del sistema de subtítulos de YouTube usando la API de InnerTube
    • Sin necesidad de precaché: funciona inmediatamente para cualquier video con subtítulos

  2. Selección de Subtítulos

    • Selecciona automáticamente los mejores subtítulos disponibles (subtítulos manuales preferidos sobre los generados automáticamente)
    • Soporta selección de preferencia de idioma
    • Recurre elegantemente a alternativas disponibles

  3. Formato de Marcas de Tiempo

    • Proporciona transcripciones limpias y formateadas con marcas de tiempo en formato [MM:SS]
    • Maneja subtítulos manuales y generados automáticamente
    • Incluye metadatos del video e información de subtítulos
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#2496ED', 'secondaryColor': '#38B2AC', 'tertiaryColor': '#1F2937', 'mainBkg': '#111827', 'textColor': '#E5E7EB', 'lineColor': '#4B5563', 'noteTextColor': '#E5E7EB'}}}%%
sequenceDiagram
    participant User
    participant MCP as MCP Client
    participant YouTube as YouTube API
    participant DeepSRT as DeepSRT API

    Note over User,DeepSRT: Summary Generation Flow (Direct Processing)
    User->>MCP: Request video summary
    MCP->>YouTube: Get video info & captions via InnerTube API
    YouTube-->>MCP: Return video details & caption tracks
    MCP->>YouTube: Fetch transcript XML from caption URL
    YouTube-->>MCP: Return raw transcript content
    MCP->>DeepSRT: Send transcript + metadata for summarization
    DeepSRT-->>MCP: Return generated summary
    MCP-->>User: Return formatted summary

    Note over User,DeepSRT: Transcript Extraction Flow (Direct)
    User->>MCP: Request video transcript
    MCP->>YouTube: Get video info & captions via InnerTube API
    YouTube-->>MCP: Return video details & caption tracks
    MCP->>YouTube: Fetch transcript XML from caption URL
    YouTube-->>MCP: Return raw transcript content
    MCP->>MCP: Parse & format transcript with timestamps
    MCP-->>User: Return formatted transcript with metadata

Uso de CLI

El servidor MCP DeepSRT proporciona una interfaz unificada que maneja tanto el modo de servidor MCP como los comandos CLI.

Interfaz Unificada

# MCP Server Mode (default - for Claude Desktop/Cline)
bunx @deepsrt/deepsrt-mcp                    # Starts MCP server on stdio
bunx @deepsrt/deepsrt-mcp --server           # Explicit server mode

# CLI Commands (direct usage)
bunx @deepsrt/deepsrt-mcp get-transcript <video-url> [options]
bunx @deepsrt/deepsrt-mcp get-summary <video-url> [options]

# Help
bunx @deepsrt/deepsrt-mcp --help

Comandos CLI Directos (Sin Instalación Requerida)

# Extract transcript with timestamps
bunx @deepsrt/deepsrt-mcp get-transcript https://www.youtube.com/watch?v=dQw4w9WgXcQ
bunx @deepsrt/deepsrt-mcp get-transcript dQw4w9WgXcQ --lang=en

# Generate video summary
bunx @deepsrt/deepsrt-mcp get-summary dQw4w9WgXcQ --lang=zh-tw --mode=bullet
bunx @deepsrt/deepsrt-mcp get-summary https://youtu.be/dQw4w9WgXcQ --lang=ja

Instalación Global

Para un acceso más fácil, instale globalmente:

# Install globally
npm install -g @deepsrt/deepsrt-mcp

# MCP Server Mode
deepsrt-mcp                                             # Starts MCP server
deepsrt-mcp --server                                    # Explicit server mode

# CLI Commands
deepsrt-mcp get-transcript https://youtu.be/dQw4w9WgXcQ --lang=en
deepsrt-mcp get-summary dQw4w9WgXcQ --lang=zh-tw --mode=narrative

Opciones de CLI

get-transcript

bunx @deepsrt/deepsrt-mcp get-transcript <video-url> [options]

Options:
  --lang=<language>    Preferred language code for captions (default: en)
  --lang <language>    Alternative format
                      Examples: en, zh-tw, ja, es, fr

Examples:
  bunx @deepsrt/deepsrt-mcp get-transcript https://www.youtube.com/watch?v=dQw4w9WgXcQ
  bunx @deepsrt/deepsrt-mcp get-transcript dQw4w9WgXcQ --lang=zh-tw
  bunx @deepsrt/deepsrt-mcp get-transcript https://youtu.be/dQw4w9WgXcQ --lang ja

get-summary

bunx @deepsrt/deepsrt-mcp get-summary <video-url> [options]

Options:
  --lang=<language>    Target language for summary (default: zh-tw)
  --lang <language>    Alternative format
                      Examples: zh-tw, en, ja, es, fr
  --mode=<mode>        Summary format (default: narrative)
  --mode <mode>        Alternative format
                      Options: narrative, bullet

Examples:
  bunx @deepsrt/deepsrt-mcp get-summary https://www.youtube.com/watch?v=dQw4w9WgXcQ
  bunx @deepsrt/deepsrt-mcp get-summary dQw4w9WgXcQ --lang=en --mode=bullet
  bunx @deepsrt/deepsrt-mcp get-summary https://youtu.be/dQw4w9WgXcQ --lang ja --mode narrative

Formatos de URL Soportados

El CLI acepta múltiples formatos de URL de YouTube:

# Full YouTube URLs
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=30s

# Short URLs
https://youtu.be/dQw4w9WgXcQ

# Embed URLs
https://www.youtube.com/embed/dQw4w9WgXcQ

# Direct video IDs
dQw4w9WgXcQ

Características de CLI

  • Ejecución directa: Sin instalación requerida con bunx
  • Múltiples formatos de URL: URLs completas, URLs cortas o IDs de video directos
  • Formatos de argumento flexibles: Se soportan formatos --key=value y --key value
  • Soporte de idioma: Especifique el idioma de destino para resúmenes y preferencias de transcripción
  • Modos de resumen: Elija entre formatos narrativos o de viñetas
  • Salida enriquecida: Salida de consola con colores e indicadores de progreso
  • Manejo de errores: Mensajes de error claros con sugerencias

Ejemplo de Salida

Salida de Transcripción

# Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)

**Author:** Rick Astley  
**Duration:** 3:33  
**Captions:** English (manual)

## Transcript

[00:18] ♪ We're no strangers to love ♪
[00:22] ♪ You know the rules and so do I ♪
[00:27] ♪ A full commitment's what I'm thinking of ♪
...

Salida de Resumen (Modo Narrativo)

# 瑞克·艾斯利 - 永遠不會放棄你

**Author:** Rick Astley  
**Duration:** 3:33  
**Language:** zh-tw  
**Mode:** narrative

## Summary

這是一首經典的流行歌曲，表達了對愛情的承諾和忠誠...

Salida de Resumen (Modo Viñetas)

# How Robots Are Helping Amazon Deliver on Prime Day

**Author:** Bloomberg Television  
**Duration:** 5:45  
**Language:** zh-tw  
**Mode:** bullet

## Summary

本影片主要探討亞馬遜如何運用機器人技術來提升倉儲效率...

# 機器人技術在亞馬遜倉儲的應用與效益

  - 亞馬遜已部署了第一百萬個機器人，並在Prime Day等高峰期用於滿足訂單需求 [00:00:00]
  - 機器人旨在為員工提供安全且高生產力的工作環境 [00:00:30]
  - 移動機器人可以搬運超過一千磅的貨物，並移動貨架以減少員工的行走距離 [00:00:54]
...

Instalación

Opción 1: Uso Directo con bunx (Recomendado - Sin Instalación Requerida)

Use la interfaz unificada directamente sin ninguna instalación:

# MCP Server Mode (for Claude Desktop/Cline)
bunx @deepsrt/deepsrt-mcp                    # Default: starts MCP server
bunx @deepsrt/deepsrt-mcp --server           # Explicit server mode

# CLI Commands (direct usage)
bunx @deepsrt/deepsrt-mcp get-transcript https://www.youtube.com/watch?v=dQw4w9WgXcQ
bunx @deepsrt/deepsrt-mcp get-summary dQw4w9WgXcQ --lang=zh-tw --mode=bullet

# Always uses latest version automatically
bunx @deepsrt/deepsrt-mcp@latest get-transcript dQw4w9WgXcQ --lang=en

Opción 2: Instalación Global (Para Uso Frecuente)

# Install globally for easier access
npm install -g @deepsrt/deepsrt-mcp

# Then use directly with shorter command
deepsrt-mcp get-transcript https://www.youtube.com/watch?v=dQw4w9WgXcQ
deepsrt-mcp get-summary dQw4w9WgXcQ --lang zh-tw --mode bullet

Opción 3: Instalación para Claude Desktop (Recomendado)

Agregue esta configuración a su archivo de configuración de Claude Desktop:

  • En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • En Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "deepsrt": {
      "type": "stdio",
      "command": "bunx",
      "args": [
        "@deepsrt/deepsrt-mcp@latest",
        "--server"
      ]
    }
  }
}

Este enfoque:

  • ✅ Sin instalación local requerida
  • ✅ Siempre usa la última versión
  • ✅ Actualizaciones automáticas al reiniciar Claude
  • ✅ Compatibilidad multiplataforma
  • ✅ Configuración simple y limpia

Opción 4: Instalación para Cline

Agregue esta configuración a su cline_mcp_settings.json:

{
  "mcpServers": {
    "deepsrt": {
      "type": "stdio", 
      "command": "bunx",
      "args": [
        "@deepsrt/deepsrt-mcp@latest",
        "--server"
      ]
    }
  }
}

O simplemente pídale a Cline que instale en el chat:

"Oye, instala este servidor MCP para mí desde https://github.com/DeepSRT/deepsrt-mcp"

Opción 5: Usando bunx (Ejecución Directa)

Puede ejecutar el servidor directamente con bunx sin instalación:

# Run from the project directory
bunx --bun src/index.ts

# Or use npm scripts
npm run start:bun  # Uses Bun
npm run start:node # Uses Node.js
npm run dev        # Development mode with Bun

Uso

Integración MCP

El servidor proporciona las siguientes herramientas para clientes MCP:

get_summary

Obtiene un resumen para un video de YouTube.

Parámetros:

  • videoId (obligatorio): ID del video de YouTube
  • lang (opcional): Código de idioma (por ejemplo, zh-tw) - predeterminado a zh-tw
  • mode (opcional): Modo de resumen ("narrative" o "bullet") - predeterminado a narrative

get_transcript

Obtiene una transcripción para un video de YouTube con marcas de tiempo.

Parámetros:

  • videoId (obligatorio): ID del video de YouTube o URL completa de YouTube
  • lang (opcional): Código de idioma preferido para subtítulos (por ejemplo, en, zh-tw) - predeterminado a en

Ejemplo de Uso

Usando Claude Desktop:

// Get video summary
const summaryResult = await mcp.use_tool("deepsrt", "get_summary", {
  videoId: "dQw4w9WgXcQ",
  lang: "zh-tw",
  mode: "narrative"
});

// Get video transcript
const transcriptResult = await mcp.use_tool("deepsrt", "get_transcript", {
  videoId: "dQw4w9WgXcQ",
  lang: "en"
});

Usando Cline:

// Get video summary
const summaryResult = await mcp.use_tool("deepsrt", "get_summary", {
  videoId: "dQw4w9WgXcQ",
  lang: "zh-tw",
  mode: "bullet"
});

// Get video transcript
const transcriptResult = await mcp.use_tool("deepsrt", "get_transcript", {
  videoId: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  lang: "en"
});

Desarrollo

Instale las dependencias:

npm install

Ejecución de Pruebas

# Run unit tests (fast, no network calls)
npm test

# Run unit tests only
npm run test:unit

# Run network tests (requires internet, may be slower)
npm run test:network

# Run all tests including network tests
npm run test:all

# Run tests in watch mode
npm run test:watch

# Run tests with CI reporter (for CI/CD)
npm run test:ci

Tipos de Pruebas:

  • Pruebas Unitarias (src/index.test.ts, src/integration.test.ts) - Pruebas rápidas con datos simulados
  • Pruebas de Red (src/transcript.test.ts, src/e2e.test.ts) - Pruebas de integración reales con la API de YouTube

Ejemplos

Consulte el directorio examples/ para implementaciones de referencia:

  • examples/standalone-summarizer.ts - Script independiente que muestra patrones de uso directo de la API

Ejecución del Servidor

Con Bun (Recomendado para desarrollo - inicio más rápido):

# Development mode (runs TypeScript directly)
npm run dev
# or
bun src/index.ts

# Using npm script
npm run start:bun

Con Node.js (Producción):

# Build first
npm run build

# Then run
npm run start:node
# or
node build/index.js

Pruebas del Servidor

Puede probar el servidor usando el inspector MCP:

npm run inspector

O probar manualmente con JSON-RPC:

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | bun src/index.ts

# Test get_transcript
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_transcript", "arguments": {"videoId": "dQw4w9WgXcQ", "lang": "en"}}}' | bun src/index.ts

Compilación para Producción

Compile para producción:

npm run build

Modo de observación para desarrollo:

npm run watch

Demo

Preguntas Frecuentes

P: Estoy obteniendo el error 404, ¿por qué?

R: Esto se debe a que el resumen del video no está almacenado en caché en la ubicación perimetral de la CDN; debe abrir este video usando la extensión de Chrome de DeepSRT para que se almacene en caché en la red CDN antes de poder obtener ese resumen usando MCP.

Puede verificar el estado de la caché usando cURL de la siguiente manera

curl -s 'https://worker.deepsrt.com/transcript' \
-i --data '{"arg":"v=VafNvIcOs5w","action":"summarize","lang":"zh-tw","mode":"narrative"}' | grep -i "^cache-status"
cache-status: HIT

Si ve cache-status: HIT, el contenido está almacenado en caché en la ubicación perimetral de la CDN y su servidor MCP no debería obtener 404.