feat: Add Deep Research System v4.2.0 (#380)

feat: Add Deep Research System v4.2.0 - Autonomous web research capabilities

## Overview
Comprehensive implementation of Deep Research framework aligned with DR Agent architecture, enabling autonomous, adaptive, and intelligent web research capabilities.

## Key Features

### 🔬 Deep Research Agent
- 15th specialized agent for comprehensive research orchestration
- Adaptive planning strategies: Planning-Only, Intent-Planning, Unified Intent-Planning
- Multi-hop reasoning with genealogy tracking (up to 5 hops)
- Self-reflective mechanisms with confidence scoring (0.0-1.0)
- Case-based learning for cross-session intelligence

### 🎯 New /sc:research Command
- Intelligent web research with depth control (quick/standard/deep/exhaustive)
- Parallel-first execution for optimal performance
- Domain filtering and time-based search options
- Automatic report generation in claudedocs/

### 🔍 Tavily MCP Integration
- 7th MCP server for real-time web search
- News search with time filtering
- Content extraction from search results
- Multi-round searching with iterative refinement
- Free tier available with optional API key

### 🎨 MODE_DeepResearch
- 7th behavioral mode for systematic investigation
- 6-phase workflow: Understand → Plan → TodoWrite → Execute → Track → Validate
- Evidence-based reasoning with citation management
- Parallel operation defaults for efficiency

## Technical Changes

### Framework Updates
- Updated agent count: 14 → 15 agents
- Updated mode count: 6 → 7 modes
- Updated MCP server count: 6 → 7 servers
- Updated command count: 24 → 25 commands

### Configuration
- Added RESEARCH_CONFIG.md for research settings
- Added deep_research_workflows.md with examples
- Standardized file naming conventions (UPPERCASE for Core)
- Removed multi-source investigation features for simplification

### Integration Points
- Enhanced MCP component with remote server support
- Added check_research_prerequisites() in environment.py
- Created verify_research_integration.sh script
- Updated all documentation guides

## Requirements
- TAVILY_API_KEY environment variable (free tier available)
- Node.js and npm for Tavily MCP execution

## Documentation
- Complete user guide integration
- Workflow examples and best practices
- API configuration instructions
- Depth level explanations

🤖 Generated with Claude Code

Co-authored-by: moshe_anconina <moshe_a@ituran.com>
Co-authored-by: Claude <noreply@anthropic.com>

setup/__init__.py

@@ -8,7 +8,7 @@ from pathlib import Path
 try:
     __version__ = (Path(__file__).parent.parent / "VERSION").read_text().strip()
 except Exception:
-    __version__ = "4.1.4"  # Fallback
+    __version__ = "4.2.0"  # Fallback - Deep Research Integration
 
 __author__ = "NomenAK, Mithun Gowda B"
 

setup/components/agents.py

@@ -21,7 +21,7 @@ class AgentsComponent(Component):
         return {
             "name": "agents",
             "version": __version__,
-            "description": "14 specialized AI agents with domain expertise and intelligent routing",
+            "description": "15 specialized AI agents with domain expertise and intelligent routing",
             "category": "agents"
         }
     

setup/components/mcp.py

@@ -67,6 +67,15 @@ class MCPComponent(Component):
                 "required": False,
                 "api_key_env": "MORPH_API_KEY",
                 "api_key_description": "Morph API key for Fast Apply"
+            },
+            "tavily": {
+                "name": "tavily",
+                "description": "Web search and real-time information retrieval for deep research",
+                "install_method": "npm",
+                "install_command": "npx -y tavily-mcp@0.1.2",
+                "required": False,
+                "api_key_env": "TAVILY_API_KEY",
+                "api_key_description": "Tavily API key for web search (get from https://app.tavily.com)"
             }
         }
     
@@ -296,6 +305,7 @@ class MCPComponent(Component):
         except Exception as e:
             self.logger.error(f"Error installing MCP server {server_name} using uv: {e}")
             return False
+    
 
     def _install_github_mcp_server(self, server_info: Dict[str, Any], config: Dict[str, Any]) -> bool:
         """Install a single MCP server from GitHub using uvx"""
@@ -535,9 +545,10 @@ class MCPComponent(Component):
 
         server_name = server_info["name"]
         npm_package = server_info.get("npm_package")
+        install_command = server_info.get("install_command")
 
-        if not npm_package:
-            self.logger.error(f"No npm_package found for server {server_name}")
+        if not npm_package and not install_command:
+            self.logger.error(f"No npm_package or install_command found for server {server_name}")
             return False
         
         command = "npx"
