Summary of Challenges Making This MCP Server with YouTube

Based on the codebase and documentation, here are the key challenges encountered:

Find it on GitHub.com

1. YouTube API Authentication & Configuration

• Challenge: Securing YouTube API keys without committing them to Git
• Solution: Created .env.example as a template with placeholder values
• Status: .env_yt is properly git-ignored
• Files: .env.example, .env_yt, .gitignore

2. CORS (Cross-Origin Resource Sharing) Issues

• Challenge: Browser blocking requests due to missing CORS headers
• Error: HTTP POST http://192.168.1.125:9091/mcp failed: Failed to fetch (check CORS?)
• Solution: Added CORS middleware to FastMCP/FastAPI app
• Configuration:cors_middleware = [ Middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["GET", "POST", "OPTIONS", "DELETE"], allow_headers=["Content-Type", "Authorization", "mcp-protocol-version", ...], ) ]

3. Llama.cpp Envelope Format Compatibility

• Challenge: Llama.cpp sends MCP requests in an envelope format that FastMCP doesn’t understand natively
• Issue: Missing body.value field in Llama.cpp envelope format
• Solution: Created EnvelopeMiddleware to extract the JSON-RPC request from the envelope
• Status: Middleware needs to be properly applied to the FastMCP app

4. HTTP Transport Header Compatibility

• Challenge: FastMCP’s streamable HTTP transport has strict Accept header requirements
• Issue: Server rejected requests with application/json, text/event-stream headers
• Solution: Patched _check_accept_headers function to accept both content types
• Code:# Patch to accept json, event-stream, or both streamable_http_module.StreamableHTTPServerTransport._check_accept_headers = patched_check_accept_headers

5. YouTube API Integration

• Challenge: YouTube Data API v3 requires proper authentication
• Implementation:
  • Uses google-api-python-client library
  • Extracts video IDs from various URL formats
  • Fetches video details, transcripts, and similar videos
• Key Methods:
  • get_video_details()
  • get_transcript()
  • get_similar_videos()
  • search_videos()

6. Server Deployment & Restart

• Challenge: Code changes need to be deployed and server restarted
• Solution: Documentation for SSH deployment and service restart
• Commands: kill <PID> or sudo systemctl restart mcp-server

7. Request Timeouts

• Challenge: Requests may hang indefinitely
• Solution: Added --max-time 30 to curl commands
• Importance: Prevents hanging requests to external services

8. Multiple Transport Methods

• Challenge: Supporting TCP, STDIO, and SSE transports
• Solution: Implemented run_all_transports() function that spawns multiple processes
• Transport Types:
  • streamable-http (default for HTTP requests)
  • sse (Server-Sent Events)
  • stdio (Standard Input/Output)

9. Environment Configuration

• Challenge: Managing different environments (local, server)
• Environment Variables:
  • YOUTUBE_API_KEY (required)
  • MCP_PORT (default: 9090)
  • MCP_TOKEN_KEY (auto-generated)
  • LOG_LEVEL (default: INFO)

Would you like me to work on any specific challenge, such as:

1. Testing the CORS configuration
2. Verifying the envelope middleware works
3. Setting up proper deployment documentation
   Total iterations: 8

1. High-Level Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│     MCP Server Layer (HTTP, SSE, STDIO transports)          │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  HTTP        │  │   SSE        │  │  STDIO       │      │
│  │  (Uvicorn)   │  │   (FastMCP)  │  │  (FastMCP)   │      │
│  └──────┬───────┘  └──────────────┘  └──────────────┘      │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────────┐                                        │
│  │  FastMCP App     │                                        │
│  │  (Core Server)   │                                        │
│  └────────┬─────────┘                                        │
│           │                                                  │
│  ┌────────▼─────────┐  ┌──────────────────┐                │
│  │  CORS Middleware │  │ Envelope         │                │
│  │  (Starlette)     │  │ Middleware       │                │
│  └──────────────────┘  └──────────────────┘                │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────┐
│     Business Logic Layer                                   │
├────────────────────────────────────────────────────────────┤
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ get_video    │ │ get_trans    │ │ get_similar  │        │
│  │ _details     │ │ _script      │ │ _videos      │        │
│  └──────┬───────┘ └──────────────┘ └──────────────┘        │
│         │                                                  │
│         ▼                                                  │
│  ┌──────────────────┐                                      │
│  │  YouTubeClient   │                                      │
│  └──────────────────┘                                      │
└──────────────────────────┬─────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│     External Services (YouTube Data API v3)                 │
└─────────────────────────────────────────────────────────────┘

2. Key Components

• FastMCP Framework: Core server with JSON-RPC handling
• CORS Middleware: Enables cross-origin requests from Llama.cpp WebUI
• Envelope Middleware: Handles Llama.cpp envelope format compatibility
• YouTubeClient: YouTube API integration with error handling
• Multiple Transports: HTTP, SSE, and STDIO support

3. Request Flow

The document details the complete request flow from client → HTTP server → CORS → Envelope → FastMCP → Tool Handler → YouTubeClient → External APIs → Response.

4. Configuration & Environment

• .env.example – Template for YouTube API key configuration
• .env_yt – Actual configuration (git-ignored)
• Environment variables for API keys, ports, and loggin