# IMDb MCP Server 🎬

A powerful Model Context Protocol (MCP) server for searching, discovering, and playing content from IMDb. Built with [FastMCP](https://github.com/punkpeye/fastmcp), this server provides a robust bridge between LLMs and movie metadata, featuring a custom playback layer and a modern web dashboard.

## ✨ Features

- **🚀 FastMCP Engine**: High-performance MCP implementation over streamable HTTP.
- **🔍 Intelligent Search**: Patched search logic using the IMDb Autocomplete API for reliable, unauthenticated title discovery.
- **📺 Playback Layer**: Direct integration with `playimdb.com` for instant streaming links.
- **📊 Monitoring Dashboard**: Password-protected WebUI to monitor metrics, tools, and health in real-time.
- **🐳 Docker Ready**: Optimized multi-stage Dockerfile for easy deployment.
- **🤖 GitHub Actions**: Automated CI/CD workflow to build and push images to GHCR on release tags.

## 🛠️ Tools Included

| Tool | Description |
| :--- | :--- |
| `imdb_search_title` | Search for movies, series, or games. Returns clean metadata including IDs. |
| `imdb_get_public_list_items` | Fetch all items from any public IMDb list by its ID. |
| `play_movie` | Generates a direct `playimdb.com` streaming URL for a given IMDb ID. |
| `search_and_play` | **The Ultimate Tool**: Searches for a title and returns the play URL + full details in a single call. |

## 🚀 Quick Start

### 1. Install dependencies
```bash
npm install
```

### 2. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` to set your `WEBUI_PASSWORD`.

### 3. Run Development Server
```bash
npm run dev
```

## 🌐 Endpoints

- **MCP Endpoint**: `http://127.0.0.1:8080/mcp`
- **Dashboard**: `http://127.0.0.1:8080/dashboard`
- **Health Check**: `http://127.0.0.1:8080/health`

## 🐳 Docker Deployment

Build the image locally:
```bash
docker build -t imdb-mcp .
```

Run the container:
```bash
docker run --rm \
  -p 8080:8080 \
  -e HOST=0.0.0.0 \
  -e PORT=8080 \
  -e WEBUI_PASSWORD=your-secure-password \
  -e WEBUI_SESSION_SECRET=your-secret \
  imdb-mcp
```

### Docker Compose

Alternatively, use Docker Compose to manage the container:

```bash
docker-compose up -d
```

Example `docker-compose.yml`:
```yaml
services:
  imdb-mcp:
    image: ghcr.io/danish-mar/imdb-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - WEBUI_PASSWORD=your-password
```

## 📁 Project Structure

```text
src/
  index.ts       # Entry point & Server initialization
  config.ts      # App configuration & Env loading
  server.ts      # FastMCP instance setup
  tools/         # IMDb tool implementations (Search, Playback, etc.)
  webui/         # Hono routes for the dashboard
  lib/           # Auth & formatting utilities
views/           # EJS templates for the WebUI
.github/         # GitHub Actions workflows for Docker publishing
```

## 📝 Notes

- **Search Patch**: This server uses a custom fallback to the IMDb Autocomplete API because the standard `imdb-core` GraphQL hashes are currently outdated.
- **Authentication**: Most tools are stateless and don't require IMDb cookies. For private list access, you can extend the `imdbClient` session in `src/tools/index.ts`.
- **Playback**: Playback URLs point to third-party providers; use responsibly.

---
Built with ❤️ using FastMCP and TypeScript.