tube-bridge

tube-bridge

Pesquisa do YouTube auto-hospedada para agentes de IA.

Pesquise vídeos e canais, leia transcrições e comentários, extraia quadros com carimbo de tempo e construa corpora privados de busca semântica — por meio de 17 ferramentas MCP.

• 14 das 17 ferramentas não precisam de chave da API do YouTube.
• Corpus local primeiro: transcrições, vetores e índices permanecem na sua máquina.
• Resultados de pesquisa úteis: títulos, pontuações de similaridade, URLs canônicas de vídeo e links com carimbo de tempo.
• Uma ferramenta para um quadro: retorne evidência visual perto de um achado de transcrição sem manter arquivos de mídia.
• Auto-hospedado e MIT: sem conta, intermediário hospedado, armazenamento gerenciado ou dependência de fornecedor.

Conecte-se em um minuto

A configuração mais simples usa uvx, que executa o pacote PyPI publicado em um ambiente isolado:

uvx tube-bridge

Normalmente, seu cliente MCP inicia esse comando para você. Escolha seu cliente abaixo.

[!NOTE] tube-bridge requer Python 3.12 ou mais recente. Uma chave de API é opcional. ffmpeg é necessária apenas para youtube_get_frame, e a primeira operação de incorporação pode baixar o modelo local.

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Config e adicione:

