# YouTube MCP

Una implementación de Model Context Protocol (MCP) para buscar y reproducir canciones en YouTube directamente desde tu navegador.

## Tabla de Contenidos

- [Características](#características)
- [Instalación](#instalación)
- [Uso](#uso)
- [Tests](#tests)
- [Calidad de Código](#calidad-de-código)
- [Estructura del Proyecto](#estructura-del-proyecto)
- [Herramientas Disponibles](#herramientas-disponibles)
- [Ejemplos de Prompts](#ejemplos-de-prompts)
- [Requisitos de API Key](#requisitos-de-api-key)
- [Soporte de Sistemas Operativos](#soporte-de-sistemas-operativos)
- [Licencia](#licencia)
- [Contribuciones](#contribuciones)

## Características

- 🔍 Buscar canciones en YouTube usando la API oficial
- 🎵 Reproducir canciones en el navegador automáticamente
- 🖥️ Soporte multi-plataforma (Windows, macOS, Linux)
- 📦 Fácil integración con herramientas que soporten MCP
- ✅ Validación completa de inputs (API Keys, URLs, búsquedas)
- 📝 Type hints modernos (Python 3.9+)
- 🧪 Cobertura de tests completa (59 tests, 100% passing)
- 📊 Logging estructurado y centralización de configuración

## Instalación

### 1. Clonar/Crear el proyecto

```bash
cd youtube_mcp
# O: git clone https://github.com/roquevaamonde/youtube-mcp.git youtube_mcp
```

### 2. Crear el virtual environment

```bash
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
```

### 3. Instalar dependencias

```bash
pip install -r requirements.txt
```

### 4. Configurar API Key

Sigue estos pasos para obtener tu API Key de YouTube:

1. **Acceder a Google Cloud Console**: Dirígete a [Google Cloud Console](https://console.cloud.google.com/)
2. **Crear un nuevo proyecto**:
   - Haz clic en el selector de proyecto en la parte superior
   - Selecciona "Nuevo Proyecto"
   - Asigna un nombre (ej: "YouTube MCP")
   - Clic en "Crear"
3. **Habilitar YouTube Data API v3**:
   - Ve a [APIs & Services > Library](https://console.cloud.google.com/apis/library)
   - Busca "YouTube Data API v3"
   - Haz clic en el resultado
   - Clic en "Habilitar"
4. **Crear una API Key**:
   - Ve a [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials)
   - Clic en "Crear credenciales" → "Clave de API"
   - Copia la clave generada
5. **Configurar en tu proyecto**:

```bash
cp .env.example .env
# Edita .env y añade tu YOUTUBE_API_KEY
# YOUTUBE_API_KEY=tu_clave_aqui
```

### 5. Configurar en VS Code

1. Abre las configuraciones de VS Code (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)")
2. Localiza o crea la sección `"modelContextProtocol"`
3. Agrega la configuración del servidor YouTube:

```json
{
  "modelContextProtocol": {
    "servers": {
      "youtube": {
        "type": "stdio",
        "command": "{python-path}",
        "args": ["{project-path}/youtube_mcp_server.py"],
        "disabled": false,
        "autoApprove": [],
        "env": {
          "YOUTUBE_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}
```

Reemplaza:
- `{python-path}`: Ruta completa a tu Python (ej: `/usr/bin/python3` o `C:\Python\python.exe`)
- `{project-path}`: Ruta del proyecto (ej: `/home/user/projects/youtube_mcp`)
- `your_api_key_here`: Tu API Key de YouTube

## Uso

```python
from youtube_mcp.server import YouTubeMCPServer

server = YouTubeMCPServer(api_key="your_api_key")

# Ejemplo 1: Reproducir el primer resultado (tema suelto)
results = server.handle_search_youtube(query="Bohemian Rhapsody Queen", max_results=5)
if results.get("success") and results.get("results"):
    first_url = results["results"][0]["url"]
    server.handle_play_youtube(first_url)
```

Snippets MCP (JSON) para el mismo flujo:

```json
{
  "tool": "search_youtube",
  "params": {
    "query": "Bohemian Rhapsody Queen",
    "max_results": 5
  }
}
```

Con el `url` del primer resultado devuelto, reproducir:

```json
{
  "tool": "play_youtube",
  "params": {
    "url": "https://www.youtube.com/watch?v=<VIDEO_ID>"
  }
}
```

### Ejemplos avanzados

- Playlist con orden explícito (por IDs conocidos):

  Python:
  ```python
  video_ids = ["VIDEO1", "VIDEO2", "VIDEO3", "VIDEO4"]
  # Método recomendado (determinista): watch_videos con video_ids
  playlist_url = f"https://www.youtube.com/watch_videos?video_ids={','.join(video_ids)}"
  server.handle_play_youtube(playlist_url)
  ```

  JSON MCP:
  ```json
  {
    "tool": "play_youtube",
    "params": {
      "url": "https://www.youtube.com/watch_videos?video_ids=VIDEO1,VIDEO2,VIDEO3,VIDEO4"
    }
  }
  ```

  Alternativa (menos determinista en algunos navegadores):

  ```json
  {
    "tool": "play_youtube",
    "params": {
      "url": "https://www.youtube.com/watch?v=VIDEO1&playlist=VIDEO2,VIDEO3,VIDEO4&autoplay=1"
    }
  }
  ```

- Reproducción continua (Mix de YouTube) para un tema:

  Python:
  ```python
  video_id = "VIDEO_ID"
  mix_url = f"https://www.youtube.com/watch?v={video_id}&list=RD{video_id}&autoplay=1"
  server.handle_play_youtube(mix_url)
  ```

  JSON MCP:
  ```json
  {
    "tool": "play_youtube",
    "params": {
      "url": "https://www.youtube.com/watch?v=VIDEO_ID&list=RDVIDEO_ID&autoplay=1"
    }
  }
  ```

## Tests

```bash
pytest tests/
```

**Cobertura de Tests**: 59 tests que cubren:
- ✅ Búsqueda de canciones en YouTube (YouTubeClient)
- ✅ Reproducción de videos en navegador (BrowserController)
- ✅ Detección de Sistema Operativo (Windows, macOS, Linux, WSL)
- ✅ Gestión de procesos de navegador
- ✅ Validadores de URL, API Keys, búsquedas y max_results
- ✅ Servidor MCP y orquestación de herramientas
- ✅ Manejo de errores y casos edge

Para ver la cobertura de código:
```bash
pytest tests/ --cov=youtube_mcp --cov-report=term-missing
```

## Calidad de Código

Este proyecto incluye:

- **Validación de inputs**: Módulo `validators.py` con validación completa para:
  - API Keys (longitud mínima 20 caracteres)
  - URLs de YouTube (validación con regex)
  - Queries de búsqueda (1-300 caracteres)
  - Max results (1-50)

- **Type hints modernos**: Uso de `dict`, `list`, `tuple` en lugar de `typing` (Python 3.9+)

- **Logging estructurado**: Setup centralizado con `logger.py`

- **Constantes**: Configuración centralizada en `constants.py` para:
  - Mensajes de error y éxito
  - Detectores de SO (Windows, macOS, Linux, WSL)
  - Configuración por defecto (región, max_results)
  - Formato de logging

## Estructura del proyecto

```
youtube_mcp/
├── youtube_mcp/
│   ├── __init__.py
│   ├── youtube_client.py      # Cliente de YouTube API
│   ├── browser_controller.py   # Controlador de navegador multi-plataforma
│   ├── server.py              # Servidor MCP con herramientas
│   ├── validators.py          # Validación de inputs
│   ├── constants.py           # Constantes y configuración centralizada
│   └── logger.py              # Setup de logging
├── tests/                      # Tests con pytest (59 tests, 100% passing)
├── config/                     # Archivos de configuración
├── docs/                       # Documentación
├── requirements.txt
├── .env.example
└── README.md
```

## Herramientas disponibles

### search_youtube

Busca una canción en YouTube.

**Parámetros:**
- `query` (string, requerido): Nombre de la canción o artista
- `max_results` (integer, opcional): Número máximo de resultados (default: 5)
- `play` (boolean, opcional): Si es true, abre el primer resultado en el navegador

**Ejemplo:**
```json
{
  "query": "Bohemian Rhapsody Queen",
  "max_results": 5,
  "play": false
}
```

### play_youtube

Reproduce una canción en YouTube abriendo el enlace del video en el navegador.

**Parámetros:**
- `url` (string, requerido): Enlace de YouTube del video a reproducir

**Ejemplo:**
```json
{
  "url": "https://www.youtube.com/watch?v=<VIDEO_ID>"
}
```

También puedes pasar URLs de playlist o Mix:

```json
{
  "url": "https://www.youtube.com/watch?v=VIDEO1&playlist=VIDEO2,VIDEO3,VIDEO4&autoplay=1"
}
```

```json
{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID&list=RDVIDEO_ID&autoplay=1"
}
```

## Ejemplos de Prompts

A continuación tienes ejemplos prácticos para pedir búsquedas, listas/colas y reproducción en bucle o continua. Puedes combinarlos y ser específico con el orden, el artista y la cantidad.

- Reproducción directa (tema suelto):
  - "Pon King Kong de Midas Alonso"
  - "Reproduce Bohemian Rhapsody de Queen y súbelo a 1080p si hay opción"

- Reproducción en bucle o continua:
  - "Déjalo en bucle" (el agente puede activar el modo loop del reproductor o usar el Mix de YouTube cuando corresponda)
  - "Activa el Mix de YouTube de esta canción para que siga solo"
  - "Ponlo en repetición por 30 minutos"

- Listas/colas personalizadas (orden explícito):
  - "Prepárame una cola con BRIXTON, GRAND PRIX, CLUEDO y TYRION de Midas Alonso en ese orden y reprodúcela"
  - "Crea una playlist de 8 temas de Yung Beef empezando por Me Perdí en Madrid y mezclando con artistas similares"

- Búsquedas versátiles y por criterios:
  - "Busca 5 temas de PXXR GVNG y pon el mejor resultado oficial"
  - "Haz una playlist de 10 temas de rap español 2015–2018 y reprodúcela"
  - "Mezcla clásicos de Yung Beef con temas nuevos y activa autoplay"

Notas:
- Para reproducción en bucle exacta de un único tema, el agente puede usar el modo loop del reproductor en tu navegador. Si no está disponible, intentará alternativas como el Mix o repetir la pista al finalizar.
- Para colas dinámicas, el agente puede crear una playlist temporal en YouTube y abrirla con autoplay.

## Requisitos de API Key

La API Key necesita las siguientes APIs habilitadas:
- YouTube Data API v3

## Soporte de sistemas operativos

- ✅ Windows
- ✅ macOS
- ✅ Linux

## Licencia

Archivo LICENCE

## Contribuciones

Ver archivo CONTRIBUTING.md