# IMDb MCP App

An MCP server that answers natural-language movie questions ("top 10 popular horror movies", "highest rated movie", "10 movies with Nicolas Cage") using live TMDb data, with React views rendered inline in chat.

## Setup

1. Get a free TMDb API Read Access Token: https://www.themoviedb.org/settings/api
2. Copy `.env.example` to `.env` and set `TMDB_API_KEY` to that token.
3. (Optional) Get a free OMDb API key at https://www.omdbapi.com/apikey.aspx and set `OMDB_API_KEY` in `.env` to add real IMDb rating and Metacritic score to `get-movie-details`. Leave it blank to skip.
4. (Optional) Set `CLERK_DOMAIN`, `TRAKT_CLIENT_ID`, `TRAKT_CLIENT_SECRET`, `UPSTASH_REDIS_REST_URL`, and `UPSTASH_REDIS_REST_TOKEN` in `.env` (see the comments in `.env.example`) to enable the `connect-trakt` tool. Leave them all blank to skip — every other tool works with zero sign-in regardless.
5. `npm install`

## Development

- `npm run dev` — starts a local MCP server with hot reload, plus a devtools URL for invoking tools and previewing views.
- `npm run dev:tunnel` — same as `dev`, plus a public tunnel URL (`{tunnel-url}/mcp`) you can add as a custom connector in Claude or ChatGPT to test before deploying.
- `npm test` — runs the unit test suite. It covers pure logic only (query building, mapping, pagination decisions, schemas); code that calls TMDb, OMDb, Rotten Tomatoes, Trakt, or Upstash directly is exercised manually against the live API instead of mocked.

## Tools

- **`search-movies`** — search and rank movies by popularity, rating, genre, person (actor or director), or release year range.
  - `genre` (optional) — genre name, e.g. `"horror"`, `"comedy"`.
  - `person` (optional) — actor or director name, e.g. `"Nicolas Cage"`.
  - `sort_by` — `popularity` | `rating` | `newest` | `oldest` (default `popularity`).
  - `min_year` / `max_year` (optional) — release-year range.
  - `limit` — number of movies to return, 1–25 (default 10).
- **`get-movie-details`** — look up full details (synopsis, cast, director, runtime, rating, IMDb link, Rotten Tomatoes Tomatometer/audience score, plus real IMDb rating/Metacritic score when `OMDB_API_KEY` is configured) for one specific movie.
  - `title` — the movie title to look up.
- **`connect-trakt`** — link your Trakt.tv account so future features can know what you've already watched. Requires signing in (Clerk) and `CLERK_DOMAIN`/`TRAKT_CLIENT_ID`/`TRAKT_CLIENT_SECRET`/`UPSTASH_REDIS_REST_URL`/`UPSTASH_REDIS_REST_TOKEN` all configured — every other tool works with zero sign-in regardless.

## Deploy

- `npm run build` — builds the production bundle (also what `alpic deploy` runs from the Dockerfile).
- `npm run deploy` — deploys via Alpic. Requires `TMDB_API_KEY` to be set as an environment variable/secret in the deploy target; `OMDB_API_KEY` is optional there too, same as local `.env`.

### Docker

Build and run the server in a container:

```
docker build -t imdb-mcp-app .
docker run --rm -p 3000:3000 --env-file .env imdb-mcp-app
```

The server listens on Skybridge's `__PORT` env var (default `3000`) — see the comment in `Dockerfile` if you're deploying to a platform that injects a different `PORT` variable.