youtube-gemini-mcp: Instructions file for Claude Code

Claude Code Instructions for YouTube Gemini MCP

This document provides specific instructions for Claude Code when working with the YouTube Gemini MCP project.

Project Overview

Project: YouTube Gemini MCP Server
Type: Model Context Protocol (MCP) server for conversational video analysis
Architecture: Session-based conversational video analysis using Gemini 2.5 Pro
Primary Purpose: Enable multi-turn conversations about YouTube videos and local video files

Key Architecture Components

Hybrid Video Processing

• YouTube Videos: Direct URL processing via Gemini API (no download required)
• Local Videos: Upload via Google Files API with 48-hour retention limit
• Unified Interface: Single MCP server handles both video sources seamlessly

Core Components

src/youtube_gemini_mcp/
├── server.py              # FastMCP server with MCP tools
├── session_manager.py     # Thread-safe session management
├── gemini_client.py       # Google Gemini API integration
├── youtube_validator.py   # YouTube URL validation and metadata
├── files_uploader.py      # Google Files API wrapper

Session Management

• Thread-safe: Uses RLock for concurrent access
• Persistent: Sessions stored to disk with conversation history
• Timeout-based: Automatic cleanup of expired sessions
• Memory-efficient: O(1) session lookup with dictionary storage

Development Patterns

Error Handling

All MCP tools must follow this exact pattern:

@mcp.tool()
def example_tool(param: str) -> Dict[str, Any]:
    try:
        # Implementation
        return {"success": True, "result": "data"}
    except Exception as e:
        logger.error(f"Tool failed: {e}")
        return {
            "success": False,
            "error": str(e),
            "error_type": "tool_execution_error"
        }

Logging Configuration

Must use exact format from openai-image-mcp:

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(pathname)s:%(lineno)d - %(message)s',
    handlers=[logging.StreamHandler(sys.stderr)],
    force=True
)