Wizzy MCP Tmdb

1# wizzy-mcp-tmdb
2 
3[![Build Status](https://img.shields.io/github/actions/workflow/status/drakonkat/wizzy-mcp-tmdb/ci.yml)](https://github.com/drakonkat/wizzy-mcp-tmdb/actions)
4 
5[![Coverage](https://img.shields.io/codecov/c/github/drakonkat/wizzy-mcp-tmdb)](https://codecov.io/gh/drakonkat/wizzy-mcp-tmdb)
6 
7## Project Overview and Purpose
8 
9The wizzy-mcp-tmdb project is an MCP (Model Context Protocol) server implemented in JavaScript that provides tools to search and retrieve information from The Movie Database (TMDB). It allows AI clients to access movie, TV show, and person data through a standardized protocol.
10 
11## Key Features
12 
13- **Search Movies**: Perform multi-search across movies, TV shows, and people using the `search_tmdb` tool.
14- **Get Details**: Fetch detailed information for specific items using the `get_tmdb_details` tool.
15- **Trending Content**: Retrieve trending content across all media types with the `trending_all` tool.
16 
17## Installation
18 
19### Prerequisites
20 
21- Node.js version 18 or higher (required for global fetch support)
22- A TMDB API key (Bearer token) from your admin, used with the TNL TMDB proxy (production-api.tnl.one)
23 
24### Setup
25 
261. Clone the repository and navigate to the project directory.
27 
282. Install dependencies:
29 
30   ```bash
31   npm install
32   ```
33 
343. Set up your TMDB API key as an environment variable:
35 
36   - On Windows PowerShell:
37     ```powershell
38     $env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
39     ```
40 
41   - On macOS/Linux:
42     ```bash
43     export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
44     ```
45 
46## Usage
47 
48### Starting the MCP Server
49 
50To start the server:
51 
52```bash
53npm start
54```
55 
56The server communicates over stdio and should be configured in your MCP-compatible client (e.g., IDE or chat client) with the command `node mcp-tmdb-server.js` and the `TMDB_AUTH_TOKEN` environment variable.
57 
58### MCP Integration Examples
59 
60Here are code snippets showing how to integrate with the MCP tools:
61 
62#### Search for Movies
63 
64```javascript
65// Example MCP tool call for searching
66{
67  "method": "tools/call",
68  "params": {
69    "name": "search_tmdb",
70    "arguments": {
71      "query": "dune",
72      "page": 1,
73      "language": "en-US",
74      "include_adult": false
75    }
76  }
77}
78```
79 
80#### Get Movie Details
81 
82```javascript
83// Example MCP tool call for getting details
84{
85  "method": "tools/call",
86  "params": {
87    "name": "get_tmdb_details",
88    "arguments": {
89      "type": "movie",
90      "id": 438631,
91      "append": "credits,images"
92    }
93  }
94}
95```
96 
97#### Get Trending Content
98 
99```javascript
100// Example MCP tool call for trending content
101{
102  "method": "tools/call",
103  "params": {
104    "name": "trending_all",
105    "arguments": {
106      "time_window": "day",
107      "page": 1,
108      "language": "en-US"
109    }
110  }
111}
112```
113 
114## MCP Client Integration
115 
116Per integrare questo MCP server nel tuo client MCP (come un IDE o un client di chat compatibile), segui questi passi:
117 
1181. Installa il pacchetto npm se necessario:
119 
120   ```bash
121   npm install -g wizzy-mcp-tmdb
122   ```
123 
1242. Crea o aggiorna il file `mcp.json` nel tuo client MCP con la seguente configurazione:
125 
126   ```json
127   {
128     "mcpServers": {
129       "tmdb": {
130         "command": "npx",
131         "args": ["wizzy-mcp-tmdb"],
132         "env": {
133           "TMDB_AUTH_TOKEN": "YOUR_TNL_PROXY_BEARER_TOKEN"
134         },
135         "alwaysAllow": [
136           "get_watch_providers",
137           "discover_tv",
138           "discover_by_provider"
139         ]
140       }
141     }
142   }
143   ```
144 
145   Nota: Il `TMDB_AUTH_TOKEN` può essere impostato a un valore casuale per ora, poiché le chiamate API TMDB sono gratuite e non richiedono autenticazione obbligatoria.
146 
147## Testing Strategy
148 
149The project uses Jest for comprehensive testing, including:
150 
151- **Unit Tests**: Validate individual handler functions, input validation, and response formatting (see `tests/unit/handlers.test.js`).
152- **Integration Tests**: Test API interactions with mocked responses, error handling, and network failures (see `tests/integration/api.test.js`).
153- **Protocol Tests**: Ensure MCP protocol compliance, including tool listing and calling (see `tests/protocol/mcp.test.js`).
154 
155Run the test suite with:
156 
157```bash
158npm test
159```
160 
161For watch mode:
162 
163```bash
164npm run test:watch
165```
166 
167## Project Structure
168 
169```
170wizzy-mcp-tmdb/
171├── mcp-tmdb-server.js          # Main MCP server implementation
172├── package.json                # Project configuration and dependencies
173├── MCP_GUIDE.md                # Detailed MCP integration guide
174├── babel.config.cjs            # Babel configuration for Jest
175├── tests/
176│   ├── unit/
177│   │   └── handlers.test.js    # Unit tests for handlers
178│   ├── integration/
179│   │   └── api.test.js         # Integration tests for API calls
180│   └── protocol/
181│       └── mcp.test.js         # MCP protocol compliance tests
182└── tests/fixtures/             # Mock data for tests
183    ├── movieDetails.json
184    ├── searchMultiResponse.json
185    └── trendingAllResponse.json
186```
187 
188## Contributing
189 
190We welcome contributions! Please follow these guidelines:
191 
1921. Fork the repository.
1932. Create a feature branch.
1943. Make your changes and add tests.
1954. Ensure all tests pass.
1965. Submit a pull request.
197 
198## License
199 
200This project is licensed under the MIT License. See the LICENSE file for details.
201 
202## Acknowledgments
203 
204- Thanks to The Movie Database (TMDB) for providing the API.
205- Built using the Model Context Protocol SDK.
206 
207## Contact
208 
209For questions or support, please open an issue on GitHub.
210