Indian Movies MCP Agent 🎬

A Model Context Protocol (MCP) agent that provides Indian movie recommendations directly within Claude Desktop. Get personalized Bollywood, Tollywood, and regional cinema suggestions with intelligent filtering by genre, language, rating, and release year.

🎯 What This Does

This MCP agent adds three powerful tools to your Claude Desktop:

• Smart Recommendations: Filter movies by genre, language, rating, or year

• Movie Search: Find detailed information about specific films

• Random Discovery: Get surprise recommendations from curated Indian cinema

📋 Prerequisites

Before you begin, ensure you have:

• macOS (this guide is Mac-specific)

• Node.js version 18 or higher (Download here)

• Claude Desktop app (Download here)

• Terminal access

• Text editor (VS Code, TextEdit, etc.)

Check Your Node.js Version

If you see v18.0.0 or higher, you're good to go!

🚀 Quick Start (5 Minutes)

Step 1: Clone and Setup

If testing, you should see: Indian Movies MCP server running on stdio Press Ctrl+C to stop the test.

Step 2: Get Your Project Path

Copy this path! You'll need it in the next step. Example output: /Users/john/Documents/indian-movies-mcp

Step 3: Configure Claude Desktop

Option A: Create Config File via Terminal (Recommended)

Important: Replace REPLACE_WITH_YOUR_PATH with the path you copied from Step 2.

Option B: Create Config File Manually

1. Open Finder

2. Press Cmd + Shift + G

3. Go to: ~/Library/Application Support/Claude/

4. Create a new file named: claude_desktop_config.json

5. Copy and paste this content, replacing the path:

Step 4: Connect to Claude Desktop

