mcp-vector-search 0.12.6__py3-none-any.whl → 1.0.3__py3-none-any.whl

mcp_vector_search/core/models.py

@@ -147,6 +147,9 @@ class SearchResult(BaseModel):
     context_before: list[str] = Field(default=[], description="Lines before the match")
     context_after: list[str] = Field(default=[], description="Lines after the match")
     highlights: list[str] = Field(default=[], description="Highlighted terms")
+    file_missing: bool = Field(
+        default=False, description="True if file no longer exists (stale index)"
+    )
 
     class Config:
         arbitrary_types_allowed = True

mcp_vector_search/core/project.py

@@ -107,6 +107,23 @@ class ProjectManager:
             index_path = get_default_index_path(self.project_root)
             index_path.mkdir(parents=True, exist_ok=True)
 
+            # Ensure .mcp-vector-search/ is in .gitignore
+            # This is a non-critical operation - failures are logged but don't block initialization
+            try:
+                from ..utils.gitignore_updater import ensure_gitignore_entry
+
+                ensure_gitignore_entry(
+                    self.project_root,
+                    pattern=".mcp-vector-search/",
+                    comment="MCP Vector Search index directory",
+                )
+            except Exception as e:
+                # Log warning but continue initialization
+                logger.warning(f"Could not update .gitignore: {e}")
+                logger.info(
+                    "Please manually add '.mcp-vector-search/' to your .gitignore file"
+                )
+
             # Detect languages and files
             detected_languages = self.detect_languages()
             file_count = self.count_indexable_files(

mcp_vector_search/core/scheduler.py

@@ -73,7 +73,7 @@ class SchedulerManager:
             project_root = str(self.project_root)
 
             # Create wrapper script
-            script_content = f'''#!/bin/bash
+            script_content = f"""#!/bin/bash
 # MCP Vector Search Auto-Reindex - {task_name}
 cd "{project_root}" || exit 1
 
@@ -85,7 +85,7 @@ elif [ -f "{python_path}" ]; then
 else
     python3 -m mcp_vector_search auto-index check --auto-reindex --max-files 10
 fi
-'''
+"""
 
             # Write script to temp file
             script_dir = Path.home() / ".mcp-vector-search" / "scripts"
@@ -109,7 +109,7 @@ fi
 
             # Get current crontab
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B607
                     ["crontab", "-l"], capture_output=True, text=True, check=True
                 )
                 current_crontab = result.stdout
@@ -125,7 +125,7 @@ fi
             new_crontab = current_crontab + cron_entry
 
             # Install new crontab
-            process = subprocess.Popen(
+            process = subprocess.Popen(  # nosec B607
                 ["crontab", "-"], stdin=subprocess.PIPE, text=True
             )
             process.communicate(input=new_crontab)
@@ -148,7 +148,7 @@ fi
         try:
             # Get current crontab
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B607
                     ["crontab", "-l"], capture_output=True, text=True, check=True
                 )
                 current_crontab = result.stdout
@@ -163,13 +163,13 @@ fi
 
             # Install new crontab
             if new_crontab.strip():
-                process = subprocess.Popen(
+                process = subprocess.Popen(  # nosec B607
                     ["crontab", "-"], stdin=subprocess.PIPE, text=True
                 )
                 process.communicate(input=new_crontab)
             else:
                 # Remove crontab entirely if empty
-                subprocess.run(["crontab", "-r"], check=False)
+                subprocess.run(["crontab", "-r"], check=False)  # nosec B607
 
             # Remove script file
             script_dir = Path.home() / ".mcp-vector-search" / "scripts"
@@ -191,7 +191,7 @@ fi
             project_root = str(self.project_root)
 
             # Create PowerShell script
-            script_content = f'''# MCP Vector Search Auto-Reindex - {task_name}
+            script_content = f"""# MCP Vector Search Auto-Reindex - {task_name}
 Set-Location "{project_root}"
 
 try {{
@@ -205,7 +205,7 @@ try {{
 }} catch {{
     # Silently ignore errors
 }}
-'''
+"""
 
             # Write script
             script_dir = Path.home() / ".mcp-vector-search" / "scripts"
@@ -302,7 +302,7 @@ try {{
     def _get_cron_status(self, task_name: str) -> dict:
         """Get cron job status."""
         try:
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B607
                 ["crontab", "-l"], capture_output=True, text=True, check=True
             )
 
@@ -315,7 +315,7 @@ try {{
     def _get_windows_task_status(self, task_name: str) -> dict:
         """Get Windows task status."""
         try:
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B607
                 ["schtasks", "/query", "/tn", task_name], capture_output=True, text=True
             )
 

mcp_vector_search/core/search.py

@@ -1,5 +1,6 @@
 """Semantic search engine for MCP Vector Search."""
 
+import asyncio
 import re
 import time
 from collections import OrderedDict
@@ -11,8 +12,9 @@ from loguru import logger
 
 from ..config.constants import DEFAULT_CACHE_SIZE
 from .auto_indexer import AutoIndexer, SearchTriggeredIndexer
+from .boilerplate import BoilerplateFilter
 from .database import VectorDatabase
-from .exceptions import SearchError
+from .exceptions import RustPanicError, SearchError
 from .models import SearchResult
 
 
@@ -67,6 +69,7 @@ class SemanticSearchEngine:
     _BOOST_SHALLOW_PATH = 0.02
     _PENALTY_TEST_FILE = -0.02
     _PENALTY_DEEP_PATH = -0.01
+    _PENALTY_BOILERPLATE = -0.15
 
     def __init__(
         self,
@@ -106,6 +109,156 @@ class SemanticSearchEngine:
         self._last_health_check: float = 0.0
         self._health_check_interval: float = 60.0
 
+        # Boilerplate filter for smart result ranking
+        self._boilerplate_filter = BoilerplateFilter()
+
+    @staticmethod
+    def _is_rust_panic_error(error: Exception) -> bool:
+        """Detect ChromaDB Rust panic errors.
+
+        Args:
+            error: Exception to check
+
+        Returns:
+            True if this is a Rust panic error
+        """
+        error_msg = str(error).lower()
+
+        # Check for the specific Rust panic pattern
+        # "range start index X out of range for slice of length Y"
+        if "range start index" in error_msg and "out of range" in error_msg:
+            return True
+
+        # Check for other Rust panic indicators
+        rust_panic_patterns = [
+            "rust panic",
+            "pyo3_runtime.panicexception",
+            "thread 'tokio-runtime-worker' panicked",
+            "rust/sqlite/src/db.rs",  # Specific to the known ChromaDB issue
+        ]
+
+        return any(pattern in error_msg for pattern in rust_panic_patterns)
+
+    @staticmethod
+    def _is_corruption_error(error: Exception) -> bool:
+        """Detect index corruption errors.
+
+        Args:
+            error: Exception to check
+
+        Returns:
+            True if this is a corruption error
+        """
+        error_msg = str(error).lower()
+
+        corruption_indicators = [
+            "pickle",
+            "unpickling",
+            "eof",
+            "ran out of input",
+            "hnsw",
+            "deserialize",
+            "corrupt",
+        ]
+
+        return any(indicator in error_msg for indicator in corruption_indicators)
+
+    async def _search_with_retry(
+        self,
+        query: str,
+        limit: int,
+        filters: dict[str, Any] | None,
+        threshold: float,
+        max_retries: int = 3,
+    ) -> list[SearchResult]:
+        """Execute search with retry logic and exponential backoff.
+
+        Args:
+            query: Processed search query
+            limit: Maximum number of results
+            filters: Optional filters
+            threshold: Similarity threshold
+            max_retries: Maximum retry attempts (default: 3)
+
+        Returns:
+            List of search results
+
+        Raises:
+            RustPanicError: If Rust panic persists after retries
+            SearchError: If search fails for other reasons
+        """
+        last_error = None
+        backoff_delays = [0, 0.1, 0.5]  # Immediate, 100ms, 500ms
+
+        for attempt in range(max_retries):
+            try:
+                # Add delay for retries (exponential backoff)
+                if attempt > 0 and backoff_delays[attempt] > 0:
+                    await asyncio.sleep(backoff_delays[attempt])
+                    logger.debug(
+                        f"Retrying search after {backoff_delays[attempt]}s delay (attempt {attempt + 1}/{max_retries})"
+                    )
+
+                # Perform the actual search
+                results = await self.database.search(
+                    query=query,
+                    limit=limit,
+                    filters=filters,
+                    similarity_threshold=threshold,
+                )
+
+                # Success! If we had retries, log that we recovered
+                if attempt > 0:
+                    logger.info(
+                        f"Search succeeded after {attempt + 1} attempts (recovered from transient error)"
+                    )
+
+                return results
+
+            except BaseException as e:
+                # Re-raise system exceptions we should never catch
+                if isinstance(e, (KeyboardInterrupt, SystemExit, GeneratorExit)):
+                    raise
+
+                last_error = e
+
+                # Check if this is a Rust panic
+                if self._is_rust_panic_error(e):
+                    logger.warning(
+                        f"ChromaDB Rust panic detected (attempt {attempt + 1}/{max_retries}): {e}"
+                    )
+
+                    # If this is the last retry, escalate to corruption recovery
+                    if attempt == max_retries - 1:
+                        logger.error(
+                            "Rust panic persisted after all retries - index may be corrupted"
+                        )
+                        raise RustPanicError(
+                            "ChromaDB Rust panic detected. The HNSW index may be corrupted. "
+                            "Please run 'mcp-vector-search reset' followed by 'mcp-vector-search index' to rebuild."
+                        ) from e
+
+                    # Otherwise, continue to next retry
+                    continue
+
+                # Check for general corruption
+                elif self._is_corruption_error(e):
+                    logger.error(f"Index corruption detected: {e}")
+                    raise SearchError(
+                        "Index corruption detected. Please run 'mcp-vector-search reset' "
+                        "followed by 'mcp-vector-search index' to rebuild."
+                    ) from e
+
+                # Some other error - don't retry, just fail
+                else:
+                    logger.error(f"Search failed: {e}")
+                    raise SearchError(f"Search failed: {e}") from e
+
+        # Should never reach here, but just in case
+        raise SearchError(
+            f"Search failed after {max_retries} retries: {last_error}"
+        ) from last_error
+
     async def search(
         self,
         query: str,
@@ -162,12 +315,12 @@ class SemanticSearchEngine:
             # Preprocess query
             processed_query = self._preprocess_query(query)
 
-            # Perform vector search
-            results = await self.database.search(
+            # Perform vector search with retry logic
+            results = await self._search_with_retry(
                 query=processed_query,
                 limit=limit,
                 filters=filters,
-                similarity_threshold=threshold,
+                threshold=threshold,
             )
 
             # Post-process results
@@ -184,32 +337,13 @@ class SemanticSearchEngine:
             )
             return ranked_results
 
+        except (RustPanicError, SearchError):
+            # These errors are already properly formatted with user guidance
+            raise
         except Exception as e:
-            error_msg = str(e).lower()
-            # Check for corruption indicators
-            if any(
-                indicator in error_msg
-                for indicator in [
-                    "pickle",
-                    "unpickling",
-                    "eof",
-                    "ran out of input",
-                    "hnsw",
-                    "index",
-                    "deserialize",
-                    "corrupt",
-                ]
-            ):
-                logger.error(f"Index corruption detected during search: {e}")
-                logger.info(
-                    "The index appears to be corrupted. Please run 'mcp-vector-search reset' to clear the index and then 'mcp-vector-search index' to rebuild it."
-                )
-                raise SearchError(
-                    "Index corruption detected. Please run 'mcp-vector-search reset' followed by 'mcp-vector-search index' to rebuild."
-                ) from e
-            else:
-                logger.error(f"Search failed for query '{query}': {e}")
-                raise SearchError(f"Search failed: {e}") from e
+            # Unexpected error - wrap it in SearchError
+            logger.error(f"Unexpected search error for query '{query}': {e}")
+            raise SearchError(f"Search failed: {e}") from e
 
     async def search_similar(
         self,
@@ -470,6 +604,11 @@ class SemanticSearchEngine:
             result.context_before = context_before
             result.context_after = context_after
 
+        except FileNotFoundError:
+            # File was deleted since indexing - silently skip context
+            # This is normal when index is stale; use --force to reindex
+            logger.debug(f"File no longer exists (stale index): {result.file_path}")
+            result.file_missing = True  # Mark for potential filtering
         except Exception as e:
             logger.warning(f"Failed to get context for {result.file_path}: {e}")
 
@@ -562,6 +701,17 @@ class SemanticSearchEngine:
             elif path_depth > 5:
                 score += self._PENALTY_DEEP_PATH
 
+            # Factor 7: Boilerplate penalty (penalize common boilerplate patterns)
+            # Apply penalty to function names (constructors, lifecycle methods, etc.)
+            if result.function_name:
+                boilerplate_penalty = self._boilerplate_filter.get_penalty(
+                    name=result.function_name,
+                    language=result.language,
+                    query=query,
+                    penalty=self._PENALTY_BOILERPLATE,
+                )
+                score += boilerplate_penalty
+
             # Ensure score doesn't exceed 1.0
             result.similarity_score = min(1.0, score)
 

mcp_vector_search/mcp/server.py

@@ -38,11 +38,28 @@ class MCPVectorSearchServer:
         """Initialize the MCP server.
 
         Args:
-            project_root: Project root directory. If None, will auto-detect.
+            project_root: Project root directory. If None, will auto-detect from:
+                         1. PROJECT_ROOT or MCP_PROJECT_ROOT environment variable
+                         2. Current working directory
             enable_file_watching: Enable file watching for automatic reindexing.
                                   If None, checks MCP_ENABLE_FILE_WATCHING env var (default: True).
         """
-        self.project_root = project_root or Path.cwd()
+        # Auto-detect project root from environment or current directory
+        if project_root is None:
+            # Priority 1: MCP_PROJECT_ROOT (new standard)
+            # Priority 2: PROJECT_ROOT (legacy)
+            # Priority 3: Current working directory
+            env_project_root = os.getenv("MCP_PROJECT_ROOT") or os.getenv(
+                "PROJECT_ROOT"
+            )
+            if env_project_root:
+                project_root = Path(env_project_root).resolve()
+                logger.info(f"Using project root from environment: {project_root}")
+            else:
+                project_root = Path.cwd()
+                logger.info(f"Using current directory as project root: {project_root}")
+
+        self.project_root = project_root
         self.project_manager = ProjectManager(self.project_root)
         self.search_engine: SemanticSearchEngine | None = None
         self.file_watcher: FileWatcher | None = None
@@ -397,9 +414,11 @@ class MCPVectorSearchServer:
                     "languages": config.languages,
                     "total_chunks": stats.total_chunks,
                     "total_files": stats.total_files,
-                    "index_size": f"{stats.index_size_mb:.2f} MB"
-                    if hasattr(stats, "index_size_mb")
-                    else "Unknown",
+                    "index_size": (
+                        f"{stats.index_size_mb:.2f} MB"
+                        if hasattr(stats, "index_size_mb")
+                        else "Unknown"
+                    ),
                 }
             else:
                 status_info = {

mcp_vector_search/utils/__init__.py

@@ -6,6 +6,7 @@ from .gitignore import (
     create_gitignore_parser,
     is_path_gitignored,
 )
+from .gitignore_updater import ensure_gitignore_entry
 from .timing import (
     PerformanceProfiler,
     SearchProfiler,
@@ -24,6 +25,7 @@ __all__ = [
     "GitignorePattern",
     "create_gitignore_parser",
     "is_path_gitignored",
+    "ensure_gitignore_entry",
     # Timing utilities
     "PerformanceProfiler",
     "TimingResult",

mcp_vector_search/utils/gitignore_updater.py

@@ -0,0 +1,212 @@
+"""Gitignore file update utilities for automatic .gitignore entry management."""
+
+from pathlib import Path
+
+from loguru import logger
+
+
+def ensure_gitignore_entry(
+    project_root: Path,
+    pattern: str = ".mcp-vector-search/",
+    comment: str | None = "MCP Vector Search index directory",
+    create_if_missing: bool = True,
+) -> bool:
+    """Ensure a pattern exists in .gitignore file.
+
+    This function safely adds a pattern to .gitignore if it doesn't already exist.
+    It handles various edge cases including:
+    - Non-existent .gitignore files (creates if in git repo)
+    - Empty .gitignore files
+    - Existing patterns in various formats
+    - Negation patterns (conflict detection)
+    - Permission errors
+    - Encoding issues
+
+    Design Decision: Non-Blocking Operation
+    ----------------------------------------
+    This function is designed to be non-critical and non-blocking. It will:
+    - NEVER raise exceptions (returns False on errors)
+    - Log warnings for failures instead of blocking
+    - Allow project initialization to continue even if gitignore update fails
+
+    Rationale: .gitignore updates are a quality-of-life improvement, not a
+    requirement for mcp-vector-search functionality. Users can manually add
+    the entry if automatic update fails.
+
+    Pattern Detection Strategy
+    --------------------------
+    The function checks for semantic equivalents of the pattern:
+    - `.mcp-vector-search/` (exact match)
+    - `.mcp-vector-search` (without trailing slash)
+    - `.mcp-vector-search/*` (with wildcard)
+    - `/.mcp-vector-search/` (root-relative)
+
+    All are treated as equivalent to avoid duplicate entries.
+
+    Edge Cases Handled
+    ------------------
+    1. .gitignore does not exist -> Create (if in git repo)
+    2. .gitignore is empty -> Add pattern
+    3. Pattern already exists -> Skip (log debug)
+    4. Similar pattern exists -> Skip (log debug)
+    5. Negation pattern exists -> Warn and skip (respects user intent)
+    6. Not a git repository -> Skip (no .gitignore needed)
+    7. Permission denied -> Warn and skip (log manual instructions)
+    8. Encoding errors -> Try fallback encoding
+    9. Missing parent directory -> Should not occur (project_root exists)
+    10. Concurrent modification -> Safe (append operation is atomic-ish)
+
+    Args:
+        project_root: Project root directory (must exist)
+        pattern: Pattern to add to .gitignore (default: .mcp-vector-search/)
+        comment: Optional comment to add before the pattern
+        create_if_missing: Create .gitignore if it doesn't exist (default: True)
+
+    Returns:
+        True if pattern was added or already exists, False on error
+
+    Performance:
+        - Time Complexity: O(n) where n = lines in .gitignore (typically <1000)
+        - Space Complexity: O(n) for reading file into memory
+        - Expected Runtime: <10ms for typical .gitignore files
+
+    Notes:
+        - Only creates .gitignore in git repositories (checks for .git directory)
+        - Preserves existing file structure and encoding (UTF-8)
+        - Handles negation patterns gracefully (warns but doesn't override)
+        - Non-blocking: logs warnings instead of raising exceptions
+
+    Examples:
+        >>> # Basic usage during project initialization
+        >>> ensure_gitignore_entry(Path("/path/to/project"))
+        True
+
+        >>> # Custom pattern with custom comment
+        >>> ensure_gitignore_entry(
+        ...     Path("/path/to/project"),
+        ...     pattern=".custom-dir/",
+        ...     comment="Custom tool directory"
+        ... )
+        True
+
+        >>> # Don't create .gitignore if missing
+        >>> ensure_gitignore_entry(
+        ...     Path("/path/to/project"),
+        ...     create_if_missing=False
+        ... )
+        False
+    """
+    gitignore_path = project_root / ".gitignore"
+
+    # Edge Case 1: Check if this is a git repository
+    # Only create/modify .gitignore in git repositories to avoid polluting non-git projects
+    git_dir = project_root / ".git"
+    if not git_dir.exists():
+        logger.debug(
+            "Not a git repository (no .git directory), skipping .gitignore update"
+        )
+        return False
+
+    try:
+        # Edge Case 2: Handle non-existent .gitignore
+        if not gitignore_path.exists():
+            if not create_if_missing:
+                logger.debug(".gitignore does not exist and create_if_missing=False")
+                return False
+
+            # Create new .gitignore with the pattern
+            content = f"# {comment}\n{pattern}\n" if comment else f"{pattern}\n"
+            gitignore_path.write_text(content, encoding="utf-8")
+            logger.info(f"Created .gitignore with {pattern} entry")
+            return True
+
+        # Read existing content with UTF-8 encoding
+        try:
+            content = gitignore_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            # Edge Case 8: Fallback to more lenient encoding
+            logger.debug("UTF-8 decode failed, trying with error replacement")
+            try:
+                content = gitignore_path.read_text(encoding="utf-8", errors="replace")
+            except Exception as e:
+                logger.warning(
+                    f"Failed to read .gitignore due to encoding error: {e}. "
+                    f"Please manually add '{pattern}' to your .gitignore"
+                )
+                return False
+
+        # Edge Case 3: Handle empty .gitignore
+        stripped_content = content.strip()
+        if not stripped_content:
+            content = f"# {comment}\n{pattern}\n" if comment else f"{pattern}\n"
+            gitignore_path.write_text(content, encoding="utf-8")
+            logger.info(f"Added {pattern} to empty .gitignore")
+            return True
+
+        # Check for existing patterns (Edge Cases 4, 5, 6)
+        lines = content.split("\n")
+        normalized_pattern = pattern.rstrip("/").lstrip("/")
+
+        for line in lines:
+            # Skip comments and empty lines
+            stripped_line = line.strip()
+            if not stripped_line or stripped_line.startswith("#"):
+                continue
+
+            # Edge Case 6: Check for negation pattern (conflict)
+            # Negation patterns indicate explicit user intent to track the directory
+            if stripped_line.startswith("!") and normalized_pattern in stripped_line:
+                logger.warning(
+                    f".gitignore contains negation pattern: {stripped_line}. "
+                    "This indicates you want to track .mcp-vector-search/ in git. "
+                    "Skipping automatic entry to respect your configuration."
+                )
+                return False
+
+            # Normalize line for comparison
+            normalized_line = stripped_line.rstrip("/").lstrip("/")
+
+            # Edge Cases 4 & 5: Check for exact or similar matches
+            # These patterns are semantically equivalent for .gitignore:
+            # - .mcp-vector-search/
+            # - .mcp-vector-search
+            # - .mcp-vector-search/*
+            # - /.mcp-vector-search/
+            if (
+                normalized_line == normalized_pattern
+                or normalized_line == normalized_pattern + "/*"
+            ):
+                logger.debug(f"Pattern already exists in .gitignore: {stripped_line}")
+                return True
+
+        # Pattern doesn't exist, add it
+        # Preserve file structure: ensure proper newline handling
+        if not content.endswith("\n"):
+            content += "\n"
+
+        # Add blank line before comment for visual separation
+        content += "\n"
+
+        if comment:
+            content += f"# {comment}\n"
+        content += f"{pattern}\n"
+
+        # Write back to file
+        gitignore_path.write_text(content, encoding="utf-8")
+        logger.info(f"Added {pattern} to .gitignore")
+        return True
+
+    except PermissionError:
+        # Edge Case 7: Handle read-only .gitignore or protected directory
+        logger.warning(
+            f"Cannot update .gitignore: Permission denied. "
+            f"Please manually add '{pattern}' to your .gitignore file at {gitignore_path}"
+        )
+        return False
+    except Exception as e:
+        # Catch-all for unexpected errors (don't block initialization)
+        logger.warning(
+            f"Failed to update .gitignore: {e}. "
+            f"Please manually add '{pattern}' to your .gitignore"
+        )
+        return False