hanzo-mcp 0.8.11__py3-none-any.whl → 0.9.0__py3-none-any.whl

hanzo_mcp/tools/filesystem/find.py

@@ -1,9 +1,10 @@
 """Unified find tool implementation.
 
-This module provides the FindTool for finding text patterns in files using
+This module provides the FindTool for finding files by name or content using
 multiple search backends in order of preference: rg > ag > ack > grep.
 """
 
+import os
 import re
 import json
 import shutil
@@ -17,6 +18,7 @@ from typing import (
     TypedDict,
     final,
     override,
+    Literal,
 )
 from pathlib import Path
 
@@ -25,11 +27,17 @@ from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
 
+try:
+    import ffind
+    FFIND_AVAILABLE = True
+except ImportError:
+    FFIND_AVAILABLE = False
+
 # Parameter types
 Pattern = Annotated[
     str,
     Field(
-        description="Pattern to search for (regex or literal)",
+        description="Pattern to search for (file name pattern or content regex/literal)",
         min_length=1,
     ),
 ]
@@ -42,10 +50,18 @@ SearchPath = Annotated[
     ),
 ]
 
+Mode = Annotated[
+    Literal["name", "content", "both"],
+    Field(
+        description="Search mode: 'name' for file names, 'content' for file contents, 'both' for both",
+        default="name",
+    ),
+]
+
 Include = Annotated[
     Optional[str],
     Field(
-        description='File pattern to include (e.g. "*.js")',
+        description='File pattern to include (e.g. "*.js", "*.{ts,tsx}")',
         default=None,
     ),
 ]
@@ -62,30 +78,22 @@ CaseSensitive = Annotated[
     bool,
     Field(
         description="Case sensitive search",
-        default=True,
-    ),
-]
-
-FixedStrings = Annotated[
-    bool,
-    Field(
-        description="Treat pattern as literal string, not regex",
         default=False,
     ),
 ]
 
