movie-rec
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@movie-rec Recommend sci-fi movies for the primary audience and record the recommendation run."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
movie-rec
movie-rec is a movie and television recommendation service implemented as a FastMCP server. It stores audience-specific evidence in SQLite, retrieves candidates from MovieLens ALS factors and TMDB, and records recommendation runs and reactions.
Architecture
The repository contains the following parts:
movie_rec/server.py: FastMCP tools and optional GitHub OAuth authorization.movie_rec/service.py: application-level operations shared by the MCP surface.movie_rec/store.py: SQLite schema, immutable evidence events, derived profiles, recommendation runs, and candidate exposures.movie_rec/retrieval.py: candidate assembly, filtering, ranking, and evidence attachment.movie_rec/als.pyandmovie_rec/movielens.py: MovieLens ALS training artifacts and per-audience fold-in retrieval.movie_rec/tmdb.py,movie_rec/tmdb_recommendations.py, andmovie_rec/discover.py: TMDB title resolution, recommendation expansion, and property-based discovery.scripts/: offline MovieLens training, fixture generation, and evidence-shape inspection.tests/: unit and integration tests with synthetic data.
The service recognizes two neutral audience namespaces, primary and shared. Evidence and recommendation history remain isolated by audience.
Related MCP server: MediaSage
MCP tools
The server exposes these tools:
resolve_title: resolve a movie or television title through TMDB and store its canonical record.add_evidence: append an immutable evidence event.get_evidence_context: return current evidence and a derived profile for an audience.get_candidates: retrieve and filter candidates from the available retrieval lanes.record_recommendations: mark shortlisted and shown titles for a recommendation run.get_recommendation_history: return recent recommendation runs and shown titles.record_reaction: store a reaction linked to an audience and optional run.discover_titles: query TMDB by media type, genre, year, language, keywords, votes, and sorting.
Local setup
Python 3.11 or later and uv are required.
uv sync --all-extras
cp .env.example .envReplace the placeholder values in .env. For local shell use, load the file before starting the service:
set -a
. ./.env
set +a
uv run movie-rec serve --transport stdioThe default database path is under the current user's local data directory. MOVIE_REC_DB_PATH and MOVIE_REC_ARTIFACTS_PATH can select project-local or external runtime storage.
For Streamable HTTP transport, provide the bind port and configure every GitHub OAuth variable listed in .env.example:
uv run movie-rec serve --transport http --host 127.0.0.1 --port 8000The HTTP transport restricts access to the configured GitHub login. Deployment-specific TLS termination, public routing, and secret storage are outside this repository.
External APIs
TMDB access is required for title resolution, metadata, discovery, and TMDB recommendation expansion. Set either TMDB_READ_ACCESS_TOKEN or TMDB_API_KEY in the file selected by MOVIE_REC_TMDB_ENV_FILE.
GitHub OAuth is required only for HTTP transport. Configure a GitHub OAuth application and set MOVIE_REC_PUBLIC_URL, MOVIE_REC_GITHUB_CLIENT_ID, MOVIE_REC_GITHUB_CLIENT_SECRET, MOVIE_REC_OAUTH_SIGNING_KEY, and MOVIE_REC_ALLOWED_GITHUB_LOGIN. Stdio transport does not require GitHub OAuth.
MovieLens training downloads the checksum-pinned MovieLens 32M archive when the configured local archive is absent. Train and map artifacts with:
uv run --extra offline python scripts/train_movielens.py train
uv run --extra offline python scripts/train_movielens.py mapTests
Run the full test suite with:
uv run pytestRegenerate the deterministic ALS fold-in fixture with:
uv run --extra offline python scripts/generate_als_fixture.pyThe generator uses seeded synthetic factors and the implicit library's user-factor recalculation as the independent reference implementation.
Privacy
This public repository contains no personal recommendation evidence, preference history, taste-derived model rows, family context, runtime database, deployment secrets, or private infrastructure configuration. Tests and committed fixtures use synthetic or fictional data. Runtime evidence, databases, generated model artifacts, exports, backups, and secret files are excluded by .gitignore.
License
This project is licensed under the MIT License. See LICENSE.
Available Tools
8 toolsadd_evidenceC
Append one immutable evidence event and return its event ID.
Inputs: kind (required), payload (required), audience (required), title_id, +2 more. Returns: result
discover_titlesA
Find titles by era, genre, rating, language, or keywords.
Use this when similarity search cannot express the user's request. Results can be passed to get_candidates as seed titles. Seen, rated, and not_interested titles are excluded unless allow_repeats applies; not_interested stays excluded. When sorting by vote_average.desc without min_vote_count, the default floor is 1000 votes for movies and 500 for TV. Calls are cheap and paging is normal.
Inputs: media_type (required), page, sort_by, year_to, +9 more. Returns: object
get_candidatesC
Candidate calls are cheap. Read every candidate against the ask and the user's evidence, then requery with different seed_titles, genre filters, or exclude_title_ids if the pool is off target. Any returned title_id can be a seed; use resolve_title for seeds named in the user's words. Use exclude_seed_title_ids to avoid user-positive seeds used in an earlier call. Larger limits pull more seeds and deeper pages; min_vote_average and min_vote_count adjust the score floors. Property arguments add a discover route to the same pool. On general calls, ALS candidates come from the user's overall movie taste vector, not from one seed. Set allow_repeats only to include titles the user has seen or rated; titles marked not_interested remain excluded. Use detail="full" only when the complete metadata and evidence records are needed. Record only final picks.
Inputs: audience (required), limit, detail, context, +14 more. Returns: object
get_evidence_contextC
Return the audience's latest profile and relevant immutable evidence.
Inputs: audience (required), limit, query, title_ids. Returns: object
get_recommendation_historyC
Return recent runs; shortlisted explanations are null by construction.
Inputs: audience (required), limit. Returns: result
record_reactionC
Record a reaction and optionally link it to a recommendation run.
Inputs: audience (required), reaction (required), title_id (required), note, +1 more. Returns: result
record_recommendationsB
Record only final picks. Candidate calls are cheap: read every candidate against the ask and the user's evidence, and requery with different seed_titles, genre filters, or exclude_title_ids when needed. Any returned title_id can be a seed, and resolve_title turns titles from the user's words into seed IDs.
Inputs: picks (required), run_id (required), shortlisted (required). Returns: object
resolve_titleC
Search TMDB, store canonical matches, and return their local title IDs.
Inputs: query (required), year, media_type. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: resolving titles, adding evidence, retrieving context, generating candidates, recording recommendations, fetching history, recording reactions, and discovering titles. No two tools appear to overlap in functionality, and the descriptions provide strong differentiation.
All tool names follow a consistent verb_noun pattern: resolve_title, add_evidence, get_evidence_context, get_candidates, record_recommendations, get_recommendation_history, record_reaction, discover_titles. The pattern is systematic and predictable, making tool selection straightforward.
With 8 tools, the server is well-scoped for its purpose of movie recommendation and user feedback. Each tool addresses a distinct part of the workflow without redundancy, and the count is within the typical well-scoped range (3-15).
The tool set covers the core lifecycle: resolving user inputs, adding evidence, generating candidates, recording recommendations, retrieving history, and capturing reactions. Minor gaps exist (e.g., no explicit delete/update for evidence or reactions), but these are not critical for the main recommendation flow and can be worked around.
Maintenance
Related MCP Connectors
Track the TV and films you watch, and find more like them, by talking to your own AI.
Recommendations, search, catalogue, analytics, and platform admin tools for NeuronSearchLab
Machine-readable entity discovery with provenance, trust and verified source evidence.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceIntegrates with The Movie Database (TMDB) API to provide movie information, search capabilities, and recommendations.11 npm77MIT
- FlicenseNot gradedqualityDmaintenanceTracks movies, books, and TV shows with ratings and preferences, providing intelligent cross-media recommendations. Automatically fetches metadata from OMDB, Google Books, and TMDB to help manage watchlists and analyze viewing patterns.1-
- AlicenseNot gradedqualityDmaintenanceIntegrates with The Movie Database (TMDB) API to provide movie information, search capabilities, and recommendations.11 npmMIT
- FlicenseAqualityDmaintenanceEnables movie/series recommendations via TMDB API and personal tracking of watchlist, watched history, and episodes in local SQLite.8-