{
  "mcpServers": {
    "tube-bridge": {
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

Reinicie o Claude Desktop após salvar a configuração.

Claude Code

claude mcp add --scope user tube-bridge -- uvx tube-bridge

Cursor

Crie .cursor/mcp.json no seu projeto, ou adicione o servidor à sua configuração MCP de nível de usuário:

{
  "mcpServers": {
    "tube-bridge": {
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

VS Code

Crie .vscode/mcp.json:

{
  "servers": {
    "tube-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

Codex CLI

codex mcp add tube-bridge -- uvx tube-bridge

Pacote Pi

O Pi pode carregar o adaptador relativo ao pacote e a habilidade canônica tube-bridge-research da mesma fonte Git:

python3 -m pip install tube-bridge==1.1.6
pi install git:github.com/TheWhiteWater/tube-bridge@v1.1.6
pi list

Isso registra uma ferramenta de status mais todas as 17 ferramentas MCP com o prefixo tube_bridge_. O adaptador lê os existentes plugin.json e mcp.json, inicia apenas o runtime stdio local, preserva conteúdo de texto e imagem limitado e encaminha apenas um ambiente de processo filho na lista de permissões.

O gerenciador de pacotes Pi instala a dependência do adaptador Node, mas não instala Python ou ffmpeg. Garanta que o python3 visível ao Pi seja Python 3.12+ com as dependências do tube-bridge instaladas; instale ffmpeg separadamente para usar youtube_get_frame. Por padrão, o estado gerenciado pelo Pi fica sob o diretório de dados da plataforma; defina TUBE_BRIDGE_PI_DATA para mover essa raiz. Um TUBE_BRIDGE_CACHE explícito ainda tem precedência para os bancos de dados de runtime. O portão opcional de quadro ao vivo é /tube-bridge-selftest frame.

Remova o pacote com:

pi remove git:github.com/TheWhiteWater/tube-bridge@v1.1.6

Se um cliente de desktop não conseguir encontrar uvx, substitua "uvx" pelo caminho absoluto retornado por which uvx no macOS/Linux ou where.exe uvx no Windows.

Experimente o fluxo de pesquisa completo

Pergunte ao seu agente:

Pesquise no YouTube por vídeos recentes sobre agentes de IA locais primeiro. Leia a transcrição do resultado mais forte, adicione-a a um corpus chamado local-agents, encontre a seção que discute memória, retorne o link da fonte com carimbo de tempo e extraia um quadro desse momento.

O agente pode concluir essa solicitação com esta sequência de ferramentas:

youtube_search(query="local-first AI agents", order="date")
youtube_get_transcript(url="https://www.youtube.com/watch?v=VIDEO_ID", with_timestamps=true)
corpus_create(corpus_id="local-agents", label="Local-first AI Agents")
corpus_add(corpus_id="local-agents", url="https://www.youtube.com/watch?v=VIDEO_ID")
corpus_search(corpus_id="local-agents", query="memory architecture")
youtube_get_frame(url="https://www.youtube.com/watch?v=VIDEO_ID", timestamp_ms=FOUND_TIME_MS)

Adicione mais vídeos com corpus_add, depois use corpus_search para pesquisar em todas as transcrições de uma vez.

Ferramentas

Ferramenta	Chave da API do YouTube	O que faz
youtube_search	Opcional	Pesquisa vídeos com filtros de data, canal, duração e ordenação
youtube_get_video_info	Opcional	Obtém título, duração, visualizações, canal, descrição e tags
youtube_get_trending	Opcional	Obtém vídeos em alta no momento
youtube_get_channel_videos	Não	Obtém uploads recentes de uma URL de canal ou @handle
youtube_get_playlist	Não	Obtém vídeos de uma playlist
youtube_get_transcript	Não	Obtém uma transcrição, opcionalmente com carimbos de tempo [MM:SS]
youtube_get_frame	Não	Retorna um JPEG efêmero perto de um carimbo de tempo em milissegundos inteiros
youtube_get_available_languages	Não	Lista faixas de legenda manuais e geradas automaticamente
youtube_get_comments	Obrigatória	Obtém comentários de nível superior com curtidas e contagens de respostas
youtube_search_channels	Obrigatória	Pesquisa canais e filtra por contagem de inscritos
youtube_get_channel_info	Obrigatória	Obtém estatísticas do canal, país e palavras-chave
corpus_create	Não	Cria um corpus local nomeado
corpus_add	Não	Busca, divide em blocos e incorpora localmente uma transcrição de vídeo
corpus_search	Não	Pesquisa semanticamente um corpus com resultados com carimbo de tempo
corpus_list	Não	Lista corpora com contagens de vídeos e blocos
corpus_delete	Não	Exclui permanentemente um corpus e seus vetores
tube_bridge_help	Não	Lê documentação de runtime e limitações conhecidas

Não significa que nenhuma chave da API de Dados do YouTube é necessária; acesso de rede ao YouTube ainda pode ser necessário. Pesquisa, informações de vídeo e tendências funcionam sem chave por meio do yt-dlp e fazem upgrade para a API de Dados v3 quando uma chave está configurada.

Chave opcional da API de Dados do YouTube

Uma chave da API de Dados do YouTube v3 desbloqueia comentários, pesquisa de canais e detalhes de canais. Também melhora a confiabilidade de pesquisa, informações de vídeo e tendências.

Crie uma chave no Google Cloud Console, ative a API de Dados do YouTube v3 e exponha-a ao processo que inicia o tube-bridge:

export YOUTUBE_API_KEY="your-key"

Mantenha chaves fora de arquivos de configuração MCP commitados. Use o suporte a segredos/ambiente do seu cliente quando disponível.

Corpus semântico local

O armazenamento do corpus e a inferência de incorporação são locais à máquina que executa o tube-bridge.

• Armazenamento: SQLite mais sqlite-vec em ~/.tube_bridge/corpus.db
• Incorporações: BGE-small-en-v1.5 por meio do fastembed
• Divisão em blocos: janelas de 80 segundos com sobreposição de 20 segundos
• Classificação: deduplicação de sobreposição e limites por vídeo com reconhecimento de fonte
• Resultados: pontuação de similaridade, intervalo de tempo, título do vídeo, URL canônica e URL com carimbo de tempo

Defina TUBE_BRIDGE_CACHE para mover tanto o corpus quanto os bancos de dados de cache:

export TUBE_BRIDGE_CACHE="/path/to/tube-bridge-data"

O modelo de incorporação pode ser baixado no primeiro uso. Após os ativos estarem disponíveis, a inferência de incorporação não requer uma API de modelo externa.

Extração de quadros

youtube_get_frame requer ffmpeg em PATH; a imagem Docker já o inclui.

Cada chamada baixa uma seção temporária curta ao redor de timestamp_ms, retorna um JPEG limitado como MCP ImageContent e remove a mídia temporária antes de retornar. Não cria uma biblioteca de quadros ou clipes.

Outras formas de executar

Instalação PyPI persistente

pip install tube-bridge

tube-bridge          # stdio
tube-bridge --http   # Streamable HTTP on port 8080

Docker

docker run --rm -p 8080:8080 ghcr.io/thewhitewater/tube-bridge:latest

O endpoint de saúde é http://localhost:8080/health; o endpoint HTTP Streamable é http://localhost:8080/mcp.

Registro MCP Oficial

Nome do registro: io.github.TheWhiteWater/tube-bridge

Clientes com reconhecimento de registro podem instalar a distribuição PyPI com uvx e iniciar o servidor stdio sem um intermediário hospedado.

Configuração HTTP remota

Para uma instância HTTP que você opera:

{
  "mcpServers": {
    "tube-bridge": {
      "type": "http",
      "url": "https://your-host.example/mcp"
    }
  }
}

Proteja rotas MCP remotas definindo uma chave Bearer no lado do servidor:

export TUBE_BRIDGE_AUTH_KEY="choose-a-long-random-value"
tube-bridge --http

Depois configure um cliente com capacidade de cabeçalho:

{
  "mcpServers": {
    "tube-bridge": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

/health permanece público. /mcp, /sse e /messages exigem a chave Bearer quando TUBE_BRIDGE_AUTH_KEY está definido. SSE legado está disponível em /sse para clientes que ainda precisam dele.

Variáveis de ambiente

Variável	Obrigatória	Propósito
YOUTUBE_API_KEY	Não	Ativa as 3 ferramentas somente de API e melhora as chamadas de descoberta suportadas
TUBE_BRIDGE_PROXY	Não	Roteia solicitações de yt-dlp e transcrição por meio de um proxy HTTP(S) ou SOCKS
TUBE_BRIDGE_CACHE	Não	Altera o diretório que contém cache.db e corpus.db
TUBE_BRIDGE_AUTH_KEY	Não	Protege rotas MCP HTTP auto-hospedadas com um token Bearer estático

Como funciona

MCP client
   │
   ├── discovery and metadata ── Data API v3 (when configured)
   │                          └─ yt-dlp fallback
   ├── transcripts ───────────── youtube-transcript-api
   ├── timestamped frames ────── yt-dlp + ffmpeg → ephemeral JPEG
   └── semantic corpus ───────── SQLite + sqlite-vec + local fastembed

• stdio é recomendado para clientes locais;
• HTTP Streamable está disponível em /mcp para uso remoto auto-hospedado;
• respostas de fallback bem-sucedidas mantêm seus esquemas normais;
• falhas controladas usam erros MCP tipados com campos estáveis code, source e retryable;
• bancos de dados de cache e corpus são separados e permanecem de propriedade do operador.

Prévia do Plugin de Agente

GitHub Releases inclui tube-bridge-agent-plugin-<version>.zip, contendo:

• a configuração MCP stdio local;
• a habilidade tube-bridge-research;
• modelos de pesquisa e orientação de avaliação de fontes.

O Agent Plugins v1 não padroniza a instalação de dependências. Instale Python 3.12+, ffmpeg e as dependências do pacote no ambiente usado pelo host do plugin. O pacote não contém credenciais.

Limitações conhecidas

• O YouTube pode restringir solicitações anônimas de yt-dlp e transcrição, especialmente de faixas de IP de hospedagem em nuvem.
• Uma chave da API de Dados melhora a confiabilidade de descoberta e metadados, mas não substitui o acesso a transcrições.
• A configuração inicial do modelo de incorporação local pode exigir acesso de rede e espaço adicional em disco.
• tube-bridge é software auto-hospedado; não fornece contas, acesso hospedado público, armazenamento gerenciado ou SLA.

Se o YouTube bloquear solicitações da sua rede, defina TUBE_BRIDGE_PROXY. Mantenha credenciais de proxy em variáveis de ambiente em vez de configuração commitada.

Desenvolvimento

git clone https://github.com/TheWhiteWater/tube-bridge.git
cd tube-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-release.txt
pip install --no-deps -e .
pip install pytest pytest-asyncio pytest-mock build twine
python -m pytest tests -q

python test_tools.py é um teste de fumaça opcional ao vivo do YouTube. A suíte de testes determinística não chama o YouTube.

Veja CONTRIBUTING.md para contribuir. Relatórios de segurança devem seguir SECURITY.md.

Licença

MIT — veja LICENSE.