Filmladder MCP Server

A Model Context Protocol (MCP) server that provides movie listings and recommendations for Amsterdam cinemas by scraping filmladder.nl.

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

Clone the repository:

git clone <repository-url>
cd filmladder-mcp

Install dependencies using Poetry:
```
poetry install
```
Install pre-commit hooks (optional but recommended):
```
poetry run pre-commit install
```
Copy .env.example to .env and adjust configuration if needed:
```
cp .env.example .env
```

Usage

Running the MCP Server

The server uses stdio transport and can be run directly:

poetry run python -m src.server

Connecting to Cursor IDE

To use this MCP server in Cursor:

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
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:
```
{
  "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.
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:

{
  "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:

{
  "movie_title": "Nuremberg"
}

`list_cinema_movies`

List all movies playing at a specific cinema.

Parameters:

cinema_name (required): Name of the cinema

Example:

{
  "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:

{
  "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:

poetry run pytest tests/

Run with verbose output:

poetry run pytest tests/ -v

Quick Server Test

Test that the server initializes correctly:

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:

Install MCP Inspector (if not already installed):
```
npm install -g @modelcontextprotocol/inspector
```
Run the inspector:
```
npx @modelcontextprotocol/inspector
```
Configure the inspector to use your server:
- Server command: poetry run python -m src.server
- Transport: stdio
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:

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:

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

Run tests:

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]

Filmladder MCP Server

A Model Context Protocol (MCP) server that provides movie listings and recommendations for Amsterdam cinemas by scraping filmladder.nl.

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

Clone the repository:

git clone <repository-url>
cd filmladder-mcp

Install dependencies using Poetry:
```
poetry install
```
Install pre-commit hooks (optional but recommended):
```
poetry run pre-commit install
```
Copy .env.example to .env and adjust configuration if needed:
```
cp .env.example .env
```

Usage

Running the MCP Server

The server uses stdio transport and can be run directly:

poetry run python -m src.server

Connecting to Cursor IDE

To use this MCP server in Cursor:

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
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:
```
{
  "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.
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:

{
  "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:

{
  "movie_title": "Nuremberg"
}

`list_cinema_movies`

List all movies playing at a specific cinema.

Parameters:

cinema_name (required): Name of the cinema

Example:

{
  "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:

{
  "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:

poetry run pytest tests/

Run with verbose output:

poetry run pytest tests/ -v

Quick Server Test

Test that the server initializes correctly:

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:

Install MCP Inspector (if not already installed):
```
npm install -g @modelcontextprotocol/inspector
```
Run the inspector:
```
npx @modelcontextprotocol/inspector
```
Configure the inspector to use your server:
- Server command: poetry run python -m src.server
- Transport: stdio
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:

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:

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

Run tests:

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]