tube-bridge

tube-bridge

Investigación de YouTube autoalojada para agentes de IA.

Busca videos y canales, lee transcripciones y comentarios, extrae fotogramas con marca de tiempo y construye corpus privados de búsqueda semántica, a través de 17 herramientas MCP.

• 14 de las 17 herramientas no necesitan clave de API de YouTube.
• Corpus local-primero: las transcripciones, los vectores y los índices permanecen en tu máquina.
• Resultado de investigación útil: títulos, puntuaciones de similitud, URL canónicas de video y enlaces con marca de tiempo.
• Una herramienta para un fotograma: devuelve evidencia visual cerca de un hallazgo de transcripción sin conservar archivos multimedia.
• Autoalojado y MIT: sin cuenta, intermediario alojado, almacenamiento gestionado ni bloqueo de proveedor.

Conéctate en un minuto

La configuración más sencilla usa uvx, que ejecuta el paquete PyPI publicado en un entorno aislado:

uvx tube-bridge

Normalmente tu cliente MCP ejecuta ese comando por ti. Elige tu cliente a continuación.

[!NOTE] tube-bridge requiere Python 3.12 o superior. Una clave de API es opcional. ffmpeg solo se necesita para youtube_get_frame, y la primera operación de incrustación puede descargar el modelo local.

Claude Desktop

Abre Configuración → Desarrollador → Editar configuración y añade:

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

Reinicia Claude Desktop después de guardar la configuración.

Claude Code

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

Cursor

Crea .cursor/mcp.json en tu proyecto, o añade el servidor a tu configuración MCP a nivel de usuario:

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

VS Code

Crea .vscode/mcp.json:

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

Codex CLI

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

Paquete Pi

Pi puede cargar el adaptador relativo al paquete y la habilidad canónica tube-bridge-research desde la misma fuente Git:

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

Esto registra una herramienta de estado más las 17 herramientas MCP con el prefijo tube_bridge_. El adaptador lee los plugin.json y mcp.json existentes, lanza solo el runtime stdio local, conserva el contenido de texto e imagen acotado y reenvía únicamente un entorno de procesos hijo en lista de permitidos.

El gestor de paquetes Pi instala la dependencia del adaptador Node pero no instala Python ni ffmpeg. Asegúrate de que el python3 visible para Pi sea Python 3.12+ con las dependencias de tube-bridge instaladas; instala ffmpeg por separado para usar youtube_get_frame. Por defecto, el estado gestionado por Pi reside en el directorio de datos de la plataforma; establece TUBE_BRIDGE_PI_DATA para mover esa raíz. Un TUBE_BRIDGE_CACHE explícito sigue teniendo prioridad para las bases de datos del runtime. La puerta opcional de fotogramas en vivo es /tube-bridge-selftest frame.

Elimina el paquete con:

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

Si un cliente de escritorio no puede encontrar uvx, reemplaza "uvx" con la ruta absoluta devuelta por which uvx en macOS/Linux o where.exe uvx en Windows.

Prueba el flujo de investigación completo

Pregunta a tu agente:

Busca en YouTube videos recientes sobre agentes de IA local-primero. Lee la transcripción del resultado más fuerte, añádela a un corpus llamado local-agents, encuentra la sección que habla de la memoria, devuelve el enlace de origen con marca de tiempo y extrae un fotograma de ese momento.

El agente puede completar esa solicitud con esta secuencia de herramientas:

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)

Añade más videos con corpus_add y luego usa corpus_search para buscar en todas sus transcripciones a la vez.

Herramientas

Herramienta	Clave de API de YouTube	Qué hace
youtube_search	Opcional	Busca videos con filtros de fecha, canal, duración y orden
youtube_get_video_info	Opcional	Obtén título, duración, vistas, canal, descripción y etiquetas
youtube_get_trending	Opcional	Obtén los videos en tendencia actuales
youtube_get_channel_videos	No	Obtén subidas recientes desde una URL de canal o @handle
youtube_get_playlist	No	Obtén videos de una lista de reproducción
youtube_get_transcript	No	Obtén una transcripción, opcionalmente con marcas de tiempo [MM:SS]
youtube_get_frame	No	Devuelve un JPEG efímero cerca de una marca de tiempo en milisegundos enteros
youtube_get_available_languages	No	Enumera pistas de subtítulos manuales y autogeneradas
youtube_get_comments	Requerida	Obtén comentarios de nivel superior con me gusta y recuentos de respuestas
youtube_search_channels	Requerida	Busca canales y filtra por número de suscriptores
youtube_get_channel_info	Requerida	Obtén estadísticas del canal, país y palabras clave
corpus_create	No	Crea un corpus local con nombre
corpus_add	No	Obtén, divide en fragmentos e incrusta localmente una transcripción de video
corpus_search	No	Busca semánticamente en un corpus con resultados con marca de tiempo
corpus_list	No	Enumera corpus con recuentos de videos y fragmentos
corpus_delete	No	Elimina permanentemente un corpus y sus vectores
tube_bridge_help	No	Lee la documentación del runtime y las limitaciones conocidas

