mcp-vector-search 0.15.7__py3-none-any.whl

mcp_vector_search/cli/suggestions.py

@@ -0,0 +1,375 @@
+"""Contextual suggestion system for better user experience."""
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+
+
+class ContextualSuggestionProvider:
+    """Provides context-aware suggestions based on project state and user workflow."""
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the suggestion provider.
+
+        Args:
+            project_root: Root directory of the project (defaults to current directory)
+        """
+        self.project_root = project_root or Path.cwd()
+        self.console = Console(stderr=True)
+
+    def get_project_state(self) -> dict[str, bool]:
+        """Analyze the current project state.
+
+        Returns:
+            Dictionary with boolean flags indicating project state
+        """
+        state = {
+            "is_initialized": False,
+            "has_index": False,
+            "has_config": False,
+            "has_recent_changes": False,
+            "is_git_repo": False,
+            "has_mcp_config": False,
+        }
+
+        try:
+            # Check if project is initialized
+            config_dir = self.project_root / ".mcp-vector-search"
+            state["is_initialized"] = config_dir.exists()
+
+            if state["is_initialized"]:
+                # Check for config
+                config_file = config_dir / "config.json"
+                state["has_config"] = config_file.exists()
+
+                # Check for index
+                index_dir = config_dir / "chroma_db"
+                state["has_index"] = index_dir.exists() and any(index_dir.iterdir())
+
+            # Check if it's a git repo
+            git_dir = self.project_root / ".git"
+            state["is_git_repo"] = git_dir.exists()
+
+            # Check for MCP configuration (Claude Desktop config)
+            home = Path.home()
+            claude_config = (
+                home
+                / "Library"
+                / "Application Support"
+                / "Claude"
+                / "claude_desktop_config.json"
+            )
+            if claude_config.exists():
+                try:
+                    with open(claude_config) as f:
+                        config_data = json.load(f)
+                        mcp_servers = config_data.get("mcpServers", {})
+                        state["has_mcp_config"] = "mcp-vector-search" in mcp_servers
+                except (OSError, json.JSONDecodeError):
+                    pass
+
+            # TODO: Check for recent file changes (would need file system monitoring)
+            # For now, we'll assume false
+            state["has_recent_changes"] = False
+
+        except Exception as e:
+            # If we can't determine state, provide conservative defaults
+            logger.debug(f"Failed to determine project state for suggestions: {e}")
+            pass
+
+        return state
+
+    def get_workflow_suggestions(self, failed_command: str) -> list[dict[str, str]]:
+        """Get workflow-based suggestions for a failed command.
+
+        Args:
+            failed_command: The command that failed
+
+        Returns:
+            List of suggestion dictionaries with 'command', 'reason', and 'priority'
+        """
+        suggestions = []
+        state = self.get_project_state()
+
+        # High priority suggestions based on project state
+        if not state["is_initialized"]:
+            suggestions.append(
+                {
+                    "command": "init",
+                    "reason": "Project is not initialized for vector search",
+                    "priority": "high",
+                    "description": "Set up the project configuration and create necessary directories",
+                }
+            )
+        elif not state["has_index"]:
+            suggestions.append(
+                {
+                    "command": "index",
+                    "reason": "No search index found - create one to enable searching",
+                    "priority": "high",
+                    "description": "Build the vector index for your codebase",
+                }
+            )
+
+        # Context-specific suggestions based on the failed command
+        if failed_command.lower() in ["search", "find", "query", "s", "f"]:
+            if not state["has_index"]:
+                suggestions.append(
+                    {
+                        "command": "index",
+                        "reason": "Cannot search without an index",
+                        "priority": "high",
+                        "description": "Build the search index first",
+                    }
+                )
+            else:
+                suggestions.extend(
+                    [
+                        {
+                            "command": "search",
+                            "reason": "Correct command for semantic code search",
+                            "priority": "high",
+                            "description": "Search your codebase semantically",
+                        },
+                        {
+                            "command": "interactive",
+                            "reason": "Try interactive search for better experience",
+                            "priority": "medium",
+                            "description": "Start an interactive search session",
+                        },
+                    ]
+                )
+
+        elif failed_command.lower() in ["index", "build", "scan", "i", "b"]:
+            suggestions.append(
+                {
+                    "command": "index",
+                    "reason": "Correct command for building search index",
+                    "priority": "high",
+                    "description": "Index your codebase for semantic search",
+                }
+            )
+
+        elif failed_command.lower() in ["status", "info", "stat", "st"]:
+            suggestions.append(
+                {
+                    "command": "status",
+                    "reason": "Show project status and statistics",
+                    "priority": "high",
+                    "description": "Display current project information",
+                }
+            )
+
+        elif failed_command.lower() in ["config", "configure", "settings", "c"]:
+            suggestions.append(
+                {
+                    "command": "config",
+                    "reason": "Manage project configuration",
+                    "priority": "high",
+                    "description": "View or modify project settings",
+                }
+            )
+
+        # MCP-related suggestions
+        if not state["has_mcp_config"] and failed_command.lower() in [
+            "mcp",
+            "claude",
+            "server",
+        ]:
+            suggestions.append(
+                {
+                    "command": "init-mcp",
+                    "reason": "Set up Claude Code MCP integration",
+                    "priority": "medium",
+                    "description": "Configure MCP server for Claude Code integration",
+                }
+            )
+
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_suggestions = []
+        for suggestion in suggestions:
+            key = suggestion["command"]
+            if key not in seen:
+                seen.add(key)
+                unique_suggestions.append(suggestion)
+
+        return unique_suggestions
+
+    def get_next_steps(self) -> list[dict[str, str]]:
+        """Get suggested next steps based on current project state.
+
+        Returns:
+            List of suggested next step dictionaries
+        """
+        state = self.get_project_state()
+        next_steps = []
+
+        if not state["is_initialized"]:
+            next_steps.append(
+                {
+                    "command": "init",
+                    "description": "Initialize the project for semantic search",
+                    "priority": "high",
+                }
+            )
+        elif not state["has_index"]:
+            next_steps.append(
+                {
+                    "command": "index",
+                    "description": "Build the search index for your codebase",
+                    "priority": "high",
+                }
+            )
+        else:
+            # Project is ready for use
+            next_steps.extend(
+                [
+                    {
+                        "command": 'search "your query here"',
+                        "description": "Search your codebase semantically",
+                        "priority": "high",
+                    },
+                    {
+                        "command": "status",
+                        "description": "Check project statistics and index health",
+                        "priority": "medium",
+                    },
+                ]
+            )
+
+            if state["has_recent_changes"]:
+                next_steps.insert(
+                    0,
+                    {
+                        "command": "index --force",
+                        "description": "Update the index with recent changes",
+                        "priority": "high",
+                    },
+                )
+
+        if not state["has_mcp_config"] and state["is_initialized"]:
+            next_steps.append(
+                {
+                    "command": "init-mcp",
+                    "description": "Set up Claude Code integration",
+                    "priority": "low",
+                }
+            )
+
+        return next_steps
+
+    def show_contextual_help(self, failed_command: str | None = None) -> None:
+        """Show contextual help and suggestions.
+
+        Args:
+            failed_command: The command that failed (if any)
+        """
+        if failed_command:
+            self.console.print(
+                f"\n[yellow]Command '{failed_command}' not recognized.[/yellow]"
+            )
+
+            suggestions = self.get_workflow_suggestions(failed_command)
+            if suggestions:
+                self.console.print(
+                    "\n[bold]Based on your project state, you might want to try:[/bold]"
+                )
+
+                for i, suggestion in enumerate(suggestions[:3], 1):  # Show top 3
+                    priority_color = {
+                        "high": "red",
+                        "medium": "yellow",
+                        "low": "dim",
+                    }.get(suggestion["priority"], "white")
+
+                    self.console.print(
+                        f"  [{priority_color}]{i}.[/{priority_color}] "
+                        f"[bold cyan]mcp-vector-search {suggestion['command']}[/bold cyan]"
+                    )
+                    self.console.print(f"     {suggestion['description']}")
+                    if suggestion.get("reason"):
+                        self.console.print(f"     [dim]({suggestion['reason']})[/dim]")
+        else:
+            # Show general next steps
+            next_steps = self.get_next_steps()
+            if next_steps:
+                self.console.print("\n[bold]Suggested next steps:[/bold]")
+
+                for i, step in enumerate(next_steps[:3], 1):
+                    priority_color = {
+                        "high": "green",
+                        "medium": "yellow",
+                        "low": "dim",
+                    }.get(step["priority"], "white")
+
+                    self.console.print(
+                        f"  [{priority_color}]{i}.[/{priority_color}] "
+                        f"[bold cyan]mcp-vector-search {step['command']}[/bold cyan]"
+                    )
+                    self.console.print(f"     {step['description']}")
+
+    def get_command_completion_suggestions(self, partial_command: str) -> list[str]:
+        """Get command completion suggestions for a partial command.
+
+        Args:
+            partial_command: Partial command string
+
+        Returns:
+            List of possible command completions
+        """
+        all_commands = [
+            "search",
+            "index",
+            "status",
+            "config",
+            "init",
+            "mcp",
+            "doctor",
+            "version",
+            "watch",
+            "auto-index",
+            "history",
+            "interactive",
+            "demo",
+            "install",
+            "reset",
+            "health",
+        ]
+
+        # Add common aliases and shortcuts
+        all_commands.extend(["s", "i", "st", "c", "f", "find"])
+
+        partial_lower = partial_command.lower()
+        matches = [cmd for cmd in all_commands if cmd.startswith(partial_lower)]
+
+        return sorted(matches)
+
+
+def get_contextual_suggestions(
+    project_root: Path | None = None, failed_command: str | None = None
+) -> None:
+    """Get and display contextual suggestions.
+
+    Args:
+        project_root: Root directory of the project
+        failed_command: The command that failed
+    """
+    provider = ContextualSuggestionProvider(project_root)
+    provider.show_contextual_help(failed_command)
+
+
+def suggest_workflow_commands(project_root: Path | None = None) -> list[str]:
+    """Get workflow command suggestions for the current project state.
+
+    Args:
+        project_root: Root directory of the project
+
+    Returns:
+        List of suggested commands in priority order
+    """
+    provider = ContextualSuggestionProvider(project_root)
+    next_steps = provider.get_next_steps()
+
+    return [step["command"] for step in next_steps]

mcp_vector_search/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration management for MCP Vector Search."""

