Cineverse Mcp Discovery

A high-precision, zero-hallucination media discovery platform and complete directory of Netflix movies and TV series. Built with a lightweight Python backend, custom Model Context Protocol (MCP) server, RAG engine guardrails, and an editorial Whats-New frontend interface.

---

🌟 Key Features

1. 🎬 Full Netflix Library Directory (7,644 Titles)

• Complete, searchable directory of 7,644 clean Netflix titles (5,268 Movies & 2,376 TV Shows).
• Purged all obscure date titles, numbers, and corrupt entries.
• Full catalog pagination across 153 pages (50 items per page).

2. 🤖 100% ML & Semantic NLP Categorization

• Every single movie and series in the dataset is classified into 12 Canonical High-Precision Genres and 8 Expressive Emotional Moods.
• Zero Uncategorized Guarantee: 100% coverage across all 7,644 titles.

🏷️ Canonical Genres:

• Dramas (2,940 titles)
• Action & Adventure (2,506 titles)
• Comedies (2,346 titles)
• Children & Family (2,159 titles)
• Romantic Movies (1,388 titles)
• Documentaries (1,298 titles)
• Crime Movies & Shows (1,126 titles)
• Thrillers & Mysteries (720 titles)
• Horror Movies (676 titles)
• Sci-Fi & Fantasy (569 titles)
• Reality TV (275 titles)
• Anime Series (249 titles)

🎭 Expressive Emotional Moods:

• 💧 Deeply Emotional & Touching (2,924 titles)
• ⚡ Adrenaline & High-Octane (2,305 titles)
• 🌌 Dark, Gritty & Intense (2,131 titles)
• ❤️ Heartwarming & Feel-Good (1,797 titles)
• 🎨 Inspiring & Educational (1,089 titles)
• 🤣 Witty & Hilarious (979 titles)
• 👻 Spooky & Chilling (486 titles)
• 🧠 Mind-Bending & Thought-Provoking (323 titles)

3. 📰 Whats-New Editorial Layout (Zero Posters)

• Clean, poster-less directory table matching editorial Whats-New layouts.
• Columns: Title & Release Year (📅 2022), Type Badges (MOVIE / TV SERIES), Duration (⏱️ 148 min / 4 Seasons), IMDb (⭐ 8.7/10) & Rotten Tomatoes (🍅 94%), Genres, Moods, Plot Synopsis, Director & Cast, and direct ▶️ Watch on Netflix streaming launch buttons.

4. 🛡️ Agentic RAG & Anti-Hallucination Guardrails

• Underneath queries run through a Model Context Protocol (MCP) tool server (mcp_server.py) and RAG Engine (rag_engine.py).
• Every recommendation is verified against valid dataset IDs before returning, preventing any hallcuinated titles or false matches.

5. 🔴 Personal Netflix Account Sync

• Paste viewing history or upload official ViewingActivity.csv files to compute personal affinity match scores across the entire Netflix catalog.

6. 🥂 Dual Mood Harmonizer (Watch Party)

• Combine two distinct mood vibes (e.g. Sci-Fi Thriller + Cozy Comedy) to find overlapping recommendations suitable for group viewing.

---

📁 Project Structure

cineverse-mcp-discovery/
├── backend/
│   ├── main.py                     # Primary HTTP Server & REST API router
│   ├── data_engine.py              # In-memory dataset engine with pagination & search
│   ├── classify_catalog.py         # ML & NLP semantic catalog classifier
│   ├── force_clean_db.py           # Strict dataset title purger
│   ├── agent_router.py             # Agent query routing logic
│   ├── rag_engine.py               # RAG Engine with guardrail validation
│   ├── mcp_server.py               # Model Context Protocol (MCP) server
│   └── data/
│       └── media_dataset.json      # 7,644 clean Netflix items database
├── frontend/
│   ├── index.html                  # Main application structure
│   ├── style.css                   # Editorial dark design system
│   └── app.js                      # Client-side state & pagination handler
└── README.md                       # Project documentation

---

🚀 Getting Started

Prerequisites

• Python 3.8 or higher installed on your system.

Running the Server

1. Start Backend Server:

   python backend/main.py
   

2. Access Web Application: Open your browser and navigate to:

   http://127.0.0.1:8000/
   

---

🔌 API Endpoints

• GET /api/movies?page=1&page_size=50: Fetch paginated catalog.
• POST /api/chat: Send search queries, genre filters (genre: Action), mood filters (mood: Mind-Bending), or content type filters (content_type: Movie).
• POST /api/netflix/sync: Sync viewing history text or CSV to get personalized affinity recommendations.