-ShowContext = Annotated[
-    int,
+Recursive = Annotated[
+    bool,
     Field(
-        description="Lines of context to show around matches",
-        default=0,
+        description="Search recursively in subdirectories",
+        default=True,
     ),
 ]
 
-Backend = Annotated[
-    Optional[str],
+MaxResults = Annotated[
+    Optional[int],
     Field(
-        description="Force specific backend: rg, ag, ack, grep",
+        description="Maximum number of results to return",
         default=None,
     ),
 ]
@@ -96,17 +104,17 @@ class FindParams(TypedDict, total=False):
 
     pattern: str
     path: str
+    mode: Literal["name", "content", "both"]
     include: Optional[str]
     exclude: Optional[str]
     case_sensitive: bool
-    fixed_strings: bool
-    show_context: int
-    backend: Optional[str]
+    recursive: bool
+    max_results: Optional[int]
 
 
 @final
 class FindTool(FilesystemBaseTool):
-    """Unified find tool with multiple backend support."""
+    """Unified find tool for searching by file name or content."""
 
     def __init__(self, permission_manager):
         """Initialize the find tool."""
@@ -125,17 +133,24 @@ class FindTool(FilesystemBaseTool):
     def description(self) -> str:
         """Get the tool description."""
         backends = self._get_available_backends()
-        backend_str = ", ".join(backends) if backends else "fallback grep"
+        backend_str = ", ".join(backends) if backends else "fallback search"
+
+        return f"""Find files by name, content, or both. Available backends: {backend_str}.
+
+Examples:
+# Find by file name (default mode)
+find "*.py" 
+find "test_*" ./src
+find "README.*" --case-sensitive
 
-        return f"""Find pattern in files (like ffind). Available: {backend_str}.
+# Find by content 
+find "TODO" --mode content
+find "error.*fatal" ./src --mode content
 
-Usage:
-find "TODO"
-find "error.*fatal" ./src
-find "config" --include "*.json"
-find "password" --exclude "*.log"
+# Find both name and content
+find "config" --mode both --include "*.json"
 
-Fast, intuitive file content search."""
+Supports wildcards for names, regex for content."""
 
     def _get_available_backends(self) -> List[str]:
         """Get list of available search backends."""
@@ -161,12 +176,15 @@ Fast, intuitive file content search."""
             return "Error: pattern is required"
 
         path = params.get("path", ".")
+        mode = params.get("mode", "name")
         include = params.get("include")
         exclude = params.get("exclude")
-        case_sensitive = params.get("case_sensitive", True)
-        fixed_strings = params.get("fixed_strings", False)
-        show_context = params.get("show_context", 0)
-        backend = params.get("backend")
+        case_sensitive = params.get("case_sensitive", False)
+        recursive = params.get("recursive", True)
+        max_results = params.get("max_results")
+
+        # Expand path (handles ~, $HOME, etc.)
+        path = self.expand_path(path)
 
         # Validate path
         path_validation = self.validate_path(path)
@@ -184,95 +202,154 @@ Fast, intuitive file content search."""
         if not exists:
             return error_msg
 
-        # Select backend
-        available = self._get_available_backends()
+        await tool_ctx.info(f"Searching for '{pattern}' in {path} (mode: {mode})")
 
-        if backend:
-            # User specified backend
-            if backend not in available and backend != "grep":
-                return f"Error: Backend '{backend}' not available. Available: {', '.join(available + ['grep'])}"
-            selected_backend = backend
-        elif available:
-            # Use first available
-            selected_backend = available[0]
+        # Route to appropriate search method
+        if mode == "name":
+            return await self._find_by_name(
+                pattern, path, include, exclude, case_sensitive, recursive, max_results, tool_ctx
+            )
+        elif mode == "content":
+            return await self._find_by_content(
+                pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
+            )
+        elif mode == "both":
+            return await self._find_both(
+                pattern, path, include, exclude, case_sensitive, recursive, max_results, tool_ctx
+            )
         else:
-            # Fallback
-            selected_backend = "grep"
+            return f"Error: Invalid mode '{mode}'. Use 'name', 'content', or 'both'."
 
-        await tool_ctx.info(
-            f"Using {selected_backend} to search for '{pattern}' in {path}"
-        )
+    async def _find_by_name(
+        self, pattern, path, include, exclude, case_sensitive, recursive, max_results, tool_ctx
+    ) -> str:
+        """Find files by name pattern."""
+        search_path = path or os.getcwd()
+        
+        # If ffind is not available, fall back to basic implementation
+        if not FFIND_AVAILABLE:
+            return await self._find_files_fallback(
+                pattern, search_path, recursive, not case_sensitive, False, False, True, max_results or 100
+            )
+
+        try:
+            # Use ffind for efficient searching
+            results = []
+            count = 0
+
+            # Configure ffind options
+            options = {
+                "pattern": pattern,
+                "path": search_path,
+                "recursive": recursive,
+                "ignore_case": not case_sensitive,
+                "hidden": False,
+            }
+
+            # Search with ffind
+            for filepath in ffind.find(**options):
+                # Check if it matches our include/exclude criteria
+                filename = os.path.basename(filepath)
+                if not self._match_file_pattern(filename, include, exclude):
+                    continue
+
+                # Make path relative for cleaner output
+                try:
+                    rel_path = os.path.relpath(filepath, search_path)
+                except ValueError:
+                    rel_path = filepath
+
+                results.append(rel_path)
+                count += 1
+
+                if max_results and count >= max_results:
+                    break
+
+            if not results:
+                return f"No files found matching '{pattern}'"
+
+            # Format output
+            output = [f"Found {len(results)} file(s) matching '{pattern}':"]
+            output.append("")
+
+            for filepath in sorted(results):
+                output.append(filepath)
+
+            if max_results and count >= max_results:
+                output.append(f"\n... (showing first {max_results} results)")
+
+            return "\n".join(output)
+
+        except Exception as e:
+            await tool_ctx.error(f"Error during name search: {str(e)}")
+            # Fall back to basic implementation
+            return await self._find_files_fallback(
+                pattern, search_path, recursive, not case_sensitive, False, False, True, max_results or 100
+            )
+
+    async def _find_by_content(
+        self, pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
+    ) -> str:
+        """Find files by content pattern."""
+        # Select backend for content search
+        available = self._get_available_backends()
+        selected_backend = available[0] if available else "grep"
+
+        await tool_ctx.info(f"Using {selected_backend} for content search")
 
-        # Execute search
+        # Execute content search
         if selected_backend == "rg":
-            return await self._run_ripgrep(
-                pattern,
-                path,
-                include,
-                exclude,
-                case_sensitive,
-                fixed_strings,
-                show_context,
-                tool_ctx,
+            return await self._run_ripgrep_content(
+                pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
             )
         elif selected_backend == "ag":
-            return await self._run_silver_searcher(
-                pattern,
-                path,
-                include,
-                exclude,
-                case_sensitive,
-                fixed_strings,
-                show_context,
-                tool_ctx,
+            return await self._run_silver_searcher_content(
+                pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
             )
         elif selected_backend == "ack":
-            return await self._run_ack(
-                pattern,
-                path,
-                include,
-                exclude,
-                case_sensitive,
-                fixed_strings,
-                show_context,
-                tool_ctx,
+            return await self._run_ack_content(
+                pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
             )
         else:
-            return await self._run_fallback_grep(
-                pattern,
-                path,
-                include,
-                exclude,
-                case_sensitive,
-                fixed_strings,
-                show_context,
-                tool_ctx,
+            return await self._run_fallback_grep_content(
+                pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
             )
 
-    async def _run_ripgrep(
-        self,
-        pattern,
-        path,
-        include,
-        exclude,
-        case_sensitive,
-        fixed_strings,
-        show_context,
-        tool_ctx,
+    async def _find_both(
+        self, pattern, path, include, exclude, case_sensitive, recursive, max_results, tool_ctx
     ) -> str:
-        """Run ripgrep backend."""
+        """Find files by both name and content."""
+        # Run both searches
+        name_results = await self._find_by_name(
+            pattern, path, include, exclude, case_sensitive, recursive, max_results, tool_ctx
+        )
+        content_results = await self._find_by_content(
+            pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
+        )
+
+        # Combine results
+        output = ["=== NAME MATCHES ==="]
+        output.append(name_results)
+        output.append("")
+        output.append("=== CONTENT MATCHES ===")
+        output.append(content_results)
+
+        return "\n".join(output)
+
+    async def _run_ripgrep_content(
+        self, pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
+    ) -> str:
+        """Run ripgrep backend for content search."""
         cmd = ["rg", "--json"]
 
         if not case_sensitive:
             cmd.append("-i")
-        if fixed_strings:
-            cmd.append("-F")
-        if show_context > 0:
-            cmd.extend(["-C", str(show_context)])
         if include:
             cmd.extend(["-g", include])
         if exclude:
             cmd.extend(["-g", f"!{exclude}"])
+        if max_results:
+            cmd.extend(["-m", str(max_results)])
 
         cmd.extend([pattern, path])
 
@@ -293,30 +370,20 @@ Fast, intuitive file content search."""
             await tool_ctx.error(f"Error running ripgrep: {str(e)}")
             return f"Error running ripgrep: {str(e)}"
 
-    async def _run_silver_searcher(
-        self,
-        pattern,
-        path,
-        include,
-        exclude,
-        case_sensitive,
-        fixed_strings,
-        show_context,
-        tool_ctx,
+    async def _run_silver_searcher_content(
+        self, pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
     ) -> str:
-        """Run silver searcher (ag) backend."""
+        """Run silver searcher (ag) backend for content search."""
         cmd = ["ag", "--nocolor", "--nogroup"]
 
         if not case_sensitive:
             cmd.append("-i")
-        if fixed_strings:
-            cmd.append("-F")
-        if show_context > 0:
-            cmd.extend(["-C", str(show_context)])
         if include:
             cmd.extend(["-G", include])
         if exclude:
             cmd.extend(["--ignore", exclude])
+        if max_results:
+            cmd.extend(["-m", str(max_results)])
 
         cmd.extend([pattern, path])
 
@@ -342,35 +409,23 @@ Fast, intuitive file content search."""
             await tool_ctx.error(f"Error running ag: {str(e)}")
             return f"Error running ag: {str(e)}"
 
-    async def _run_ack(
-        self,
-        pattern,
-        path,
-        include,
-        exclude,
-        case_sensitive,
-        fixed_strings,
-        show_context,
-        tool_ctx,
+    async def _run_ack_content(
+        self, pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
     ) -> str:
-        """Run ack backend."""
+        """Run ack backend for content search."""
         cmd = ["ack", "--nocolor", "--nogroup"]
 
         if not case_sensitive:
             cmd.append("-i")
-        if fixed_strings:
-            cmd.append("-Q")
-        if show_context > 0:
-            cmd.extend(["-C", str(show_context)])
         if include:
             # ack uses different syntax for file patterns
-            cmd.extend(
-                [
-                    "--type-add",
-                    f"custom:ext:{include.replace('*.', '')}",
-                    "--type=custom",
-                ]
-            )
+            cmd.extend([
+                "--type-add",
+                f"custom:ext:{include.replace('*.', '')}",
+                "--type=custom",
+            ])
+        if max_results:
+            cmd.extend(["-m", str(max_results)])
 
         cmd.extend([pattern, path])
 
@@ -396,18 +451,10 @@ Fast, intuitive file content search."""
             await tool_ctx.error(f"Error running ack: {str(e)}")
             return f"Error running ack: {str(e)}"
 
-    async def _run_fallback_grep(
-        self,
-        pattern,
-        path,
-        include,
-        exclude,
-        case_sensitive,
-        fixed_strings,
-        show_context,
-        tool_ctx,
+    async def _run_fallback_grep_content(
+        self, pattern, path, include, exclude, case_sensitive, max_results, tool_ctx
     ) -> str:
-        """Fallback Python implementation."""
+        """Fallback Python implementation for content search."""
         await tool_ctx.info("Using fallback Python grep implementation")
 
         try:
@@ -428,17 +475,11 @@ Fast, intuitive file content search."""
                 return "No matching files found."
 
             # Compile pattern
-            if fixed_strings:
-                pattern_re = re.escape(pattern)
-            else:
-                pattern_re = pattern
-
-            if not case_sensitive:
-                flags = re.IGNORECASE
-            else:
-                flags = 0
-
-            regex = re.compile(pattern_re, flags)
+            flags = 0 if case_sensitive else re.IGNORECASE
+            try:
+                regex = re.compile(pattern, flags)
+            except re.error as e:
+                return f"Error: Invalid regex pattern: {e}"
 
             # Search files
             results = []
@@ -451,28 +492,20 @@ Fast, intuitive file content search."""
 
                     for i, line in enumerate(lines, 1):
                         if regex.search(line):
-                            # Format result with context if requested
-                            if show_context > 0:
-                                start = max(0, i - show_context - 1)
-                                end = min(len(lines), i + show_context)
-
-                                context_lines = []
-                                for j in range(start, end):
-                                    prefix = ":" if j + 1 == i else "-"
-                                    context_lines.append(
-                                        f"{file_path}:{j + 1}{prefix}{lines[j].rstrip()}"
-                                    )
-                                results.extend(context_lines)
-                                results.append("")  # Separator
-                            else:
-                                results.append(f"{file_path}:{i}:{line.rstrip()}")
+                            results.append(f"{file_path}:{i}:{line.rstrip()}")
                             total_matches += 1
+                            
+                            if max_results and total_matches >= max_results:
+                                break
 
                 except UnicodeDecodeError:
                     pass  # Skip binary files
                 except Exception as e:
                     await tool_ctx.warning(f"Error reading {file_path}: {str(e)}")
 
+                if max_results and total_matches >= max_results:
+                    break
+
             if not results:
                 return "No matches found."
 
@@ -482,9 +515,109 @@ Fast, intuitive file content search."""
             await tool_ctx.error(f"Error in fallback grep: {str(e)}")
             return f"Error in fallback grep: {str(e)}"
 
-    def _match_file_pattern(
-        self, filename: str, include: Optional[str], exclude: Optional[str]
-    ) -> bool:
+    async def _find_files_fallback(
+        self,
+        pattern: str,
+        search_path: str,
+        recursive: bool,
+        ignore_case: bool,
+        hidden: bool,
+        dirs_only: bool,
+        files_only: bool,
+        max_results: int,
+    ) -> str:
+        """Fallback implementation for file name search when ffind is not available."""
+        results = []
+        count = 0
+
+        # Convert pattern for case-insensitive matching
+        if ignore_case:
+            pattern = pattern.lower()
+
+        try:
+            if recursive:
+                # Walk directory tree
+                for root, dirs, files in os.walk(search_path):
+                    # Skip hidden directories if not requested
+                    if not hidden:
+                        dirs[:] = [d for d in dirs if not d.startswith(".")]
+
+                    # Check directories
+                    if not files_only:
+                        for dirname in dirs:
+                            if self._match_pattern(dirname, pattern, ignore_case):
+                                filepath = os.path.join(root, dirname)
+                                rel_path = os.path.relpath(filepath, search_path)
+                                results.append(rel_path + "/")
+                                count += 1
+                                if count >= max_results:
+                                    break
+
+                    # Check files
+                    if not dirs_only:
+                        for filename in files:
+                            if not hidden and filename.startswith("."):
+                                continue
+
+                            if self._match_pattern(filename, pattern, ignore_case):
+                                filepath = os.path.join(root, filename)
+                                rel_path = os.path.relpath(filepath, search_path)
+                                results.append(rel_path)
+                                count += 1
+                                if count >= max_results:
+                                    break
+
+                    if count >= max_results:
+                        break
+            else:
+                # Only search in the specified directory
+                for entry in os.listdir(search_path):
+                    if not hidden and entry.startswith("."):
+                        continue
+
+                    filepath = os.path.join(search_path, entry)
+                    is_dir = os.path.isdir(filepath)
+
+                    if dirs_only and not is_dir:
+                        continue
+                    if files_only and is_dir:
+                        continue
+
+                    if self._match_pattern(entry, pattern, ignore_case):
+                        results.append(entry + "/" if is_dir else entry)
+                        count += 1
+                        if count >= max_results:
+                            break
+
+            if not results:
+                return f"No files found matching '{pattern}' (using fallback search)"
+
+            # Format output
+            output = [f"Found {len(results)} file(s) matching '{pattern}' (using fallback search):"]
+            output.append("")
+
+            for filepath in sorted(results):
+                output.append(filepath)
+
+            if count >= max_results:
+                output.append(f"\n... (showing first {max_results} results)")
+
+            if not FFIND_AVAILABLE:
+                output.append("\nNote: Install 'ffind' for faster searching: pip install ffind")
+
+            return "\n".join(output)
+
+        except Exception as e:
+            return f"Error searching for files: {str(e)}"
+
+    def _match_pattern(self, filename: str, pattern: str, ignore_case: bool) -> bool:
+        """Check if filename matches pattern."""
+        if ignore_case:
+            return fnmatch.fnmatch(filename.lower(), pattern)
+        else:
+            return fnmatch.fnmatch(filename, pattern)
+
+    def _match_file_pattern(self, filename: str, include: Optional[str], exclude: Optional[str]) -> bool:
         """Check if filename matches include/exclude patterns."""
         if include and not fnmatch.fnmatch(filename, include):
             return False
@@ -534,4 +667,4 @@ Fast, intuitive file content search."""
 
     def register(self, mcp_server) -> None:
         """Register this tool with the MCP server."""
-        pass
+        pass