get_top_rated_malayalam_movies

Retrieve top-rated Malayalam movies from IMDb, returning 5 films starting from a specified index in the list of highest-rated titles.

Instructions

Top 50 Malayalam movies as rated by the IMDb users. Args: start: The starting index (0-based) to retrieve movies from. Returns: JSON object containing 5 top rated Malayalam movies starting from the specified index.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`start`	Yes

Implementation Reference

src/imdb_mcp_server/tools.py:312-327 (handler)

The main handler function decorated with @mcp.tool() which defines the tool schema via signature and docstring, registers it, and implements the logic: fetches data from IMDb API endpoint /india/top-rated-malayalam-movies using make_imdb_request helper, extracts items, applies pagination with paginated_response helper, and returns JSON.

@mcp.tool()
async def get_top_rated_malayalam_movies(start: int, ctx: Context) -> str:
    """Top 50 Malayalam movies as rated by the IMDb users.
    Args:
        start: The starting index (0-based) to retrieve movies from.
    Returns:
        JSON object containing 5 top rated Malayalam movies starting from the specified index.
    """
    top_rated_malayalam_movies_url = f"{BASE_URL}/india/top-rated-malayalam-movies"
    top_rated_malayalam_movies_data = await make_imdb_request(top_rated_malayalam_movies_url, {}, ctx)
    if not top_rated_malayalam_movies_data:
        return "Unable to fetch top rated Malayalam movies data."
    
    # Use paginated response helper with fixed page size
    movies = top_rated_malayalam_movies_data.get("items", [])
    return json.dumps(paginated_response(movies, start, len(movies)), indent=4)

src/imdb_mcp_server/main.py:23-23 (registration)
Calls register_tools(server) to execute the registration of all tools, including get_top_rated_malayalam_movies (defined inside register_tools).
```
register_tools(server)
```

src/imdb_mcp_server/api.py:14-56 (helper)

Core helper function called by the tool handler to make authenticated, cached HTTP requests to the IMDb API.

async def make_imdb_request(url: str, querystring: dict[str, Any], ctx: Optional[Context] = None) -> Optional[Dict[str, Any]]:
    """Make a request to the IMDb API with proper error handling and caching."""
    
    # Check if it's time to clean the cache
    cache_manager.cleanup_if_needed()
    
    # Create a cache key from the URL and querystring
    cache_key = f"{url}_{str(querystring)}"
    
    # Try to get from cache first
    cached_data = cache_manager.cache.get(cache_key)
    if cached_data:
        return cached_data
    
    # Get API key from session config or fallback to environment variable
    api_key = None
    if ctx and hasattr(ctx, 'session_config') and ctx.session_config:
        api_key = ctx.session_config.rapidApiKeyImdb
    
    if not api_key:
        api_key = os.getenv("RAPID_API_KEY_IMDB")
    
    # Not in cache, make the request
    headers = {
        "x-rapidapi-key": api_key,
        "x-rapidapi-host": "imdb236.p.rapidapi.com",
    }
    
    if not api_key:
        raise ValueError("API key not found. Please set the RAPID_API_KEY_IMDB environment variable or provide rapidApiKeyImdb in the request.")
    
    try:
        response = requests.get(url, headers=headers, params=querystring, timeout=30.0)
        response.raise_for_status()
        data = response.json()
        
        # Cache the response
        cache_manager.cache.set(cache_key, data)
            
        return data
    except Exception as e:
        raise ValueError(f"Unable to fetch data from IMDb. Please try again later. Error: {e}")

src/imdb_mcp_server/api.py:58-77 (helper)

Helper function used by the tool to paginate the list of movies with fixed page size 5.

def paginated_response(items, start, total_count=None):
    """Format a paginated response with a fixed page size of 5."""
    if total_count is None:
        total_count = len(items)
    
    # Validate starting index
    start = max(0, min(total_count - 1 if total_count > 0 else 0, start))
    
    # Fixed page size of 5
    page_size = 5
    end = min(start + page_size, total_count)
    
    return {
        "items": items[start:end],
        "start": start,
        "count": end - start,
        "totalCount": total_count,
        "hasMore": end < total_count,
        "nextStart": end if end < total_count else None
    }

src/imdb_mcp_server/api.py:11-11 (helper)
BASE_URL constant used to construct the API endpoint URL in the handler.
```
BASE_URL = "https://imdb236.p.rapidapi.com/api/imdb"
```

imdb-mcp-server