DeepSRT

Resuma vídeos do YouTube usando a API DeepSRT.

GitHub
50

Documentação

Servidor MCP DeepSRT

Um servidor Model Context Protocol (MCP) que fornece funcionalidades de resumo de vídeos do YouTube e extração de transcrições por meio da integração com a API do DeepSRT e acesso direto às legendas do YouTube.

Resumo

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

Arquitetura

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

Fluxo de Sequência

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

Arquitetura Técnica

Componentes Principais

1. Camada do Servidor MCP

  • Suporte a Runtime: Execução tanto em Node.js quanto em Bun
  • Tratamento de Protocolo: Gerenciamento de requisições/respostas do Model Context Protocol (MCP)
  • Registro de Ferramentas: ferramentas get_summary e get_transcript
  • Tratamento de Erros: Gerenciamento abrangente de erros com mensagens amigáveis ao usuário

2. Pipeline de Processamento de Vídeo

  • Analisador de URL: Suporta múltiplos formatos de URL do YouTube e IDs de vídeo diretos
  • Integração InnerTube: Acesso direto à API do YouTube sem chaves de API
  • Descoberta de Legendas: Detecção automática de faixas de legenda disponíveis
  • Seleção de Qualidade: Prioriza legendas manuais em vez de geradas automaticamente

3. Processamento de Transcrições

  • Analisador XML: Lida com o formato <timedtext> do YouTube
  • Decodificador de Entidades: Converte entidades HTML em texto legível
  • Formatador de Timestamps: Converte milissegundos para o formato [MM:SS]
  • Filtro de Conteúdo: Remove notação musical e segmentos vazios

4. Geração de Resumos

  • Integração DeepSRT: Chamadas diretas à API para worker.deepsrt.com
  • Suporte a Múltiplos Idiomas: Suporta zh-tw, en, ja e outros idiomas
  • Seleção de Modo: Formatos de resumo narrativo e em tópicos
  • Tradução de Título: Tradução automática do título para o idioma de destino

Principais Recursos

Sem Pré-cache Necessário

  • Funciona imediatamente para qualquer vídeo do YouTube com legendas
  • Extração e processamento de transcrições em tempo real
  • Sem dependência de sistemas de cache externos

Seleção Inteligente de Legendas

  • Ordem de Prioridade: Manual > Gerada automaticamente > Qualquer disponível
  • Preferência de Idioma: Respeita o idioma preferido do usuário
  • Estratégia de Fallback: Degradação graciosa para opções disponíveis

Tratamento Robusto de Erros

  • Gerenciamento de timeout de rede (timeout de 30 segundos)
  • Tradução de erros de API para mensagens amigáveis ao usuário
  • Tratamento gracioso de vídeos sem legendas
  • Validação abrangente dos parâmetros de entrada

Saída em Múltiplos Formatos

  • Formatação Markdown: Texto rico com cabeçalhos e metadados
  • Dados Estruturados: Informações do vídeo, duração, detalhes do autor
  • Transcrições com Timestamps: Informações precisas de tempo
  • Resumos Localizados: Conteúdo no idioma preferido do usuário

Características de Desempenho

  • Inicialização Rápida: < 1 segundo para inicialização do servidor
  • Processamento Eficiente: Chamadas de API paralelas para resumo + tradução de título
  • Eficiente em Memória: Análise XML em streaming, sem buffer de grandes dados
  • Otimizado para Rede: Uma única requisição por vídeo para metadados + legendas

Atualizações Recentes

v0.1.9 (Mais Recente)

  • ✅ Corrigidas falhas críticas na lógica de testes: Os testes agora validam corretamente as respostas da API em vez de verificar propriedades inexistentes success
  • ✅ Tratamento de erros aprimorado: Melhor tratamento gracioso de limitação de taxa da API do YouTube (HTTP 429)
  • ✅ Suíte de testes robusta: Todos os 56 testes agora passam consistentemente com resiliência adequada a erros
  • ✅ Integração de API verificada: Confirmado que as APIs DeepSRT e YouTube funcionam corretamente quando não há limitação de taxa
  • ✅ Suporte a múltiplos idiomas: Validação da geração de resumos em zh-tw, en, ja
  • ✅ Pronto para produção: A suíte de testes lida profissionalmente com limitações reais da API

v0.1.3

  • ✅ Corrigida a análise de argumentos da CLI: Agora suporta os formatos --key=value e --key value
  • ✅ Corrigido o modo de tópicos: --mode bullet agora funciona corretamente e gera resumos em tópicos
  • ✅ Compatibilidade bunx aprimorada: Execução direta com bunx @deepsrt/deepsrt-mcp funciona sem instalação

v0.1.2

  • ✅ Corrigida a execução da CLI: Tornou a CLI o binário padrão para execução direta via npx/bunx
  • ✅ Configuração do pacote atualizada: Resolução binária adequada para diferentes métodos de execução

v0.1.1

  • ✅ Testes abrangentes adicionados: Testes unitários, testes de integração e testes de ponta a ponta
  • ✅ Ferramenta CLI aprimorada: Interface de linha de comando completa com ajuda e exemplos
  • ✅ Extração direta de transcrições: Sem pré-cache necessário, funciona com qualquer vídeo do YouTube

Recursos

  • Gerar resumos para vídeos do YouTube
  • Extrair transcrições completas com timestamps de vídeos do YouTube
  • Suporte para modos de resumo narrativo e em tópicos
  • Suporte a múltiplos idiomas (padrão: zh-tw)
  • Acesso direto às legendas do YouTube (sem necessidade de chave de API)
  • Integração perfeita com ambientes habilitados para MCP

Como Funciona

