# Servidor MCP para la API de Twitch

Servidor MCP (Model Context Protocol) que proporciona herramientas para interactuar con la API de Twitch. Permite que asistentes de IA y otras aplicaciones accedan a datos de Twitch de manera estructurada y segura.

## 🚀 Características

Este servidor MCP proporciona las siguientes herramientas:

### 📊 Herramientas Disponibles

1. **`get_twitch_user`** - Obtiene información detallada de un usuario
   - Entrada: `login` (nombre de usuario)
   - Devuelve: ID, nombre para mostrar, biografía, imagen de perfil, fecha de creación, etc.

2. **`check_user_live`** - Verifica si un usuario está transmitiendo en vivo
   - Entrada: `login` (nombre de usuario)
   - Devuelve: Datos del stream si está en vivo, `null` si está offline

3. **`get_user_videos`** - Obtiene los videos de un usuario
   - Entrada: `login`, `video_type` (archive/highlight/upload/all), `limit` (1-100)
   - Devuelve: Lista de videos con títulos, duración, vistas, thumbnails, etc.

4. **`get_top_streams`** - Obtiene los streams más populares
   - Entrada: `game_name` (opcional), `limit` (1-100)
   - Devuelve: Lista de streams con espectadores, títulos, juegos, etc.

5. **`get_top_games`** - Obtiene los juegos más populares
   - Entrada: `limit` (1-100)
   - Devuelve: Lista de juegos con nombre, box art, IDs

6. **`search_channels`** - Busca canales por palabras clave
   - Entrada: `query`, `live_only` (bool), `limit` (1-100)
   - Devuelve: Lista de canales coincidentes

7. **`get_game_info`** - Obtiene información de un juego
   - Entrada: `game_name`
   - Devuelve: ID del juego, nombre exacto, box art URL

## 📋 Requisitos Previos

1. **Python 3.10 o superior**
2. **Credenciales de Twitch API**:
   - Ve a https://dev.twitch.tv/console/apps
   - Crea una nueva aplicación
   - Obtén tu `Client ID` y `Client Secret`

## 🔧 Instalación

### Método 1: Con UV (Recomendado) ⚡

**Paso 1:** Instalar UV
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Paso 2:** Configurar y ejecutar
```powershell
cd d:\Workspaces\twitch\mcp
copy .env.example .env
notepad .env  # Agrega tus credenciales

# Ejecutar (UV instalará las dependencias automáticamente)
uv run server.py
```

Ver [QUICKSTART_UV.md](QUICKSTART_UV.md) para más detalles.

### Método 2: Con pip tradicional

**Paso 1:** Navegar al directorio
```powershell
cd d:\Workspaces\twitch\mcp
```

**Paso 2:** Instalar dependencias
```powershell
pip install -r requirements.txt
```

**Paso 3:** Configurar credenciales
```powershell
copy .env.example .env
notepad .env  # Agrega tus credenciales
```

### Método 3: Contenedor Docker 🐳

**Paso 1:** Crear tu archivo de variables de entorno (se reutiliza fuera del contenedor)
```powershell
cd d:\Workspaces\twitch\mcp
copy .env.example .env
notepad .env  # Agrega tus credenciales de Twitch
```

**Paso 2:** Construir la imagen
```powershell
docker build -t twitch-mcp .
```

**Paso 3:** Ejecutar el contenedor en modo SSE (puedes reutilizar el mismo `.env`)
```powershell
docker run --rm --name twitch-mcp --env-file .env -p 8000:8000 twitch-mcp
```

> Usa `` `--host 0.0.0.0` `` dentro del contenedor para exponer el servidor. El `CMD` por defecto ya incluye ese valor.

**Personalizar host/puerto:**
```powershell
docker run --rm --name twitch-mcp --env-file .env -p 9000:9000 twitch-mcp python server.py --mode sse --host 0.0.0.0 --port 9000
```

**Modo stdio desde Docker:**
El modo stdio requiere interactuar con stdin/stdout del contenedor. Puedes lanzar:
```powershell
docker run --rm --name twitch-mcp-stdio --env-file .env -i twitch-mcp python server.py --mode stdio
```
Ten en cuenta que la mayoría de clientes MCP esperan ejecutar el binario directamente en tu máquina, por lo que este modo desde Docker suele usarse solo para pruebas puntuales.

### Método 4: Docker Compose ⚙️

