🚀 Performance Fix: Implement Lazy Loading to Resolve MCP Server Timeout Issues

[Silverstar187]

🚀 Performance Fix: Implement Lazy Loading to Resolve MCP Server Timeout Issues

Overview

This PR implements lazy loading for heavy components to resolve widespread MCP server timeout and disconnect issues. Reduces startup time from 10+ seconds to <1 second.

Problem Solved

Multiple users have reported timeout/disconnect issues across different MCP clients:

• Cursor IDE: Shows "list offering action" then stops communicating
• Claude Desktop: Server exits early during initialization
• Various MCP clients: "Request timed out" errors

Root cause: Heavy components (PyTorch CrossEncoder, Neo4j Knowledge Graph, AST parsing) loaded during startup, causing 5-10 second delays that trigger client timeouts.

Solution: Lazy Loading Implementation

Key Changes

1. Added lazy loading wrapper functions:

   • get_reranking_model() - Loads CrossEncoder only when needed
   • get_knowledge_validator() - Loads Neo4j only when needed
   • get_repo_extractor() - Loads AST parser only when needed

2. Modified lifespan function to only load essential components:

   • AsyncWebCrawler (lightweight)
   • Supabase client (fast)
   • Heavy components loaded on-demand

3. Updated tool functions to use lazy loading:

   • perform_rag_query() → uses get_reranking_model()
   • check_ai_script_hallucinations() → uses get_knowledge_validator()
   • parse_github_repository() → uses get_repo_extractor()

Performance Results

• Before: 10+ second startup time → Client timeouts
• After: <1 second startup time → No more timeouts
• Memory: Only loads components when actually used
• Compatibility: Zero breaking changes

Testing

• ✅ Docker rebuild: Confirmed <1 second startup
• ✅ Cursor IDE: No more "list offering action" timeouts
• ✅ All tools: Work correctly when called
• ✅ Memory usage: Optimized resource consumption

Impact

This fix resolves the most common issue reported by users - MCP server timeouts during startup. It makes the server much more reliable and responsive across all MCP clients.

Backward Compatibility

• ✅ No breaking changes to existing functionality
• ✅ All tools work exactly as before
• ✅ Same API interface maintained
• ✅ Existing configurations remain valid

[auraDancer]

Curious how this is working for you? It has been about 5 weeks and it seems like a good idea.

[Silverstar187]

its working everyday.
Minor issue is a red dot showing in cursor at times but nevermind:
just uploading it here for you (11 Gigabytes: silverstar3o7/crawl4ai-mcp:latest - you can pull it and try)

Even made a video about it but its german LinkedIn