Wizzy TMDB

Un envoltorio para TMDB

Documentación

wizzy-mcp-tmdb

Resumen y Propósito del Proyecto

El proyecto wizzy-mcp-tmdb es un servidor MCP (Model Context Protocol) implementado en JavaScript que proporciona herramientas para buscar y recuperar información de The Movie Database (TMDB). Permite que los clientes de IA accedan a datos de películas, programas de televisión y personas a través de un protocolo estandarizado.

Características Principales

Buscar Películas: Realiza búsquedas múltiples en películas, programas de televisión y personas usando la herramienta search_tmdb.
Obtener Detalles: Recupera información detallada de elementos específicos usando la herramienta get_tmdb_details.
Contenido en Tendencia: Recupera contenido en tendencia en todos los tipos de medios con la herramienta trending_all.

Instalación

Requisitos Previos

Node.js versión 18 o superior (requerido para soporte global de fetch)
Una clave de API de TMDB (token Bearer) de tu administrador, utilizada con el proxy TNL TMDB (production-api.tnl.one)

Configuración

Clona el repositorio y navega al directorio del proyecto.
Instala las dependencias:
```
npm install
```

Configura tu clave de API de TMDB como variable de entorno:

En Windows PowerShell:

$env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

En macOS/Linux:

export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

Uso

Iniciando el Servidor MCP

Para iniciar el servidor:

npm start

El servidor se comunica a través de stdio y debe configurarse en tu cliente compatible con MCP (por ejemplo, IDE o cliente de chat) con el comando node mcp-tmdb-server.js y la variable de entorno TMDB_AUTH_TOKEN.

Ejemplos de Integración MCP

Aquí hay fragmentos de código que muestran cómo integrarse con las herramientas MCP:

Buscar Películas

// Example MCP tool call for searching
{
  "method": "tools/call",
  "params": {
    "name": "search_tmdb",
    "arguments": {
      "query": "dune",
      "page": 1,
      "language": "en-US",
      "include_adult": false
    }
  }
}

Obtener Detalles de una Película

// Example MCP tool call for getting details
{
  "method": "tools/call",
  "params": {
    "name": "get_tmdb_details",
    "arguments": {
      "type": "movie",
      "id": 438631,
      "append": "credits,images"
    }
  }
}

Obtener Contenido en Tendencia

// Example MCP tool call for trending content
{
  "method": "tools/call",
  "params": {
    "name": "trending_all",
    "arguments": {
      "time_window": "day",
      "page": 1,
      "language": "en-US"
    }
  }
}

Integración con Cliente MCP

Para integrar este servidor MCP en tu cliente MCP (como un IDE o un cliente de chat compatible), sigue estos pasos:

Instala el paquete npm si es necesario:
```
npm install -g wizzy-mcp-tmdb
```

Crea o actualiza el archivo mcp.json en tu cliente MCP con la siguiente configuración:

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["wizzy-mcp-tmdb"],
      "env": {
        "TMDB_AUTH_TOKEN": "YOUR_TNL_PROXY_BEARER_TOKEN"
      },
      "alwaysAllow": [
        "get_watch_providers",
        "discover_tv",
        "discover_by_provider"
      ]
    }
  }
}

Nota: El TMDB_AUTH_TOKEN puede establecerse a un valor aleatorio por ahora, ya que las llamadas a la API de TMDB son gratuitas y no requieren autenticación obligatoria.

Estrategia de Pruebas

El proyecto utiliza Jest para pruebas exhaustivas, incluyendo:

Pruebas Unitarias: Validan funciones de manejo individuales, validación de entrada y formato de respuestas (ver tests/unit/handlers.test.js).
Pruebas de Integración: Prueban interacciones con la API usando respuestas simuladas, manejo de errores y fallos de red (ver tests/integration/api.test.js).
Pruebas de Protocolo: Aseguran el cumplimiento del protocolo MCP, incluyendo listado y llamada de herramientas (ver tests/protocol/mcp.test.js).

Ejecuta la suite de pruebas con:

npm test

Para modo de observación:

npm run test:watch

Estructura del Proyecto

wizzy-mcp-tmdb/
├── mcp-tmdb-server.js          # Main MCP server implementation
├── package.json                # Project configuration and dependencies
├── MCP_GUIDE.md                # Detailed MCP integration guide
├── babel.config.cjs            # Babel configuration for Jest
├── tests/
│   ├── unit/
│   │   └── handlers.test.js    # Unit tests for handlers
│   ├── integration/
│   │   └── api.test.js         # Integration tests for API calls
│   └── protocol/
│       └── mcp.test.js         # MCP protocol compliance tests
└── tests/fixtures/             # Mock data for tests
    ├── movieDetails.json
    ├── searchMultiResponse.json
    └── trendingAllResponse.json

Contribuciones

¡Agradecemos las contribuciones! Por favor, sigue estas pautas:

Haz un fork del repositorio.
Crea una rama de características.
Realiza tus cambios y añade pruebas.
Asegúrate de que todas las pruebas pasen.
Envía una solicitud de extracción (pull request).

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Agradecimientos

Gracias a The Movie Database (TMDB) por proporcionar la API.
Construido usando el SDK de Model Context Protocol.

Contacto

Para preguntas o soporte, por favor abre un issue en GitHub.