mcp-vector-search 0.4.14__py3-none-any.whl → 0.5.1__py3-none-any.whl

mcp_vector_search/cli/commands/reset.py

@@ -45,23 +45,23 @@ def reset_index(
     ),
 ) -> None:
     """Reset the vector search index (clear corrupted data).
-    
+
     This command will:
     - Create a backup of the current index (unless --no-backup)
     - Clear the entire vector database
     - Preserve your configuration settings
-    
+
     After reset, run 'mcp-vector-search index' to rebuild.
     """
     root = project_root or Path.cwd()
-    
+
     try:
         # Check if project is initialized
         project_manager = ProjectManager(root)
         if not project_manager.is_initialized():
             print_error("Project not initialized. Run 'mcp-vector-search init' first.")
             raise typer.Exit(1)
-        
+
         # Get confirmation unless forced
         if not force:
             console.print(
@@ -77,28 +77,29 @@ def reset_index(
                     border_style="red",
                 )
             )
-            
+
             if not Confirm.ask("\nDo you want to proceed?", default=False):
                 console.print("[yellow]Reset cancelled[/yellow]")
                 raise typer.Exit(0)
-        
+
         # Get the database directory
         config = project_manager.load_config()
         db_path = root / ".mcp_vector_search" / "db"
-        
+
         if not db_path.exists():
             print_warning("No index found. Nothing to reset.")
             raise typer.Exit(0)
-        
+
         # Create backup if requested
         if backup:
             backup_dir = root / ".mcp_vector_search" / "backups"
             backup_dir.mkdir(exist_ok=True)
-            
+
             import time
+
             timestamp = int(time.time())
             backup_path = backup_dir / f"db_backup_{timestamp}"
-            
+
             try:
                 shutil.copytree(db_path, backup_path)
                 print_success(f"Created backup at: {backup_path.relative_to(root)}")