1. Completely quit Claude Desktop (don't just close the window)

2. Restart Claude Desktop

3. Wait 10-15 seconds for the connection to establish

Step 5: Test It!

In Claude Desktop, try asking:

• "Recommend some Hindi comedy movies"

• "Find action movies with rating above 8"

• "Search for the movie Dangal"

• "Give me a random Indian movie recommendation"

📖 Detailed Installation Guide

For Complete Beginners

What is Node.js?

Node.js lets you run JavaScript on your computer (outside of a web browser). We need it to run our movie recommendation server.

Installing Node.js

1. Go to nodejs.org

2. Download the LTS version (Long Term Support)

3. Run the installer

4. Restart your Terminal after installation

What is npm?

npm (Node Package Manager) comes with Node.js and helps install code libraries. Think of it like an app store for code.

Understanding the File Structure

🛠️ Manual Setup (Alternative Method)

If you prefer to set up everything from scratch:

1. Create Project Directory

2. Create package.json

3. Install Dependencies

4. Create the Server File

Copy the index.js content from this repository into a new file in your project directory.

5. Continue with Step 2 from Quick Start

🎭 Available Movie Tools

1. Get Movie Recommendations

Usage: "Recommend movies with specific criteria"

Parameters:

• genre: Comedy, Drama, Action, Thriller, etc.

• language: Hindi, Telugu, Tamil, etc.

• min_rating: Minimum rating (0-10)

• year_after: Movies released after this year

Examples:

• "Show me Hindi comedies"

• "Find action movies with rating above 8"

• "Recommend movies from 2015 onwards"

2. Search Movie

Usage: "Search for a specific movie"

Parameters:

• title: Movie title to search for

Examples:

• "Tell me about 3 Idiots"

• "Search for Baahubali"

3. Random Movie

Usage: "Get a surprise recommendation"

Examples:

• "Suggest a random Indian movie"

• "Give me a random recommendation"

🎬 Current Movie Database

The agent includes these popular Indian films:

Hindi Cinema:

• 3 Idiots (2009) - Comedy/Drama

• Dangal (2016) - Biography/Drama/Sport

• Taare Zameen Par (2007) - Drama/Family

• Zindagi Na Milegi Dobara (2011) - Adventure/Comedy

• And more...

Regional Cinema:

• Baahubali 2 (2017) - Telugu Action/Drama

• Various Tamil and other regional films

📊 Enhanced Logging for MCP Protocol Learning

This version includes comprehensive logging to help you understand the Model Context Protocol (MCP) communication between Claude and the MCP agent. Perfect for learning how MCP works under the hood!

🔍 What Gets Logged

The enhanced logging system captures:

• Protocol Messages: All requests and responses between Claude and the MCP server

• Tool Calls: Detailed information about which tools are called and with what parameters

• Data Filtering: Step-by-step filtering process for movie recommendations

• Error Handling: Comprehensive error logging with stack traces

• Server Lifecycle: Connection, disconnection, and heartbeat messages

📁 Log File Location

Logs are written to: mcp-server.log in your project directory

🚀 Viewing Logs in Real-Time

Option 1: Terminal Logs (Live Output)

Start the server and watch logs in your terminal:

You'll see live logs like:

Option 2: Follow Log File (Recommended for Learning)

In a separate terminal window, watch the detailed log file:

Option 3: View Complete Log History

🎯 Understanding MCP Protocol Flow

When you interact with Claude, watch the logs to see this flow:

1. Initialization: Claude connects to your MCP server

2. Tool Discovery: Claude asks "what tools do you have?"

3. Tool Execution: Claude calls specific tools with parameters

4. Data Processing: Your server processes and returns results

Example Log Sequence

When you ask Claude "Recommend Hindi comedies", you'll see:

🔬 Learning MCP Protocol Concepts

Use the logs to understand these MCP concepts:

1. Tool Discovery

Watch for LIST TOOLS REQUEST to see how Claude discovers available tools:

2. Tool Schemas

See how input validation works by examining tool call parameters:

3. Error Handling

Understand MCP error handling by triggering errors:

4. Data Flow

Track data transformation through the logging:

🛠️ Debugging with Logs

Finding Connection Issues

Analyzing Tool Performance

Understanding Request Flow

📚 Log Levels Explained

• INFO: Normal operations (tool calls, data processing)

• WARN: Potential issues that don't break functionality

• ERROR: Actual errors that need attention

• DEBUG: Verbose information for detailed analysis

🎓 Learning Exercises

Try these exercises to understand MCP better:

Exercise 1: Basic Protocol Flow

1. Start the server and watch logs

2. Ask Claude: "What movie tools do you have?"

3. Observe the tool discovery protocol in the logs

Exercise 2: Parameter Validation

1. Ask Claude: "Recommend movies" (no parameters)

2. Ask Claude: "Recommend Hindi comedies" (with parameters)

3. Compare how parameters are handled in the logs

Exercise 3: Error Handling

1. Temporarily break the code (add a syntax error)

2. Watch how errors propagate through the MCP protocol

3. Fix the code and observe recovery

Exercise 4: Data Filtering

1. Ask for complex filters: "Hindi action movies from 2015 with rating above 8"

2. Watch the step-by-step filtering process in the logs

3. Understand how data flows through the system

📁 Log File Management

The log file can grow large over time. Manage it with:

🎯 Pro Tips for MCP Learning

1. Use Two Terminals: One for server logs, one for file logs

2. Timestamps: Correlate Claude requests with log timestamps

3. JSON Formatting: Use jq to format JSON in logs: cat mcp-server.log | grep "Tool arguments" | jq

4. Pattern Matching: Learn to spot patterns in MCP communication

5. Error Simulation: Intentionally trigger errors to understand error handling

🔧 Troubleshooting

MCP Server Not Connecting

Problem: Claude Desktop doesn't recognize the MCP server

Solutions:

1. Check the config file path:

   ls ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Verify the server path is absolute:

   # Your path should start with / like this: /Users/john/Documents/indian-movies-mcp/index.js

3. Test your server manually:

   cd /path/to/your/indian-movies-mcp npm start

4. Completely restart Claude Desktop:

   • Quit Claude Desktop (Cmd+Q)

   • Wait 5 seconds

   • Restart Claude Desktop

Node.js or npm Issues

Problem: command not found: node or command not found: npm

Solution:

1. Install Node.js from nodejs.org

2. Restart your Terminal

3. Verify installation: node --version

Permission Issues

Problem: Permission denied errors

Solution:

Config File Issues

Problem: JSON syntax errors

Solution:

1. Validate your JSON at jsonlint.com

2. Common issues:

   • Missing commas

   • Incorrect quotes (use " not ')

   • Missing closing brackets

Logging Issues

Problem: No logs appearing in mcp-server.log

Solution:

1. Check if the server is running:

   ps aux | grep "node.*index.js"

2. Verify logging.js is properly imported:

   grep "from './logging.js'" index.js

3. Check file permissions:

   ls -la mcp-server.log # If file doesn't exist, it will be created automatically

4. Test logging manually:

   node -e "import('./logging.js').then(({log}) => log('Test message'))"

Problem: Logs are too verbose or cluttering terminal

Solution:

1. Use only file logging by redirecting stderr:

   npm start 2>/dev/null

2. Filter logs by level:

   grep "\[ERROR\]" mcp-server.log grep "\[WARN\]" mcp-server.log grep "\[INFO\]" mcp-server.log

3. Reduce log verbosity by commenting out detailed logs in index.js

Problem: Log file growing too large

Solution:

1. Set up log rotation:

   # Create logs directory mkdir -p logs # Rotate current log mv mcp-server.log logs/mcp-server-backup-$(date +%Y%m%d-%H%M%S).log

2. Implement size-based rotation:

   # Check file size and rotate if > 10MB if [ $(wc -c < mcp-server.log) -gt 10485760 ]; then mv mcp-server.log logs/mcp-server-$(date +%Y%m%d-%H%M%S).log fi

Problem: Cannot correlate Claude actions with logs

Solution:

1. Use precise timestamps:

   # Note the time when you make a request in Claude date # Then check logs around that time grep "2024-07-20T10:30" mcp-server.log

2. Add request markers in Claude:

   • Ask Claude: "Search for test-marker-movie"

   • Look for this unique term in logs to identify your session

3. Use unique test queries:

   # Instead of "recommend movies", use: # "recommend movies with unique-identifier-12345" # Then search logs for "unique-identifier-12345"

🔄 Updating the Movie Database

Want to add more movies? Edit the indianMovies array in index.js:

After adding movies:

1. Save the file

2. Restart Claude Desktop

3. Test with new movie searches

🤝 Contributing

Want to improve this MCP agent?

1. Fork this repository

2. Create a feature branch: git checkout -b feature-name

3. Add more movies, improve filtering, or add new tools

4. Commit your changes: git commit -m "Add feature"

5. Push to your branch: git push origin feature-name

6. Create a Pull Request

Ideas for Contributions

• Add more regional Indian films

• Include movie posters or trailers

• Add director/actor filtering

• Include streaming platform availability

• Add movie reviews or ratings from multiple sources

📝 License

MIT License - feel free to use and modify!

🆘 Getting Help

If you run into issues:

1. Check the troubleshooting section above

2. Create an issue on this GitHub repository

3. Include:

   • Your macOS version

   • Node.js version (node --version)

   • Error messages

   • Your config file (remove personal paths)

🎉 What's Next?

Once you have this working, you can:

• Build other MCP agents for different domains

• Expand this agent with more Indian cinema data

• Create agents for other movie industries

• Add real-time data from movie APIs

Happy movie watching! 🍿