No significa que no se necesita clave de YouTube Data API; el acceso de red a YouTube puede seguir siendo necesario. La búsqueda, la información de video y las tendencias funcionan sin clave a través de yt-dlp y se actualizan a Data API v3 cuando se configura una clave.

Clave opcional de YouTube Data API

Una clave de YouTube Data API v3 desbloquea comentarios, búsqueda de canales y detalles de canales. También mejora la búsqueda, la información de video y la fiabilidad de las tendencias.

Crea una clave en Google Cloud Console, habilita YouTube Data API v3 y expónla al proceso que lanza tube-bridge:

export YOUTUBE_API_KEY="your-key"

Mantén las claves fuera de los archivos de configuración MCP confirmados. Usa el soporte de secretos/entorno de tu cliente cuando esté disponible.

Corpus semántico local

El almacenamiento del corpus y la inferencia de incrustaciones son locales a la máquina que ejecuta tube-bridge.

• Almacenamiento: SQLite más sqlite-vec en ~/.tube_bridge/corpus.db
• Incrustaciones: BGE-small-en-v1.5 a través de fastembed
• Fragmentación: ventanas de 80 segundos con solapamiento de 20 segundos
• Clasificación: deduplicación de solapamientos y límites por video conscientes de la fuente
• Resultados: puntuación de similitud, intervalo de tiempo, título del video, URL canónica y URL con marca de tiempo

Establece TUBE_BRIDGE_CACHE para mover tanto las bases de datos del corpus como las de caché:

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

El modelo de incrustación puede descargarse en el primer uso. Una vez que los recursos están disponibles, la inferencia de incrustaciones no requiere una API de modelo externa.

Extracción de fotogramas

youtube_get_frame requiere ffmpeg en PATH; la imagen Docker ya lo incluye.

Cada llamada descarga una sección temporal corta alrededor de timestamp_ms, devuelve un JPEG acotado como MCP ImageContent y elimina el medio temporal antes de devolver. No crea una biblioteca de fotogramas ni clips.

Otras formas de ejecutar

Instalación persistente de PyPI

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

El endpoint de salud es http://localhost:8080/health; el endpoint HTTP Streamable es http://localhost:8080/mcp.

Registro MCP oficial

Nombre del registro: io.github.TheWhiteWater/tube-bridge

Los clientes compatibles con el registro pueden instalar la distribución PyPI con uvx y lanzar el servidor stdio sin un intermediario alojado.

Configuración HTTP remota

Para una instancia HTTP que tú operas:

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

Protege las rutas MCP remotas estableciendo una clave Bearer en el servidor:

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

Luego configura un cliente compatible con cabeceras:

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

/health permanece público. /mcp, /sse y /messages requieren la clave Bearer cuando TUBE_BRIDGE_AUTH_KEY está establecido. SSE heredado está disponible en /sse para clientes que aún lo necesiten.

Variables de entorno

Variable	Requerida	Propósito
YOUTUBE_API_KEY	No	Habilita las 3 herramientas solo de API y mejora las llamadas de descubrimiento compatibles
TUBE_BRIDGE_PROXY	No	Enruta las solicitudes de yt-dlp y transcripciones a través de un proxy HTTP(S) o SOCKS
TUBE_BRIDGE_CACHE	No	Cambia el directorio que contiene cache.db y corpus.db
TUBE_BRIDGE_AUTH_KEY	No	Protege las rutas MCP HTTP autoalojadas con un token Bearer estático

Cómo 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 se recomienda para clientes locales;
• HTTP Streamable está disponible en /mcp para uso remoto autoalojado;
• las respuestas de respaldo exitosas conservan sus esquemas normales;
• los fallos controlados usan errores MCP tipados con campos estables code, source y retryable;
• las bases de datos de caché y corpus son separadas y permanecen en propiedad del operador.

Vista previa del plugin de agente

GitHub Releases incluye tube-bridge-agent-plugin-<version>.zip, que contiene:

• la configuración MCP stdio local;
• la habilidad tube-bridge-research;
• plantillas de investigación y guía de evaluación de fuentes.

Agent Plugins v1 no estandariza la instalación de dependencias. Instala Python 3.12+, ffmpeg y las dependencias del paquete en el entorno utilizado por el host del plugin. El paquete no contiene credenciales.

Limitaciones conocidas

• YouTube puede restringir las solicitudes anónimas de yt-dlp y transcripciones, especialmente desde rangos de IP de alojamiento en la nube.
• Una clave de Data API mejora el descubrimiento y la fiabilidad de los metadatos, pero no reemplaza el acceso a transcripciones.
• La configuración inicial del modelo de incrustación local puede requerir acceso a la red y espacio adicional en disco.
• tube-bridge es software autoalojado; no proporciona cuentas, acceso alojado público, almacenamiento gestionado ni un SLA.

Si YouTube bloquea las solicitudes desde tu red, establece TUBE_BRIDGE_PROXY. Mantén las credenciales del proxy en variables de entorno en lugar de en la configuración confirmada.

Desarrollo

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 es una prueba de humo opcional en vivo de YouTube. La suite de pruebas determinista no llama a YouTube.

Consulta CONTRIBUTING.md para contribuir. Los informes de seguridad deben seguir SECURITY.md.

Licencia

MIT — consulta LICENSE.