Component Implementation: Prompts

As a reminder: prompts are a distinct MCP primitive from tools and resources. While a tool executes code and returns data, a prompt generates a filled-in message template that the LLM itself will respond to. Think of it as the server pre-loading both the data and the question so the LLM only needs to provide the analysis.

Imports and Registration Shell

We use the following imports in prompts.py:

# components/prompts.py
from sqlalchemy.orm import Session

from fastmcp import FastMCP
from fastmcp.dependencies import Depends
from fastmcp.exceptions import PromptError

from database import Movie
from database import ViewSummary
from database import get_db_session


def register_prompts(mcp: FastMCP):
    ...

The imports are leaner than tools.py because prompts don't need to send HTTP requests or handle session state — they are pure data-fetching and text-assembly. PromptError takes the place of ToolError and signals failures in a way that FastMCP converts into a correctly-typed MCP error response for prompts.

Prompt: `analyze_movie_performance`

This prompt fetches the full weekly viewing history for a given movie from the database, formats it as a chronological series of rank-and-hours bullets, and returns a ready-made question string asking the LLM to analyse the trends. The LLM never touches the database — the server does all the data retrieval and hands the LLM a structured text it can reason over directly.

    @mcp.prompt()
    def analyze_movie_performance(
        movie_id: str,
        db: Session = Depends(get_db_session),
    ) -> str:
        """Analyze viewing performance trends for a movie."""

        # MCP requires prompt arguments to be strings, so we parse here
        try:
            movie_id_int = int(movie_id)
        except ValueError:
            raise PromptError(f"Invalid movie_id: '{movie_id}' is not a valid integer")

        results = (
            db.query(Movie.title, ViewSummary)
            .join(ViewSummary, ViewSummary.movie_id == Movie.id)
            .filter(Movie.id == movie_id_int)
            .filter(ViewSummary.duration == "WEEKLY")
            .