Ideal para dejar el servidor corriendo en segundo plano y reiniciarlo automáticamente si se cae.

**Paso 1:** Asegúrate de tener tu `.env` listo (mismo que en el método Docker).

**Paso 2:** Levanta el servicio y construye la imagen (solo la primera vez o cuando cambies el código):
```powershell
docker compose up --build
```

El servicio quedará escuchando en `http://localhost:8000/sse`.

**Ejecutar en segundo plano:**
```powershell
docker compose up -d
```

**Detener:**
```powershell
docker compose down
```

**Sobrescribir parámetros (por ejemplo, otro puerto):**
```powershell
docker compose run --rm -p 9000:9000 twitch-mcp python server.py --mode sse --host 0.0.0.0 --port 9000
```
El archivo `docker-compose.yml` mapea el puerto `8000` por defecto y reutiliza el `.env` para tus credenciales.

### Despliegue continuo con GitHub Actions 🚀

Se incluyó un workflow en `.github/workflows/deploy-mcp.yml` que sincroniza la carpeta `mcp` con tu VPS y ejecuta `docker compose up -d --build` automáticamente cuando haces push a `master`.

1. En tu repositorio de GitHub crea los siguientes **Secrets** (Settings → Secrets and variables → Actions):
  - `VPS_HOST`: IP o dominio de tu VPS.
  - `VPS_PORT`: Puerto SSH (usa `22` si es el predeterminado).
  - `VPS_USER`: Usuario con permisos para ejecutar Docker.
  - `VPS_SSH_KEY`: Clave privada en formato PEM autorizada en la VPS (sin passphrase).
  - `VPS_APP_PATH`: Ruta absoluta en la VPS donde se copiará el proyecto (ej. `/opt/twitch`).
2. Asegúrate de que en el VPS exista el archivo `mcp/.env` con tus credenciales antes del primer despliegue (se preserva entre despliegues).
3. Ejecuta `docker compose up -d` manualmente la primera vez si quieres validar que todo funciona.

El workflow también puede iniciarse manualmente desde la pestaña **Actions** (evento `workflow_dispatch`).

## 🎯 Uso

### Modo 1: STDIO (para clientes MCP como Claude Desktop)

**Con UV:**
```powershell
uv run server.py
# O usa el script de inicio
.\run.bat
```

**Con Python tradicional:**
```powershell
python server.py
```

### Modo 2: SSE (para desarrollo y testing)

El modo SSE permite conectarte al servidor desde un navegador o herramientas de testing como **MCP Inspector**.

**Con UV:**
```powershell
# Ejecutar en modo SSE (puerto 8000 por defecto)
uv run server.py --mode sse

# O usa el script de inicio
.\run-sse.bat

# Personalizar host y puerto
uv run server.py --mode sse --host 0.0.0.0 --port 3000
```

**Con Python tradicional:**
```powershell
python server.py --mode sse
```

Una vez iniciado, verás algo como:
```
🚀 Servidor MCP de Twitch en modo SSE
📡 Escuchando en http://localhost:8000
🔗 Endpoint SSE: http://localhost:8000/sse
📨 Endpoint Messages: http://localhost:8000/messages

💡 Tip: Usa MCP Inspector para conectarte:
   npx @modelcontextprotocol/inspector http://localhost:8000/sse
```

### Autenticación OAuth en modo SSE

- El servidor implementa OAuth 2.1 con **grant type `client_credentials`** y **registro dinámico de clientes** (RFC 7591).
- Los metadatos se exponen en `/.well-known/oauth-authorization-server` tal como indica la especificación MCP 2025-03-26.
- Clientes (por ejemplo, ChatGPT connectors) pueden registrarse automáticamente enviando un `POST /register` con `redirect_uris`.
- Para obtener tokens, envía un `POST /token` con `grant_type=client_credentials`, `client_id` y `client_secret` (método `client_secret_post`).
- Los tokens emitidos deben enviarse como `Authorization: Bearer <token>` en **todas** las llamadas a `/sse` y `/messages`.
- Personaliza la URL pública con `MCP_PUBLIC_BASE_URL` si expones el servidor detrás de un proxy o dominio distinto.

### Testear con MCP Inspector

```powershell
# Instalar MCP Inspector (si no lo tienes)
npm install -g @modelcontextprotocol/inspector

# Conectarse al servidor SSE
npx @modelcontextprotocol/inspector http://localhost:8000/sse
```

