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

1. Clone the repository:

   git clone <repository-url>
   cd filmladder-mcp
   

2. Install dependencies using Poetry:

   poetry install
   

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

   poetry run pre-commit install
   

4. 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:

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:

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

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

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

   npm install -g @modelcontextprotocol/inspector
   

2. Run the inspector:

   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:

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]