get_top_box_office_us
Retrieve current US box office rankings for movies from IMDb data. Get paginated results showing top-performing films with their positions and performance metrics.
Instructions
Get the top box office data for the US from IMDb with pagination. Args: start: The starting index (0-based) to retrieve movies from. Returns: JSON object containing 5 top box office movies starting from the specified index.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes |
Input Schema (JSON Schema)
{
"properties": {
"start": {
"title": "Start",
"type": "integer"
}
},
"required": [
"start"
],
"type": "object"
}
Implementation Reference
- src/imdb_mcp_server/tools.py:216-228 (handler)The core handler function for the 'get_top_box_office_us' tool. It is decorated with @mcp.tool() for registration and fetches top box office US movies from the IMDb API endpoint, handles errors, and returns a paginated JSON response using helper functions.@mcp.tool() async def get_top_box_office_us(start: int, ctx: Context) -> str: """Get the top box office data for the US from IMDb with pagination. Args: start: The starting index (0-based) to retrieve movies from. Returns: JSON object containing 5 top box office movies starting from the specified index. """ box_office_us_url = f"{BASE_URL}/top-box-office" box_office_us_data = await make_imdb_request(box_office_us_url, {}, ctx) if not box_office_us_data: return "Unable to fetch box office data for the US." return json.dumps(paginated_response(box_office_us_data, start, len(box_office_us_data)), indent=4)
- src/imdb_mcp_server/api.py:58-77 (helper)Shared helper function used by the tool to format the API response into a paginated structure with a fixed page size of 5 items.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:14-55 (helper)Shared helper function used by the tool to perform HTTP requests to the IMDb RapidAPI with caching, API key handling from context or env, and error management.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/main.py:22-23 (registration)Call to register_tools(server) which defines and registers all tools including get_top_box_office_us via nested decorators.# Register all tools with the server register_tools(server)
- src/imdb_mcp_server/api.py:11-11 (helper)Constant BASE_URL used in the tool to construct the API endpoint URL.BASE_URL = "https://imdb236.p.rapidapi.com/api/imdb"