# IMDB MCP

Model Context Protocol (MCP) server for movie data with semantic vector search using embeddings and PostgreSQL with pgvector.

## Overview

Provides semantic search, similarity matching, and traditional filtering across IMDB movie data:
- **Semantic Search**: Find movies by meaning using embeddings
- **Similarity Search**: Get similar movies based on descriptions
- **Hybrid Search**: Combine semantic and keyword matching
- **Traditional Filters**: Genre, country, title, ratings

## Setup

### Prerequisites

- Python 3.12+
- PostgreSQL 12+ with pgvector extension
- GCP Secret Manager (for credentials)
- ~400MB for embedding model download

### Installation

```bash
uv sync
```

### Environment

Set required environment variable:

```bash
export GCP_PROJECT_ID=your-gcp-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

GCP Secret Manager must contain:
- `db-host`: PostgreSQL host
- `db-port`: PostgreSQL port
- `db-name`: Database name
- `db-user`: Database user
- `db-password`: Database password
- `db-admin-password`: Admin password

## Usage - Database

Run the ETL pipeline to set up and seed the database:

```bash
python extract.py    # Extract from source
python transform.py  # Generate embeddings
python load.py       # Load into PostgreSQL with pgvector
```

Place the CSV file in the `data/` folder: `data/imdb_movies.csv`

## Usage - MCP

Start the MCP server:

```bash
python -m mcp_server
```

Server runs on port 3000 with tools for:
- `semantic_search`: Search by description meaning
- `similarity_search`: Find similar movies
- `hybrid_search`: Combined semantic and keyword search
- `get_movie_by_id`: Retrieve movie details
- `search_movies`: Title-based search
- Additional filtering and stats tools

## Tests

Run manually via GitHub Actions or locally:

```bash
uv run pytest tests/ -v --cov=. --cov-report=term-missing
```

## Future
My next step for this project would be to use a GCP solution for the postgres database and connect the MCP to this rather than a local pgsql database.

## Deployment

Currently this project is meant for local use only, but I have added workflows for deployment to GCP, with small modification to the mcp server to read from bigquery or cloud SQL instead of a local postgres database.

## Contributing

1. Write tests for new features
2. Run test suite locally
3. Push to feature branch
4. Manual test trigger in Actions
5. Deploy on approval