mcp-vector-search 0.4.13__py3-none-any.whl → 0.5.0__py3-none-any.whl

mcp_vector_search/cli/main.py

@@ -12,14 +12,17 @@ from .commands.auto_index import auto_index_app
 from .commands.config import config_app
 from .commands.index import index_app
 from .commands.init import (
-    init_app,
-    main as init_main,
     check_initialization as init_check,
+)
+from .commands.init import (
     init_mcp_integration,
     list_embedding_models,
 )
-from .commands.install import install_app
+from .commands.init import (
+    main as init_main,
+)
 from .commands.mcp import mcp_app
+from .commands.reset import health_main, reset_app
 from .commands.search import (
     search_app,
     search_context_cmd,
@@ -28,10 +31,9 @@ from .commands.search import (
 )
 from .commands.status import status_app
 from .commands.watch import app as watch_app
-from .commands.reset import reset_app, health_main
-from .didyoumean import create_enhanced_typer, add_common_suggestions
-from .suggestions import get_contextual_suggestions, ContextualSuggestionProvider
+from .didyoumean import add_common_suggestions, create_enhanced_typer
 from .output import print_error, setup_logging
+from .suggestions import get_contextual_suggestions
 
 # Install rich traceback handler
 install(show_locals=True)
@@ -42,15 +44,41 @@ console = Console()
 # Create main Typer app with "did you mean" functionality
 app = create_enhanced_typer(
     name="mcp-vector-search",
-    help="CLI-first semantic code search with MCP integration",
+    help="""
+🔍 [bold]CLI-first semantic code search with MCP integration[/bold]
+
+Semantic search finds code by meaning, not just keywords. Perfect for exploring
+unfamiliar codebases, finding similar patterns, and integrating with AI tools.
+
+[bold cyan]Quick Start:[/bold cyan]
+  1. Initialize: [green]mcp-vector-search init[/green]
+  2. Search code: [green]mcp-vector-search search "your query"[/green]
+  3. Check status: [green]mcp-vector-search status[/green]
+
+[bold cyan]Key Features:[/bold cyan]
+  🤖 MCP Integration: Works with Claude Code, Cursor, and AI tools
+  ⚡ Fast Indexing: Incremental updates with file watching
+  🎯 Semantic Search: Find code by meaning, not just keywords
+  📊 Rich Output: Beautiful terminal formatting with syntax highlighting
+
+[bold cyan]Configuration Files:[/bold cyan]
+  • Project: .mcp-vector-search/config.json
+  • Claude Code: .claude/settings.local.json
+  • Global cache: ~/.cache/mcp-vector-search/
+
+[dim]For detailed help on any command: [cyan]mcp-vector-search COMMAND --help[/cyan][/dim]
+[dim]Documentation: [cyan]https://github.com/yourusername/mcp-vector-search[/cyan][/dim]
+    """,
     add_completion=False,
     rich_markup_mode="rich",
 )
 
 # Import command functions for direct registration and aliases
-from .commands.install import main as install_main, demo as install_demo
-from .commands.status import main as status_main
 from .commands.index import main as index_main
+from .commands.install import demo as install_demo
+from .commands.install import main as install_main
+from .commands.status import main as status_main
+
 # Note: config doesn't have a main function, it uses subcommands via config_app
 app.command("install", help="🚀 Install mcp-vector-search in projects")(install_main)
 app.command("demo", help="🎬 Run installation demo with sample project")(install_demo)
@@ -59,8 +87,12 @@ app.command("status", help="📊 Show project status and statistics")(status_mai
 app.command("init", help="🔧 Initialize project for semantic search")(init_main)
 # Add init subcommands as separate commands
 app.command("init-check", help="Check if project is initialized")(init_check)
-app.command("init-mcp", help="Install/fix Claude Code MCP integration")(init_mcp_integration)
-app.command("init-models", help="List available embedding models")(list_embedding_models)
+app.command("init-mcp", help="Install/fix Claude Code MCP integration")(
+    init_mcp_integration
+)
+app.command("init-models", help="List available embedding models")(
+    list_embedding_models
+)
 app.add_typer(index_app, name="index", help="Index codebase for semantic search")
 app.add_typer(config_app, name="config", help="Manage project configuration")
 app.add_typer(watch_app, name="watch", help="Watch for file changes and update index")
@@ -72,23 +104,43 @@ app.add_typer(reset_app, name="reset", help="Reset and recovery operations")
 app.command("search", help="Search code semantically")(search_main)
 
 # Keep old nested structure for backward compatibility
-app.add_typer(search_app, name="search-legacy", help="Legacy search commands", hidden=True)
-app.add_typer(status_app, name="status-legacy", help="Legacy status commands", hidden=True)
+app.add_typer(
+    search_app, name="search-legacy", help="Legacy search commands", hidden=True
+)
+app.add_typer(
+    status_app, name="status-legacy", help="Legacy status commands", hidden=True
+)
 
 # Add command aliases for better user experience
 app.command("find", help="Search code semantically (alias for search)")(search_main)
-app.command("f", help="Search code semantically (short alias)", hidden=True)(search_main)  # Hidden short alias
-app.command("s", help="Search code semantically (short alias)", hidden=True)(search_main)  # Hidden short alias
-app.command("query", help="Search code semantically (alias for search)", hidden=True)(search_main)  # Hidden alias
+app.command("f", help="Search code semantically (short alias)", hidden=True)(
+    search_main
+)  # Hidden short alias
+app.command("s", help="Search code semantically (short alias)", hidden=True)(
+    search_main
+)  # Hidden short alias
+app.command("query", help="Search code semantically (alias for search)", hidden=True)(
+    search_main
+)  # Hidden alias
 
 # Index aliases
-app.command("i", help="Index codebase (short alias)", hidden=True)(index_main)  # Hidden short alias
-app.command("build", help="Index codebase (alias for index)", hidden=True)(index_main)  # Hidden alias
-app.command("scan", help="Index codebase (alias for index)", hidden=True)(index_main)  # Hidden alias
-
-# Status aliases  
-app.command("st", help="Show status (short alias)", hidden=True)(status_main)  # Hidden short alias
-app.command("info", help="Show project information (alias for status)", hidden=True)(status_main)  # Hidden alias
+app.command("i", help="Index codebase (short alias)", hidden=True)(
+    index_main
+)  # Hidden short alias
+app.command("build", help="Index codebase (alias for index)", hidden=True)(
+    index_main
+)  # Hidden alias
+app.command("scan", help="Index codebase (alias for index)", hidden=True)(
+    index_main
+)  # Hidden alias
+
+# Status aliases
+app.command("st", help="Show status (short alias)", hidden=True)(
+    status_main
+)  # Hidden short alias
+app.command("info", help="Show project information (alias for status)", hidden=True)(
+    status_main
+)  # Hidden alias
 
 # Config aliases - Since config uses subcommands, these will be handled by the enhanced typer error resolution
 # app.command("c", help="Manage configuration (short alias)", hidden=True)  # Will be handled by typo resolution
@@ -112,7 +164,15 @@ def interactive_search(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Start an interactive search session with filtering and refinement."""
+    """Start an interactive search session with filtering and refinement.
+
+    The interactive mode provides a rich terminal interface for searching your codebase
+    with real-time filtering, query refinement, and result navigation.
+
+    Examples:
+        mcp-vector-search interactive
+        mcp-vector-search interactive --project-root /path/to/project
+    """
     import asyncio
 
     from .interactive import start_interactive_search
@@ -137,7 +197,15 @@ def show_history(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Show search history."""
+    """Show search history.
+
+    Displays your recent search queries with timestamps and result counts.
+    Use this to revisit previous searches or track your search patterns.
+
+    Examples:
+        mcp-vector-search history
+        mcp-vector-search history --limit 50
+    """
     from .history import show_search_history
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -151,7 +219,14 @@ def show_favorites_cmd(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Show favorite queries."""
+    """Show favorite queries.
+
+    Displays your saved favorite search queries. Favorites allow you to quickly
+    access frequently used searches without typing them again.
+
+    Examples:
+        mcp-vector-search favorites
+    """
     from .history import show_favorites
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -167,7 +242,15 @@ def add_favorite(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Add a query to favorites."""
+    """Add a query to favorites.
+
+    Save a search query to your favorites list for quick access later.
+    Optionally include a description to help remember what the query is for.
+
+    Examples:
+        mcp-vector-search add-favorite "authentication functions"
+        mcp-vector-search add-favorite "error handling" --desc "Error handling patterns"
+    """
     from .history import SearchHistory
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -183,7 +266,13 @@ def remove_favorite(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Remove a query from favorites."""
+    """Remove a query from favorites.
+
+    Remove a previously saved favorite query from your favorites list.
+
+    Examples:
+        mcp-vector-search remove-favorite "authentication functions"
+    """
     from .history import SearchHistory
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -195,10 +284,24 @@ def remove_favorite(
 def main(
     ctx: typer.Context,
     version: bool = typer.Option(
-        False, "--version", "-v", help="Show version and exit"
+        False,
+        "--version",
+        "-v",
+        help="Show version and exit",
+        rich_help_panel="ℹ️  Information",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Enable verbose logging",
+        rich_help_panel="🔧 Global Options",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        help="Suppress non-error output",
+        rich_help_panel="🔧 Global Options",
     ),
-    verbose: bool = typer.Option(False, "--verbose", help="Enable verbose logging"),
-    quiet: bool = typer.Option(False, "--quiet", help="Suppress non-error output"),
     project_root: Path | None = typer.Option(
         None,
         "--project-root",
@@ -208,6 +311,7 @@ def main(
         file_okay=False,
         dir_okay=True,
         readable=True,
+        rich_help_panel="🔧 Global Options",
     ),
 ) -> None:
     """MCP Vector Search - CLI-first semantic code search with MCP integration.
@@ -254,19 +358,21 @@ def handle_command_error(ctx, param, value):
 
     # This will be called when a command is not found
     import click
+
     try:
         return value
     except click.UsageError as e:
         if "No such command" in str(e):
             # Extract the command name from the error
             import re
+
             match = re.search(r"No such command '([^']+)'", str(e))
             if match:
                 command_name = match.group(1)
-                
+
                 # Use both the original suggestions and contextual suggestions
                 add_common_suggestions(ctx, command_name)
-                
+
                 # Add contextual suggestions based on project state
                 try:
                     project_root = ctx.obj.get("project_root") if ctx.obj else None
@@ -277,23 +383,32 @@ def handle_command_error(ctx, param, value):
         raise
 
 
-
-
 @app.command()
 def help_contextual() -> None:
     """Show contextual help and suggestions based on project state."""
     try:
         project_root = Path.cwd()
-        console.print(f"[bold blue]mcp-vector-search[/bold blue] version [green]{__version__}[/green]")
+        console.print(
+            f"[bold blue]mcp-vector-search[/bold blue] version [green]{__version__}[/green]"
+        )
         console.print("[dim]CLI-first semantic code search with MCP integration[/dim]")
         get_contextual_suggestions(project_root)
-    except Exception as e:
-        console.print("\n[dim]Use [bold]mcp-vector-search --help[/bold] for more information.[/dim]")
+    except Exception:
+        console.print(
+            "\n[dim]Use [bold]mcp-vector-search --help[/bold] for more information.[/dim]"
+        )
 
 
 @app.command()
 def doctor() -> None:
-    """Check system dependencies and configuration."""
+    """Check system dependencies and configuration.
+
+    Runs diagnostic checks to ensure all required dependencies are installed
+    and properly configured. Use this command to troubleshoot installation issues.
+
+    Examples:
+        mcp-vector-search doctor
+    """
     from .commands.status import check_dependencies
 
     console.print("[bold blue]MCP Vector Search - System Check[/bold blue]\n")
@@ -310,14 +425,12 @@ def doctor() -> None:
         )
 
 
-
-
-
 def cli_with_suggestions():
     """CLI wrapper that catches errors and provides suggestions."""
     import sys
+
     import click
-    
+
     try:
         # Call the app with standalone_mode=False to get exceptions instead of sys.exit
         app(standalone_mode=False)
@@ -326,40 +439,46 @@ def cli_with_suggestions():
         if "No such command" in str(e):
             # Extract the command name from the error
             import re
+
             match = re.search(r"No such command '([^']+)'", str(e))
             if match:
                 command_name = match.group(1)
-                
+
                 # Show enhanced suggestions
                 from rich.console import Console
+
                 console = Console(stderr=True)
                 console.print(f"\\n[red]Error:[/red] {e}")
-                
+
                 # Show enhanced suggestions
                 add_common_suggestions(None, command_name)
-                
+
                 # Show contextual suggestions too
                 try:
                     project_root = Path.cwd()
                     get_contextual_suggestions(project_root, command_name)
                 except Exception:
                     pass
-                
+
                 sys.exit(2)  # Exit with error code
-        
+
         # For other usage errors, show the default message and exit
         click.echo(f"Error: {e}", err=True)
         sys.exit(2)
     except click.Abort:
         # User interrupted (Ctrl+C)
         sys.exit(1)
-    except SystemExit as e:
+    except SystemExit:
         # Re-raise system exits
         raise
     except Exception as e:
-        # For other exceptions, show error and exit
-        click.echo(f"Unexpected error: {e}", err=True)
-        sys.exit(1)
+        # For other exceptions, show error and exit if verbose logging is enabled
+        # Suppress internal framework errors in normal operation
+        if "--verbose" in sys.argv or "-v" in sys.argv:
+            click.echo(f"Unexpected error: {e}", err=True)
+            sys.exit(1)
+        # Otherwise, just exit silently to avoid confusing error messages
+        pass
 
 
 if __name__ == "__main__":

mcp_vector_search/cli/output.py

@@ -258,3 +258,155 @@ def print_json(data: Any, title: str | None = None) -> None:
         console.print(Panel(syntax, title=title, border_style="blue"))
     else:
         console.print(syntax)
+
+
+def print_panel(
+    content: str,
+    title: str | None = None,
+    border_style: str = "blue",
+    padding: tuple[int, int] = (1, 2),
+) -> None:
+    """Print content in a Rich panel.
+
+    Args:
+        content: The content to display in the panel
+        title: Optional title for the panel
+        border_style: Border color/style (default: "blue")
+        padding: Tuple of (vertical, horizontal) padding
+    """
+    console.print(
+        Panel(
+            content,
+            title=title,
+            border_style=border_style,
+            padding=padding,
+        )
+    )
+
+
+def print_next_steps(steps: list[str], title: str = "Next Steps") -> None:
+    """Print next step hints after a command execution.
+
+    Args:
+        steps: List of next step descriptions
+        title: Panel title (default: "Next Steps")
+    """
+    content = "\n".join(f"  {i}. {step}" for i, step in enumerate(steps, 1))
+    print_panel(content, title=f"🚀 {title}", border_style="blue")
+
+
+def print_tip(message: str) -> None:
+    """Print a helpful tip message.
+
+    Args:
+        message: The tip message to display
+    """
+    console.print(f"[dim]💡 Tip: {message}[/dim]")
+
+
+def print_completion_status(
+    title: str,
+    completed_items: list[str],
+    pending_items: list[str] | None = None,
+) -> None:
+    """Print completion status with checkmarks.
+
+    Args:
+        title: Status title
+        completed_items: List of completed items
+        pending_items: Optional list of pending items
+    """
+    content_lines = []
+
+    if completed_items:
+        content_lines.append("[bold green]✨ Completed:[/bold green]")
+        for item in completed_items:
+            content_lines.append(f"  ✅ {item}")
+
+    if pending_items:
+        content_lines.append("\n[bold yellow]📋 Pending:[/bold yellow]")
+        for item in pending_items:
+            content_lines.append(f"  ☐ {item}")
+
+    print_panel("\n".join(content_lines), title=title, border_style="green")
+
+
+def print_setup_progress(
+    completed_steps: list[str],
+    all_steps: list[tuple[str, str]] | None = None,
+) -> None:
+    """Display setup workflow progress.
+
+    Args:
+        completed_steps: List of completed step IDs
+        all_steps: Optional list of (step_id, step_name) tuples
+    """
+    if all_steps is None:
+        all_steps = [
+            ("initialize", "Initialize project"),
+            ("configure", "Configure settings"),
+            ("index", "Index codebase"),
+            ("mcp_setup", "Setup MCP integration"),
+            ("verify", "Verify installation"),
+        ]
+
+    completed = len([s for s, _ in all_steps if s in completed_steps])
+    total = len(all_steps)
+    percentage = (completed / total) * 100
+
+    console.print(f"\n🚀 Setup Progress: {completed}/{total} ({percentage:.0f}%)")
+
+    for step_id, step_name in all_steps:
+        status = "✓" if step_id in completed_steps else "☐"
+        style = "green" if step_id in completed_steps else "dim"
+        console.print(f"  {status} {step_name}", style=style)
+
+
+def print_error_with_recovery(error_message: str, recovery_steps: list[str]) -> None:
+    """Print error message with recovery hints.
+
+    Args:
+        error_message: The error message
+        recovery_steps: List of recovery step descriptions
+    """
+    print_error(error_message)
+
+    console.print("\n[bold]How to fix:[/bold]")
+    for i, step in enumerate(recovery_steps, 1):
+        console.print(f"  {i}. {step}")
+
+    console.print("\n[dim]For more help: mcp-vector-search --help[/dim]")
+
+
+def print_command_examples(
+    command: str,
+    examples: list[tuple[str, str]],
+) -> None:
+    """Print command examples in a formatted table.
+
+    Args:
+        command: Base command name
+        examples: List of (description, example) tuples
+    """
+    table = Table(
+        title=f"Examples: {command}",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Description", style="white", no_wrap=False)
+    table.add_column("Command", style="green", no_wrap=False)
+
+    for description, example in examples:
+        table.add_row(description, example)
+
+    console.print(table)
+
+
+def print_config_hint(config_type: str, config_path: str) -> None:
+    """Print configuration file location hint.
+
+    Args:
+        config_type: Type of configuration (e.g., "Claude Code", "Project")
+        config_path: Path to the configuration file
+    """
+    console.print(f"[dim]💡 {config_type} config: {config_path}[/dim]")