### Configurar en Claude Desktop (o cualquier cliente MCP)

Ver guía completa: **[CLAUDE_SETUP.md](CLAUDE_SETUP.md)** 📖

**Resumen rápido** - Con UV (Recomendado) - Windows (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "twitch": {
      "command": "uv",
      "args": [
        "--directory",
        "d:\\Workspaces\\twitch\\mcp",
        "run",
        "server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}
```

**Con Python tradicional** - Windows:

```json
{
  "mcpServers": {
    "twitch": {
      "command": "python",
      "args": [
        "d:\\Workspaces\\twitch\\mcp\\server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}
```

**macOS/Linux** (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "twitch": {
      "command": "uv",
      "args": [
        "--directory",
        "/ruta/absoluta/a/twitch/mcp",
        "run",
        "server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}
```

## 💡 Ejemplos de Uso

Una vez configurado el servidor en tu cliente MCP, puedes hacer preguntas como:

- "¿Está **a_robertdev** en vivo en Twitch?"
- "Dame los últimos 10 videos de **shroud**"
- "¿Cuáles son los 5 juegos más populares en Twitch ahora?"
- "Busca canales que transmitan **Minecraft**"
- "Dame información del usuario **ninja**"

## 🏗️ Arquitectura

```
mcp/
├── server.py              # Servidor MCP principal (soporta stdio y SSE)
├── twitch_client.py       # Cliente de Twitch API con OAuth y rate limiting
├── pyproject.toml         # Configuración del proyecto para UV
├── requirements.txt       # Dependencias de Python (pip)
├── .env.example           # Plantilla de configuración
├── .gitignore            # Archivos ignorados por git
├── run.bat               # Script de inicio para Windows (stdio)
├── run.sh                # Script de inicio para macOS/Linux (stdio)
├── run-sse.bat           # Script de inicio para Windows (SSE)
├── run-sse.sh            # Script de inicio para macOS/Linux (SSE)
├── README.md             # Este archivo
├── QUICKSTART_UV.md      # Guía rápida para UV
├── SSE_GUIDE.md          # Guía completa del modo SSE
└── EXAMPLES.md           # Ejemplos de uso prácticos
```

### Características del Cliente Twitch

- ✅ **OAuth automático** - Manejo de tokens con renovación automática
- ✅ **Rate limiting** - Detecta y maneja límites de tasa (800 req/min)
- ✅ **Paginación** - Soporte automático para resultados paginados
- ✅ **Manejo de errores** - Respuestas estructuradas con información útil
- ✅ **Cache de tokens** - Tokens válidos se reutilizan durante ~1 hora

## 🔒 Seguridad

- **Nunca** commitees tu archivo `.env` o expongas tus credenciales
- El archivo `.env` está en `.gitignore` por defecto
- Las credenciales se pasan como variables de entorno, no se guardan en código

## 🛠️ Desarrollo

### Agregar nuevas herramientas

1. Define la herramienta en `handle_list_tools()` con su schema JSON
2. Implementa la lógica en `handle_call_tool()`
3. Si necesitas un nuevo endpoint de Twitch, agrégalo en `twitch_client.py`

### Debugging

El servidor imprime mensajes de diagnóstico en `stderr`:

```
✅ Twitch API inicializada correctamente
```

Si hay errores de credenciales:

```
❌ Error al inicializar Twitch API: ...
💡 Verifica que TWITCH_CLIENT_ID y TWITCH_CLIENT_SECRET estén configurados
```

## 📚 Recursos

- **[QUICKSTART_UV.md](QUICKSTART_UV.md)** - Guía rápida para usar UV
- **[SSE_GUIDE.md](SSE_GUIDE.md)** - Guía completa del modo SSE para desarrollo
- **[EXAMPLES.md](EXAMPLES.md)** - Ejemplos prácticos de uso
- [Twitch API Documentation](https://dev.twitch.tv/docs/api/)
- [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [UV Documentation](https://docs.astral.sh/uv/)

## 🤝 Contribuciones

Este servidor es parte del proyecto Twitch API Integration. Para mejoras o reportar bugs, consulta el repositorio principal.

## 📝 Licencia

Parte del proyecto Twitch API Integration - Uso educativo y personal.

---

**¡Disfruta integrando Twitch con tus asistentes de IA! 🎮🤖**