Wizzy TMDB

Um wrapper para o TMDB

Documentação

wizzy-mcp-tmdb

Visão Geral e Propósito do Projeto

O projeto wizzy-mcp-tmdb é um servidor MCP (Model Context Protocol) implementado em JavaScript que fornece ferramentas para pesquisar e recuperar informações do The Movie Database (TMDB). Ele permite que clientes de IA acessem dados de filmes, séries de TV e pessoas por meio de um protocolo padronizado.

Principais Recursos

Pesquisar Filmes: Realiza pesquisa múltipla em filmes, séries de TV e pessoas usando a ferramenta search_tmdb.
Obter Detalhes: Busca informações detalhadas para itens específicos usando a ferramenta get_tmdb_details.
Conteúdo em Alta: Recupera conteúdo em alta em todos os tipos de mídia com a ferramenta trending_all.

Instalação

Pré-requisitos

Node.js versão 18 ou superior (necessário para suporte global a fetch)
Uma chave de API TMDB (Bearer token) do seu administrador, usada com o proxy TNL TMDB (production-api.tnl.one)

Configuração

Clone o repositório e navegue até o diretório do projeto.
Instale as dependências:
```
npm install
```

Configure sua chave de API TMDB como uma variável de ambiente:

No Windows PowerShell:

$env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

No macOS/Linux:

export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

Uso

Iniciando o Servidor MCP

Para iniciar o servidor:

npm start

O servidor se comunica via stdio e deve ser configurado no seu cliente compatível com MCP (ex.: IDE ou cliente de chat) com o comando node mcp-tmdb-server.js e a variável de ambiente TMDB_AUTH_TOKEN.

Exemplos de Integração MCP

Aqui estão trechos de código mostrando como integrar com as ferramentas MCP:

Pesquisar Filmes

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

Obter Detalhes do Filme

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

Obter Conteúdo em Alta

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

Integração com Cliente MCP

Para integrar este servidor MCP no seu cliente MCP (como um IDE ou cliente de chat compatível), siga estes passos:

Instale o pacote npm, se necessário:
```
npm install -g wizzy-mcp-tmdb
```

Crie ou atualize o arquivo mcp.json no seu cliente MCP com a seguinte configuração:

{
  "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: O TMDB_AUTH_TOKEN pode ser definido com um valor aleatório por enquanto, pois as chamadas de API TMDB são gratuitas e não exigem autenticação obrigatória.

Estratégia de Testes

O projeto usa Jest para testes abrangentes, incluindo:

Testes Unitários: Validam funções de manipulador individuais, validação de entrada e formatação de resposta (veja tests/unit/handlers.test.js).
Testes de Integração: Testam interações de API com respostas simuladas, tratamento de erros e falhas de rede (veja tests/integration/api.test.js).
Testes de Protocolo: Garantem conformidade com o protocolo MCP, incluindo listagem e chamada de ferramentas (veja tests/protocol/mcp.test.js).

Execute a suíte de testes com:

npm test

Para o modo de observação:

npm run test:watch

Estrutura do Projeto

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

Contribuindo

Aceitamos contribuições! Por favor, siga estas diretrizes:

Faça um fork do repositório.
Crie um branch de funcionalidade.
Faça suas alterações e adicione testes.
Garanta que todos os testes passem.
Envie um pull request.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Agradecemos ao The Movie Database (TMDB) por fornecer a API.
Construído usando o SDK do Model Context Protocol.

Contato

Para perguntas ou suporte, abra uma issue no GitHub.