mcp_vector_search/config/constants.py

@@ -0,0 +1,24 @@
+"""Project-wide constants for MCP Vector Search.
+
+This module contains all magic numbers and configuration constants
+used throughout the application to improve maintainability and clarity.
+"""
+
+# Timeout Constants (in seconds)
+SUBPROCESS_INSTALL_TIMEOUT = 120  # Timeout for package installation commands
+SUBPROCESS_SHORT_TIMEOUT = 10  # Short timeout for quick commands (version checks, etc.)
+SUBPROCESS_MCP_TIMEOUT = 30  # Timeout for MCP server operations
+SUBPROCESS_TEST_TIMEOUT = 5  # Timeout for server test operations
+CONNECTION_POOL_TIMEOUT = 30.0  # Connection pool acquisition timeout
+
+# Chunking Constants
+DEFAULT_CHUNK_SIZE = 50  # Default number of lines per code chunk
+TEXT_CHUNK_SIZE = 30  # Number of lines per text/markdown chunk
+SEARCH_RESULT_LIMIT = 20  # Default number of search results to return
+
+# Threshold Constants
+DEFAULT_SIMILARITY_THRESHOLD = 0.5  # Default similarity threshold for search (0.0-1.0)
+HIGH_SIMILARITY_THRESHOLD = 0.75  # Higher threshold for more precise matches
+
+# Cache Constants
+DEFAULT_CACHE_SIZE = 256  # Default LRU cache size for file reads

