# IMSDb Movie Catch-Up MCP

An MCP server that gives an LLM the tools to catch you up on a movie you joined partway through. Describe the scene you're at, and it recaps everything before that point with no spoilers for what comes after.

## How it works
1. You give the LLM a movie title and a description of where you are.
2. `movie_matcher` checks the SQLite cache. If the movie isn't there, it scrapes the script from IMSDb, splits it into scenes by detecting `INT.`/`EXT.` headings, writes a one-line summary of each scene with Claude, and stores everything.
3. `movie_matcher` returns the scene summaries, and the LLM picks the scene that matches your description.
4. `summary_to_full` returns the full text of every scene up to that point, and the LLM writes the spoiler-free recap.

## Design Decisions
- The summaries are cached to reduce the amount of API calls. Each scene requires an API call to be summarized, so by caching them, we can reduce the API calls the second time a movie is asked about by the amount of scenes in the movie (often 90+). This also increases speed of the response. 
- **Matching is done by the LLM, not code.** Viewers describe a scene in their own words and notice different details, so there's rarely a word-for-word match. Fuzzy matching is what an LLM does well.
- **One shared SQLite table.** A new movie is new rows, not a new table. Separate tables would mean generating table names from movie titles at runtime.

## Setup
1. Install [uv](https://docs.astral.sh/uv/) and run `uv sync`.
2. Create a `.env` file with `ANTHROPIC_API_KEY=your-key` (requires API credits).
3. Test with the MCP Inspector: `uv run mcp dev server.py` (needs Node.js).
4. To use with Claude Desktop, add this to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "imsdb-recap": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/this/repo", "server.py"]
    }
  }
}
```

## Known Limitations
- Pariah parses to 91 scenes, not the script's 88 numbered ones. Lettered scenes (84A, 84B) are counted separately, and one extra heading wasn't traced. Scene numbers are this tool's own count, not the script's printed numbers, and matching works on those.
- The titles of the movie must match what IMSDb has, or the LLM must be able to check for multiple possible matching names. For example, 'The Back-Up Plan' is 'Back-Up Plan, The' in the database. However, the LLM in testing has been able to find the right movie. 
- As well, the first run for a new movie makes about 90 API calls, so it can take over a minute. Some MCP clients time out, so run the Inspector with a longer timeout for the first request. 
- To run, this product needs paid Anthropic API credits.
- Scripts that don’t use INT./EXT. headings won’t parse.
- Coverage is limited to what IMSDb has.
- Cache keys are case-sensitive.

## A note on sources
Scripts are copyrighted and come from IMSDb. The tool uses them as source material: scene text is passed to the LLM to write recaps, and users receive the recap, not the script. `movies.db` is gitignored, so no script text is in the repo.
## Future Work
- Allow the user to tell the LLM the timestamp so they don't have to describe the scene.
- Add in new database sources other than IMSDb, so there can be more movies + shows.