@@ -567,18 +578,35 @@ class MCPComponent(Component):
                         self.logger.warning(f"Proceeding without {api_key_env} - server may not function properly")
             
             # Install using Claude CLI
-            if config.get("dry_run"):
-                self.logger.info(f"Would install MCP server (user scope): claude mcp add -s user {server_name} {command} -y {npm_package}")
-                return True
-            
-            self.logger.debug(f"Running: claude mcp add -s user {server_name} {command} -y {npm_package}")
-            
-            result = self._run_command_cross_platform(
-                ["claude", "mcp", "add", "-s", "user", "--", server_name, command, "-y", npm_package],
-                capture_output=True,
-                text=True,
-                timeout=120  # 2 minutes timeout for installation
-            )
+            if install_command:
+                # Use the full install command (e.g., for tavily-mcp@0.1.2)
+                install_args = install_command.split()
+                if config.get("dry_run"):
+                    self.logger.info(f"Would install MCP server (user scope): claude mcp add -s user {server_name} {' '.join(install_args)}")
+                    return True
+                
+                self.logger.debug(f"Running: claude mcp add -s user {server_name} {' '.join(install_args)}")
+                
+                result = self._run_command_cross_platform(
+                    ["claude", "mcp", "add", "-s", "user", "--", server_name] + install_args,
+                    capture_output=True,
+                    text=True,
+                    timeout=120  # 2 minutes timeout for installation
+                )
+            else:
+                # Use npm_package
+                if config.get("dry_run"):
+                    self.logger.info(f"Would install MCP server (user scope): claude mcp add -s user {server_name} {command} -y {npm_package}")
+                    return True
+                
+                self.logger.debug(f"Running: claude mcp add -s user {server_name} {command} -y {npm_package}")
+                
+                result = self._run_command_cross_platform(
+                    ["claude", "mcp", "add", "-s", "user", "--", server_name, command, "-y", npm_package],
+                    capture_output=True,
+                    text=True,
+                    timeout=120  # 2 minutes timeout for installation
+                )
             
             if result.returncode == 0:
                 self.logger.success(f"Successfully installed MCP server (user scope): {server_name}")

setup/components/mcp_docs.py

@@ -28,7 +28,8 @@ class MCPDocsComponent(Component):
             "playwright": "MCP_Playwright.md",
             "serena": "MCP_Serena.md",
             "morphllm": "MCP_Morphllm.md",
-            "morphllm-fast-apply": "MCP_Morphllm.md"  # Handle both naming conventions
+            "morphllm-fast-apply": "MCP_Morphllm.md",  # Handle both naming conventions
+            "tavily": "MCP_Tavily.md"
         }
         
         super().__init__(install_dir, Path(""))

setup/components/modes.py

@@ -22,7 +22,7 @@ class ModesComponent(Component):
         return {
             "name": "modes",
             "version": __version__,
-            "description": "SuperClaude behavioral modes (Brainstorming, Introspection, Task Management, Token Efficiency)",
+            "description": "7 behavioral modes for enhanced Claude Code operation",
             "category": "modes"
         }
     

setup/utils/environment.py

@@ -466,4 +466,48 @@ def create_env_file(api_keys: Dict[str, str], env_file_path: Optional[Path] = No
     except Exception as e:
         logger.error(f"Failed to create .env file: {e}")
         display_warning(f"Could not create .env file: {e}")
-        return False
+        return False
+
+
+def check_research_prerequisites() -> tuple[bool, list[str]]:
+    """
+    Check if deep research prerequisites are met
+    
+    Returns:
+        Tuple of (success: bool, warnings: List[str])
+    """
+    warnings = []
+    logger = get_logger()
+    
+    # Check Tavily API key
+    if not os.environ.get("TAVILY_API_KEY"):
+        warnings.append(
+            "TAVILY_API_KEY not set - Deep research web search will not work\n"
+            "Get your key from: https://app.tavily.com"
+        )
+        logger.warning("TAVILY_API_KEY not found in environment")
+    else:
+        logger.info("Found TAVILY_API_KEY in environment")
+    
+    # Check Node.js for MCP
+    import shutil
+    if not shutil.which("node"):
+        warnings.append(
+            "Node.js not found - Required for Tavily MCP\n"
+            "Install from: https://nodejs.org"
+        )
+        logger.warning("Node.js not found - required for Tavily MCP")
+    else:
+        logger.info("Node.js found")
+    
+    # Check npm
+    if not shutil.which("npm"):
+        warnings.append(
+            "npm not found - Required for MCP server installation\n"
+            "Usually installed with Node.js"
+        )
+        logger.warning("npm not found - required for MCP installation")
+    else:
+        logger.info("npm found")
+    
+    return len(warnings) == 0, warnings