Geração de Resumos

  1. Integração Direta com o YouTube

    • Extrai informações do vídeo e legendas diretamente do YouTube usando a API InnerTube
    • Obtém o conteúdo da transcrição do sistema de legendas do YouTube
    • Envia os dados da transcrição para a API DeepSRT para resumo

  2. Processamento em Tempo Real

    • Sem pré-cache necessário - funciona imediatamente para qualquer vídeo com legendas
    • Seleciona automaticamente as melhores legendas disponíveis (manuais preferidas em vez de geradas automaticamente)
    • Suporta múltiplos idiomas e modos de resumo

Extração de Transcrições

  1. Acesso Direto ao YouTube

    • As transcrições são extraídas diretamente do sistema de legendas do YouTube usando a API InnerTube
    • Sem pré-cache necessário - funciona imediatamente para qualquer vídeo com legendas

  2. Seleção de Legendas

    • Seleciona automaticamente as melhores legendas disponíveis (legendas manuais preferidas em vez de geradas automaticamente)
    • Suporta seleção de preferência de idioma
    • Recorre graciosamente a alternativas disponíveis

  3. Formatação de Timestamps

    • Fornece transcrições limpas e formatadas com timestamps no formato [MM:SS]
    • Lida com legendas manuais e geradas automaticamente
    • Inclui metadados do vídeo e informações das legendas
%%{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 da CLI

O servidor MCP DeepSRT fornece uma interface unificada que lida tanto com o modo de servidor MCP quanto com comandos CLI.

Interface 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 Diretos (Sem Instalação Necessária)

# 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

Instalação Global

Para acesso mais 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

Opções da 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 Suportados

A CLI aceita múltiplos formatos de URL do 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

Recursos da CLI

  • Execução direta: Sem instalação necessária com bunx
  • Múltiplos formatos de URL: URLs completas, URLs curtas ou IDs de vídeo diretos
  • Formatos de argumento flexíveis: Ambos os formatos --key=value e --key value suportados
  • Suporte a idiomas: Especifique o idioma de destino para resumos e preferências de transcrição
  • Modos de resumo: Escolha entre formatos narrativo ou em tópicos
  • Saída rica: Saída colorida no console com indicadores de progresso
  • Tratamento de erros: Mensagens de erro claras com sugestões

Exemplo de Saída

Saída de Transcrição

# 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 ♪
...

Saída de Resumo (Modo Narrativo)

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

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

## Summary

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

Saída de Resumo (Modo Tópicos)

# 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]
...

Instalação

Opção 1: Uso Direto com bunx (Recomendado - Sem Instalação Necessária)

Use a interface unificada diretamente sem qualquer instalação:

# 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

Opção 2: Instalação Global (Para Uso Frequente)

# 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

Opção 3: Instalação para Claude Desktop (Recomendado)

Adicione esta configuração ao seu arquivo de configuração do Claude Desktop:

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

Esta abordagem:

  • ✅ Sem instalação local necessária
  • ✅ Sempre usa a versão mais recente
  • ✅ Atualizações automáticas ao reiniciar o Claude
  • ✅ Compatibilidade entre plataformas
  • ✅ Configuração simples e limpa

Opção 4: Instalação para Cline

Adicione esta configuração ao seu cline_mcp_settings.json:

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

Ou apenas peça ao Cline para instalar no chat:

"Ei, instale este servidor MCP para mim a partir de https://github.com/DeepSRT/deepsrt-mcp"

Opção 5: Usando bunx (Execução Direta)

Você pode executar o servidor diretamente com bunx sem instalação:

# 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

Integração MCP

O servidor fornece as seguintes ferramentas para clientes MCP:

get_summary

Obtém um resumo para um vídeo do YouTube.

Parâmetros:

  • videoId (obrigatório): ID do vídeo do YouTube
  • lang (opcional): Código do idioma (ex.: zh-tw) - padrão é zh-tw
  • mode (opcional): Modo de resumo ("narrative" ou "bullet") - padrão é narrative

get_transcript

Obtém uma transcrição para um vídeo do YouTube com timestamps.

Parâmetros:

  • videoId (obrigatório): ID do vídeo do YouTube ou URL completa do YouTube
  • lang (opcional): Código de idioma preferido para legendas (ex.: en, zh-tw) - padrão é en

Exemplo 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"
});

Desenvolvimento

Instale as dependências:

npm install

Executando Testes

# 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 Testes:

  • Testes Unitários (src/index.test.ts, src/integration.test.ts) - Testes rápidos com dados simulados
  • Testes de Rede (src/transcript.test.ts, src/e2e.test.ts) - Testes de integração reais com a API do YouTube

Exemplos

Veja o diretório examples/ para implementações de referência:

  • examples/standalone-summarizer.ts - Script independente mostrando padrões de uso direto da API

Executando o Servidor

Com Bun (Recomendado para desenvolvimento - inicialização mais rápida):

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

# Using npm script
npm run start:bun

Com Node.js (Produção):

# Build first
npm run build

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

Testando o Servidor

Você pode testar o servidor usando o inspetor MCP:

npm run inspector

Ou teste manualmente com 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

Compilar para Produção

Compile para produção:

npm run build

Modo de observação para desenvolvimento:

npm run watch

Demonstração

Perguntas Frequentes

P: Estou recebendo o erro 404, por quê?

R: Isso ocorre porque o resumo do vídeo não está em cache no local de borda da CDN. Você precisa abrir este vídeo usando a extensão do Chrome DeepSRT para que ele seja armazenado em cache na rede CDN antes de poder obter esse resumo usando o MCP.

Você pode verificar o status do cache usando cURL assim

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

Se você vir cache-status: HIT, o conteúdo está em cache no local de borda da CDN e seu servidor MCP não deve receber 404.