mcp_vector_search/config/defaults.py

@@ -0,0 +1,200 @@
+"""Default configurations for MCP Vector Search."""
+
+from pathlib import Path
+
+# Dotfiles that should NEVER be skipped (CI/CD configurations)
+ALLOWED_DOTFILES = {
+    ".github",  # GitHub workflows/actions
+    ".gitlab-ci",  # GitLab CI
+    ".circleci",  # CircleCI config
+}
+
+# Default file extensions to index (prioritize supported languages)
+DEFAULT_FILE_EXTENSIONS = [
+    ".py",  # Python (fully supported)
+    ".js",  # JavaScript (fully supported)
+    ".ts",  # TypeScript (fully supported)
+    ".jsx",  # React JSX (fully supported)
+    ".tsx",  # React TSX (fully supported)
+    ".mjs",  # ES6 modules (fully supported)
+    ".java",  # Java (fallback parsing)
+    ".cpp",  # C++ (fallback parsing)
+    ".c",  # C (fallback parsing)
+    ".h",  # C/C++ headers (fallback parsing)
+    ".hpp",  # C++ headers (fallback parsing)
+    ".cs",  # C# (fallback parsing)
+    ".go",  # Go (fallback parsing)
+    ".rs",  # Rust (fallback parsing)
+    ".php",  # PHP (fallback parsing)
+    ".rb",  # Ruby (fallback parsing)
+    ".swift",  # Swift (fallback parsing)
+    ".kt",  # Kotlin (fallback parsing)
+    ".scala",  # Scala (fallback parsing)
+    ".sh",  # Shell scripts (fallback parsing)
+    ".bash",  # Bash scripts (fallback parsing)
+    ".zsh",  # Zsh scripts (fallback parsing)
+    ".json",  # JSON configuration files
+    ".md",  # Markdown documentation
+    ".txt",  # Plain text files
+]
+
+# Language mappings for parsers
+LANGUAGE_MAPPINGS: dict[str, str] = {
+    ".py": "python",
+    ".pyw": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".java": "java",
+    ".cpp": "cpp",
+    ".c": "c",
+    ".h": "c",
+    ".hpp": "cpp",
+    ".cs": "c_sharp",
+    ".go": "go",
+    ".rs": "rust",
+    ".php": "php",
+    ".rb": "ruby",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".scala": "scala",
+    ".sh": "bash",
+    ".bash": "bash",
+    ".zsh": "bash",
+    ".json": "json",
+    ".md": "markdown",
+    ".txt": "text",
+}
+
+# Default embedding models by use case
+DEFAULT_EMBEDDING_MODELS = {
+    "code": "sentence-transformers/all-MiniLM-L6-v2",  # Changed from microsoft/codebert-base which doesn't exist
+    "multilingual": "sentence-transformers/all-MiniLM-L6-v2",
+    "fast": "sentence-transformers/all-MiniLM-L12-v2",
+    "precise": "sentence-transformers/all-mpnet-base-v2",  # Changed from microsoft/unixcoder-base
+}
+
+# Default similarity thresholds by language
+DEFAULT_SIMILARITY_THRESHOLDS = {
+    "python": 0.3,
+    "javascript": 0.3,
+    "typescript": 0.3,
+    "java": 0.3,
+    "cpp": 0.3,
+    "c": 0.3,
+    "go": 0.3,
+    "rust": 0.3,
+    "json": 0.4,  # JSON files may have more structural similarity
+    "markdown": 0.3,  # Markdown documentation
+    "text": 0.3,  # Plain text files
+    "default": 0.3,
+}
+
+# Default chunk sizes by language (in tokens)
+DEFAULT_CHUNK_SIZES = {
+    "python": 512,
+    "javascript": 384,
+    "typescript": 384,
+    "java": 512,
+    "cpp": 384,
+    "c": 384,
+    "go": 512,
+    "rust": 512,
+    "json": 256,  # JSON files are often smaller and more structured
+    "markdown": 512,  # Markdown documentation can be chunked normally
+    "text": 384,  # Plain text files with paragraph-based chunking
+    "default": 512,
+}
+
+# Directories to ignore during indexing
+DEFAULT_IGNORE_PATTERNS = [
+    ".git",
+    ".svn",
+    ".hg",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",  # mypy type checking cache
+    ".ruff_cache",  # ruff linter cache
+    "node_modules",
+    ".venv",
+    "venv",
+    ".env",
+    "build",
+    "dist",
+    "target",
+    ".idea",
+    ".vscode",
+    "*.egg-info",
+    ".DS_Store",
+    "Thumbs.db",
+    ".claude-mpm",  # Claude MPM directory
+    ".mcp-vector-search",  # Our own index directory
+]
+
+# File patterns to ignore
+DEFAULT_IGNORE_FILES = [
+    "*.pyc",
+    "*.pyo",
+    "*.pyd",
+    "*.so",
+    "*.dll",
+    "*.dylib",
+    "*.exe",
+    "*.bin",
+    "*.obj",
+    "*.o",
+    "*.a",
+    "*.lib",
+    "*.jar",
+    "*.war",
+    "*.ear",
+    "*.zip",
+    "*.tar",
+    "*.gz",
+    "*.bz2",
+    "*.xz",
+    "*.7z",
+    "*.rar",
+    "*.iso",
+    "*.dmg",
+    "*.img",
+    "*.log",
+    "*.tmp",
+    "*.temp",
+    "*.cache",
+    "*.lock",
+]
+
+
+def get_default_config_path(project_root: Path) -> Path:
+    """Get the default configuration file path for a project."""
+    return project_root / ".mcp-vector-search" / "config.json"
+
+
+def get_default_index_path(project_root: Path) -> Path:
+    """Get the default index directory path for a project."""
+    return project_root / ".mcp-vector-search"
+
+
+def get_default_cache_path(project_root: Path) -> Path:
+    """Get the default cache directory path for a project."""
+    return project_root / ".mcp-vector-search" / "cache"
+
+
+def get_language_from_extension(extension: str) -> str:
+    """Get the language name from file extension."""
+    return LANGUAGE_MAPPINGS.get(extension.lower(), "text")
+
+
+def get_similarity_threshold(language: str) -> float:
+    """Get the default similarity threshold for a language."""
+    return DEFAULT_SIMILARITY_THRESHOLDS.get(
+        language.lower(), DEFAULT_SIMILARITY_THRESHOLDS["default"]
+    )
+
+
+def get_chunk_size(language: str) -> int:
+    """Get the default chunk size for a language."""
+    return DEFAULT_CHUNK_SIZES.get(language.lower(), DEFAULT_CHUNK_SIZES["default"])