# Filmladder MCP Server

A Model Context Protocol (MCP) server that provides movie listings and recommendations for Amsterdam cinemas by scraping [filmladder.nl](https://www.filmladder.nl/amsterdam/bioscopen).

## Features

- **List Movies**: Get all movies playing in Amsterdam cinemas, optionally filtered by date
- **Get Showtimes**: Find all showtimes for a specific movie (with fuzzy title matching)
- **Cinema Movies**: List all movies playing at a specific cinema
- **Recommendations**: Get movie recommendations based on rating, preferred showtimes, cinemas, and date

## Requirements

- Python 3.11 or higher
- Poetry for dependency management

## Installation

1. Clone the repository:

   ```bash
   git clone <repository-url>
   cd filmladder-mcp
   ```

2. Install dependencies using Poetry:

   ```bash
   poetry install
   ```

3. Install pre-commit hooks (optional but recommended):

   ```bash
   poetry run pre-commit install
   ```

4. Copy `.env.example` to `.env` and adjust configuration if needed:
   ```bash
   cp .env.example .env
   ```

## Usage

### Running the MCP Server

The server uses stdio transport and can be run directly:

```bash
poetry run python -m src.server
```

### Connecting to Cursor IDE

To use this MCP server in Cursor:

1. **Project-specific configuration** (recommended):

   - The project includes a `.cursor/mcp.json` file with the server configuration
   - Cursor should automatically detect it when you open this project

2. **Manual configuration**:

   - Open Cursor Settings (gear icon)
   - Go to **Tools & Integrations** → **MCP Tools**
   - Click **Add Custom MCP** or edit `mcp.json`
   - Add the following configuration:

   ```json
   {
     "mcpServers": {
       "filmladder-mcp": {
         "command": "poetry",
         "args": ["run", "python", "-m", "src.server"],
         "cwd": "/path/to/filmladder-mcp"
       }
     }
   }
   ```

   **Important**: Replace `/path/to/filmladder-mcp` with the actual path to this project directory.

3. **Verify connection**:
   - After saving, Cursor should show "filmladder-mcp" in the MCP Tools section
   - You can test it by asking Cursor: "What movies are playing in Amsterdam today?"

### Using the MCP Tools in Cursor

Once connected, you can use the tools in Cursor's chat:

- **List movies**: "What movies are playing in Amsterdam?"
- **Get showtimes**: "When is Nuremberg playing?"
- **Cinema movies**: "What movies are playing at Pathé Tuschinski?"
- **Recommendations**: "Recommend me a movie with rating above 7.0 for tonight"

### MCP Tools

The server exposes the following tools:

#### `list_movies`

List all movies playing in Amsterdam cinemas.

**Parameters:**

- `date` (optional): Date filter in YYYY-MM-DD format

**Example:**

```json
{
  "date": "2025-01-15"
}
```

#### `get_showtimes`

Get all showtimes for a specific movie (fuzzy matching on title).

**Parameters:**

- `movie_title` (required): Title of the movie

**Example:**

```json
{
  "movie_title": "Nuremberg"
}
```

#### `list_cinema_movies`

List all movies playing at a specific cinema.

**Parameters:**

- `cinema_name` (required): Name of the cinema

**Example:**

```json
{
  "cinema_name": "Pathé Tuschinski"
}
```

#### `recommend_movies`

Recommend movies based on various criteria.

**Parameters:**

- `min_rating` (optional): Minimum rating threshold (default: 0.0)
- `preferred_times` (optional): Array of preferred showtimes in HH:MM format
- `preferred_cinemas` (optional): Array of preferred cinema names
- `date` (optional): Target date for recommendations in YYYY-MM-DD format

**Example:**

```json
{
  "min_rating": 7.0,
  "preferred_times": ["20:00", "21:00"],
  "preferred_cinemas": ["Pathé Tuschinski", "EYE"],
  "date": "2025-01-15"
}
```

## Testing

### Unit Tests

Run the test suite:

```bash
poetry run pytest tests/
```

Run with verbose output:

```bash
poetry run pytest tests/ -v
```

### Quick Server Test

Test that the server initializes correctly:

```bash
poetry run python test_server.py
```

This will verify that:

- The server can be imported
- Tools are registered correctly
- Basic functionality works

### Testing with MCP Inspector

The recommended way to test the full MCP server is using the [MCP Inspector](https://www.stainless.com/mcp/how-to-test-mcp-servers):

1. Install MCP Inspector (if not already installed):

   ```bash
   npm install -g @modelcontextprotocol/inspector
   ```

2. Run the inspector:

   ```bash
   npx @modelcontextprotocol/inspector
   ```

3. Configure the inspector to use your server:

   - Server command: `poetry run python -m src.server`
   - Transport: stdio

4. The inspector will provide an interactive interface to test all tools.

### Manual Testing

You can also test the server manually by running it and sending JSON-RPC messages via stdin:

```bash
poetry run python -m src.server
```

Then send initialization and tool call requests in JSON-RPC format.

## Development

### Code Quality

This project uses:

- **ruff** for linting and import sorting
- **black** for code formatting
- **mypy** for type checking
- **pre-commit** hooks to ensure code quality
- **pytest** for testing

Run linting and formatting:

```bash
poetry run ruff check src/
poetry run black src/
poetry run mypy src/
```

Run tests:

```bash
poetry run pytest tests/
```

### Project Structure

```
filmladder-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py          # MCP server entry point
│   ├── scraper.py         # Web scraping logic
│   ├── models.py          # Pydantic data models
│   ├── config.py          # Pydantic-settings configuration
│   └── recommender.py     # Recommendation logic
├── pyproject.toml         # Poetry dependencies and project config
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── .cursorrules           # Cursor IDE rules
├── README.md             # This file
└── .env.example          # Example environment variables
```

### Type Annotations

All code must use type annotations. The project follows Python 3.11+ type hinting conventions:

- Use `list[T]` instead of `List[T]`
- Use `str | None` instead of `Optional[str]`
- All functions, methods, and variables must be typed

### Pydantic Models

All data structures use Pydantic BaseModel for validation and serialization. Configuration uses `pydantic-settings` for environment variable support.

## Error Handling

The server handles:

- Network errors (HTTP timeouts, connection failures)
- Parsing errors (HTML structure changes)
- Invalid input parameters

Errors are raised as exceptions that the MCP framework will handle appropriately.

## License

[Add your license here]

## Contributing

[Add contributing guidelines here]