@@ -108,7 +109,7 @@ def reset_index(
                     if not Confirm.ask("Continue without backup?", default=False):
                         console.print("[yellow]Reset cancelled[/yellow]")
                         raise typer.Exit(0)
-        
+
         # Clear the index
         console.print("[cyan]Clearing index...[/cyan]")
         try:
@@ -118,7 +119,7 @@ def reset_index(
         except Exception as e:
             print_error(f"Failed to clear index: {e}")
             raise typer.Exit(1)
-        
+
         # Show next steps
         console.print(
             Panel(
@@ -130,7 +131,7 @@ def reset_index(
                 border_style="green",
             )
         )
-        
+
     except (DatabaseError, IndexCorruptionError) as e:
         print_error(f"Reset failed: {e}")
         raise typer.Exit(1)
@@ -156,12 +157,12 @@ def reset_all(
     ),
 ) -> None:
     """Reset everything (index and configuration).
-    
+
     This will completely remove all MCP Vector Search data,
     requiring re-initialization with 'mcp-vector-search init'.
     """
     root = project_root or Path.cwd()
-    
+
     # Get confirmation unless forced
     if not force:
         console.print(
@@ -177,28 +178,28 @@ def reset_all(
                 border_style="red",
             )
         )
-        
+
         if not Confirm.ask("\nAre you absolutely sure?", default=False):
             console.print("[yellow]Reset cancelled[/yellow]")
             raise typer.Exit(0)
-        
+
         # Double confirmation for destructive action
         if not Confirm.ask("Type 'yes' to confirm complete reset", default=False):
             console.print("[yellow]Reset cancelled[/yellow]")
             raise typer.Exit(0)
-    
+
     # Remove entire .mcp_vector_search directory
     mcp_dir = root / ".mcp_vector_search"
-    
+
     if not mcp_dir.exists():
         print_warning("No MCP Vector Search data found. Nothing to reset.")
         raise typer.Exit(0)
-    
+
     console.print("[cyan]Removing all MCP Vector Search data...[/cyan]")
     try:
         shutil.rmtree(mcp_dir)
         print_success("All data removed successfully!")
-        
+
         console.print(
             Panel(
                 "[green]✅ Complete reset done![/green]\n\n"
@@ -229,7 +230,7 @@ async def check_health(
     ),
 ) -> None:
     """Check the health of the search index.
-    
+
     This command will:
     - Verify database connectivity
     - Check for index corruption
@@ -237,49 +238,47 @@ async def check_health(
     - Optionally attempt repairs with --fix
     """
     root = project_root or Path.cwd()
-    
+
     try:
         # Check if project is initialized
         project_manager = ProjectManager(root)
         if not project_manager.is_initialized():
             print_error("Project not initialized. Run 'mcp-vector-search init' first.")
             raise typer.Exit(1)
-        
+
         console.print("[cyan]Performing health check...[/cyan]\n")
-        
+
         # Initialize database
+        from ...config.defaults import get_default_cache_path
         from ...core.database import ChromaVectorDatabase
         from ...core.embeddings import create_embedding_function
-        from ...config.defaults import get_default_cache_path
-        
+
         config = project_manager.load_config()
         db_path = root / ".mcp_vector_search" / "db"
-        
+
         # Setup embedding function and cache
-        cache_dir = (
-            get_default_cache_path(root) if config.cache_embeddings else None
-        )
+        cache_dir = get_default_cache_path(root) if config.cache_embeddings else None
         embedding_function, _ = create_embedding_function(
             model_name=config.embedding_model,
             cache_dir=cache_dir,
             cache_size=config.max_cache_size,
         )
-        
+
         # Create database instance
         db = ChromaVectorDatabase(
             persist_directory=db_path,
             embedding_function=embedding_function,
         )
-        
+
         # Initialize and check health
         try:
             await db.initialize()
             is_healthy = await db.health_check()
-            
+
             if is_healthy:
                 # Get stats for additional info
                 stats = await db.get_stats()
-                
+
                 console.print(
                     Panel(
                         f"[green]✅ Index is healthy![/green]\n\n"
@@ -304,14 +303,14 @@ async def check_health(
                         border_style="red",
                     )
                 )
-                
+
                 if fix:
                     console.print("\n[cyan]Attempting to repair index...[/cyan]")
                     # The health check already attempts recovery
                     # Try to reinitialize
                     await db.close()
                     await db.initialize()
-                    
+
                     # Check again
                     is_healthy = await db.health_check()
                     if is_healthy:
@@ -328,7 +327,7 @@ async def check_health(
                         "or 'mcp-vector-search reset index' to clear and rebuild."
                     )
                     raise typer.Exit(1)
-                    
+
         except IndexCorruptionError as e:
             console.print(
                 Panel(
@@ -342,10 +341,10 @@ async def check_health(
                 )
             )
             raise typer.Exit(1)
-            
+
         finally:
             await db.close()
-            
+
     except Exception as e:
         logger.error(f"Health check error: {e}")
         print_error(f"Health check failed: {e}")
@@ -375,6 +374,7 @@ def reset_main(ctx: typer.Context) -> None:
 # Export for backwards compatibility
 main = reset_main
 
+
 # Make health check synchronous for CLI
 def health_main(
     project_root: Path = typer.Option(
@@ -390,4 +390,4 @@ def health_main(
     ),
 ) -> None:
     """Check the health of the search index (sync wrapper)."""
-    asyncio.run(check_health(project_root, fix))
+    asyncio.run(check_health(project_root, fix))

mcp_vector_search/cli/commands/search.py

@@ -14,7 +14,9 @@ from ...core.search import SemanticSearchEngine
 from ..didyoumean import create_enhanced_typer
 from ..output import (
     print_error,
+    print_info,
     print_search_results,
+    print_tip,
 )
 
 # Create search subcommand app with "did you mean" functionality (kept for backward compatibility)
@@ -23,7 +25,7 @@ search_app = create_enhanced_typer(help="Search code semantically")
 
 def search_main(
     ctx: typer.Context,
-    query: str = typer.Argument(..., help="Search query"),
+    query: str = typer.Argument(..., help="Search query or file path (for --similar)"),
     project_root: Path | None = typer.Option(
         None,
         "--project-root",
@@ -33,6 +35,7 @@ def search_main(
         file_okay=False,
         dir_okay=True,
         readable=True,
+        rich_help_panel="🔧 Global Options",
     ),
     limit: int = typer.Option(
         10,
@@ -41,27 +44,32 @@ def search_main(
         help="Maximum number of results to return",
         min=1,
         max=100,
+        rich_help_panel="📊 Result Options",
     ),
     files: str | None = typer.Option(
         None,
         "--files",
         "-f",
         help="Filter by file patterns (e.g., '*.py' or 'src/*.js')",
+        rich_help_panel="🔍 Filters",
     ),
     language: str | None = typer.Option(
         None,
         "--language",
-        help="Filter by programming language",
+        help="Filter by programming language (python, javascript, typescript)",
+        rich_help_panel="🔍 Filters",
     ),
     function_name: str | None = typer.Option(
         None,
         "--function",
         help="Filter by function name",
+        rich_help_panel="🔍 Filters",
     ),
     class_name: str | None = typer.Option(
         None,
         "--class",
         help="Filter by class name",
+        rich_help_panel="🔍 Filters",
     ),
     similarity_threshold: float | None = typer.Option(
         None,
@@ -70,57 +78,87 @@ def search_main(
         help="Minimum similarity threshold (0.0 to 1.0)",
         min=0.0,
         max=1.0,
+        rich_help_panel="🎯 Search Options",
     ),
     similar: bool = typer.Option(
         False,
         "--similar",
         help="Find code similar to the query (treats query as file path)",
+        rich_help_panel="🎯 Search Options",
     ),
     context: bool = typer.Option(
         False,
         "--context",
         help="Search for code based on contextual description",
+        rich_help_panel="🎯 Search Options",
     ),
     focus: str | None = typer.Option(
         None,
         "--focus",
         help="Focus areas for context search (comma-separated)",
+        rich_help_panel="🎯 Search Options",
     ),
     no_content: bool = typer.Option(
         False,
         "--no-content",
         help="Don't show code content in results",
+        rich_help_panel="📊 Result Options",
     ),
     json_output: bool = typer.Option(
         False,
         "--json",
         help="Output results in JSON format",
+        rich_help_panel="📊 Result Options",
     ),
     export_format: str | None = typer.Option(
         None,
         "--export",
         help="Export results to file (json, csv, markdown, summary)",
+        rich_help_panel="💾 Export Options",
     ),
     export_path: Path | None = typer.Option(
         None,
         "--export-path",
         help="Custom export file path",
+        rich_help_panel="💾 Export Options",
     ),
 ) -> None:
-    """Search your codebase semantically.
+    """🔍 Search your codebase semantically.
 
-    This command performs semantic search across your indexed codebase,
-    finding code that is conceptually similar to your query even if it
-    doesn't contain the exact keywords.
+    Performs vector similarity search across your indexed code to find relevant
+    functions, classes, and patterns based on semantic meaning, not just keywords.
 
-    Examples:
-        mcp-vector-search search "authentication middleware"
-        mcp-vector-search search "database connection" --language python
-        mcp-vector-search search "error handling" --files "*.js" --limit 5
-        mcp-vector-search search "user validation" --function validate --json
-        mcp-vector-search search "src/auth.py" --similar
-        mcp-vector-search search "implement rate limiting" --context
-        mcp-vector-search search "user authentication" --context --focus security,middleware
+    [bold cyan]Basic Search Examples:[/bold cyan]
+
+    [green]Simple semantic search:[/green]
+        $ mcp-vector-search search "authentication middleware"
+
+    [green]Search with language filter:[/green]
+        $ mcp-vector-search search "database connection" --language python
+
+    [green]Limit results:[/green]
+        $ mcp-vector-search search "error handling" --limit 5
+
+    [bold cyan]Advanced Search:[/bold cyan]
+
+    [green]Filter by file pattern:[/green]
+        $ mcp-vector-search search "validation" --files "src/*.py"
+
+    [green]Find similar code:[/green]
+        $ mcp-vector-search search "src/auth.py" --similar
+
+    [green]Context-based search:[/green]
+        $ mcp-vector-search search "implement rate limiting" --context --focus security
+
+    [bold cyan]Export Results:[/bold cyan]
+
+    [green]Export to JSON:[/green]
+        $ mcp-vector-search search "api endpoints" --export json
+
+    [green]Export to markdown:[/green]
+        $ mcp-vector-search search "utils" --export markdown
+
+    [dim]💡 Tip: Use quotes for multi-word queries. Adjust --threshold for more/fewer results.[/dim]
     """
     try:
         project_root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -303,6 +341,27 @@ async def run_search(
                     show_content=show_content,
                 )
 
+                # Add contextual tips based on results
+                if results:
+                    if len(results) >= limit:
+                        print_tip(
+                            f"More results may be available. Use [cyan]--limit {limit * 2}[/cyan] to see more."
+                        )
+                    if not export_format:
+                        print_tip(
+                            "Export results with [cyan]--export json[/cyan] or [cyan]--export markdown[/cyan]"
+                        )
+                else:
+                    # No results - provide helpful suggestions
+                    print_info("\n[bold]No results found. Try:[/bold]")
+                    print_info("  • Use more general terms in your query")
+                    print_info(
+                        "  • Lower the similarity threshold with [cyan]--threshold 0.3[/cyan]"
+                    )
+                    print_info(
+                        "  • Check if files are indexed with [cyan]mcp-vector-search status[/cyan]"
+                    )
+
     except Exception as e:
         logger.error(f"Search execution failed: {e}")
         raise

mcp_vector_search/cli/commands/status.py

@@ -38,39 +38,63 @@ def main(
         file_okay=False,
         dir_okay=True,
         readable=True,
+        rich_help_panel="🔧 Global Options",
     ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
         "-v",
-        help="Show detailed information",
+        help="Show detailed information including paths and patterns",
+        rich_help_panel="📊 Display Options",
     ),
     health_check: bool = typer.Option(
         False,
         "--health-check",
-        help="Perform health check of all components",
+        help="Perform comprehensive health check of all components",
+        rich_help_panel="🔍 Diagnostics",
     ),
     mcp: bool = typer.Option(
         False,
         "--mcp",
         help="Check Claude Code MCP integration status",
+        rich_help_panel="🔍 Diagnostics",
     ),
     json_output: bool = typer.Option(
         False,
         "--json",
         help="Output status in JSON format",
+        rich_help_panel="📊 Display Options",
     ),
 ) -> None:
-    """Show project status and indexing statistics.
+    """📊 Show project status and indexing statistics.
 
-    This command displays comprehensive information about your MCP Vector Search
-    project including configuration, indexing status, and system health.
+    Displays comprehensive information about your project including configuration,
+    indexing statistics, and system health. Use this to verify setup and monitor
+    indexing progress.
 
-    Examples:
-        mcp-vector-search status
-        mcp-vector-search status --verbose
-        mcp-vector-search status --health-check --json
-        mcp-vector-search status --mcp
+    [bold cyan]Basic Examples:[/bold cyan]
+
+    [green]Quick status check:[/green]
+        $ mcp-vector-search status
+
+    [green]Detailed status with all information:[/green]
+        $ mcp-vector-search status --verbose
+
+    [green]Check MCP integration:[/green]
+        $ mcp-vector-search status --mcp
+
+    [bold cyan]Diagnostics:[/bold cyan]
+
+    [green]Full health check:[/green]
+        $ mcp-vector-search status --health-check
+
+    [green]Export status to JSON:[/green]
+        $ mcp-vector-search status --json > status.json
+
+    [green]Combined diagnostics:[/green]
+        $ mcp-vector-search status --verbose --health-check --mcp
+
+    [dim]💡 Tip: Use --health-check to diagnose issues with dependencies or database.[/dim]
     """
     try:
         # Use provided project_root or current working directory
@@ -207,7 +231,9 @@ async def show_status(
         raise
 
 
-def _display_status(status_data: dict[str, Any], verbose: bool, mcp: bool = False) -> None:
+def _display_status(
+    status_data: dict[str, Any], verbose: bool, mcp: bool = False
+) -> None:
     """Display status in human-readable format."""
     project_data = status_data["project"]
     config_data = status_data["configuration"]
@@ -287,7 +313,9 @@ def _display_status(status_data: dict[str, Any], verbose: bool, mcp: bool = Fals
         elif server_status == "not_installed":
             console.print(f"[red]✗[/red] MCP Server '{server_name}': Not installed")
         else:
-            console.print(f"[yellow]⚠[/yellow] MCP Server '{server_name}': {server_status}")
+            console.print(
+                f"[yellow]⚠[/yellow] MCP Server '{server_name}': {server_status}"
+            )
 
         if mcp_data.get("project_config"):
             console.print("[green]✓[/green] Project Configuration: Found")
@@ -370,7 +398,9 @@ async def perform_health_check(project_root: Path, config) -> dict[str, Any]:
     return health_status
 
 
-async def check_mcp_integration(project_root: Path, server_name: str = "mcp-vector-search") -> dict[str, Any]:
+async def check_mcp_integration(
+    project_root: Path, server_name: str = "mcp-vector-search"
+) -> dict[str, Any]:
     """Check MCP integration status."""
     mcp_status = {
         "claude_available": False,
@@ -396,14 +426,16 @@ async def check_mcp_integration(project_root: Path, server_name: str = "mcp-vect
                     [claude_cmd, "mcp", "get", server_name],
                     capture_output=True,
                     text=True,
-                    timeout=10
+                    timeout=10,
                 )
 
                 if result.returncode == 0:
                     mcp_status["server_status"] = "installed"
                 else:
                     mcp_status["server_status"] = "not_installed"
-                    mcp_status["issues"].append(f"MCP server '{server_name}' not found in Claude Code")
+                    mcp_status["issues"].append(
+                        f"MCP server '{server_name}' not found in Claude Code"
+                    )
 
             except subprocess.TimeoutExpired:
                 mcp_status["server_status"] = "timeout"
@@ -418,12 +450,14 @@ async def check_mcp_integration(project_root: Path, server_name: str = "mcp-vect
         claude_json_path = project_root / ".claude.json"
         if claude_json_path.exists():
             try:
-                with open(claude_json_path, 'r') as f:
+                with open(claude_json_path) as f:
                     config = json.load(f)
                 if config.get("mcpServers", {}).get(server_name):
                     mcp_status["project_config"] = True
                 else:
-                    mcp_status["issues"].append(f"MCP server '{server_name}' not found in project .claude.json")
+                    mcp_status["issues"].append(
+                        f"MCP server '{server_name}' not found in project .claude.json"
+                    )
             except Exception as e:
                 mcp_status["issues"].append(f"Error reading project .claude.json: {e}")
         else: