feat: add search_directory tool for multi-file pattern search

Author: feryc@hotmail.com

README.md

@@ -37,6 +37,7 @@ Navigate, search, and edit large codebases, logs, and data files that exceed AI
 | `edit_content`     | Safe search/replace with automatic backups             |
 | `revert_edit`      | Recovering from bad edits                              |
 | `list_directory`   | Browse directory trees with recursive depth control    |
+| `search_directory` | Search patterns across all files in a directory        |
 
 ## When to Use Largefile
 

docs/API.md

@@ -4,7 +4,7 @@ Detailed documentation for the Largefile MCP Server tools.
 
 ## Overview
 
-The Largefile MCP Server provides 6 tools for working with large text files:
+The Largefile MCP Server provides 7 tools for working with large text files:
 
 | Tool | Purpose |
 |------|---------||
@@ -14,6 +14,7 @@ The Largefile MCP Server provides 6 tools for working with large text files:
 | **edit_content** | Batch search/replace editing with automatic backups |
 | **revert_edit** | Recover from bad edits via backup restoration |
 | **list_directory** | List directory contents with recursive depth and filtering |
+| **search_directory** | Multi-file pattern search across directory trees |
 
 All tools require absolute file paths and support auto-detected text encoding.
 

docs/configuration.md

@@ -315,4 +315,21 @@ LARGEFILE_IGNORED_DIR_PATTERNS=__pycache__,node_modules,.git
 - `LARGEFILE_MAX_DIR_ENTRIES` is a hard cap across all recursion depths combined.
 - `LARGEFILE_IGNORED_DIR_PATTERNS` matches exact directory *names* (not paths or globs).
   Hidden directories (e.g. `.git`) are filtered independently by `include_hidden`.
-- Entries are always listed directories-first, then files, each group sorted alphabetically.
+- Entries are always listed directories-first, then files, each group sorted alphabetically.
+
+## Directory Search Configuration
+
+Control the `search_directory` tool behaviour:
+
+```bash
+# Maximum total matches returned by search_directory across all files (default: 100)
+LARGEFILE_MAX_DIR_SEARCH_RESULTS=100
+```
+
+**Notes:**
+- `LARGEFILE_MAX_DIR_SEARCH_RESULTS` is a hard cap on *total matches* (not files).
+  When reached, `truncated=True` and `truncated_at` indicates where scanning stopped.
+- `LARGEFILE_IGNORED_DIR_PATTERNS` is shared with `list_directory` — one config
+  controls both tools.
+- `fuzzy=False` is the default for `search_directory`; enabling it on large trees
+  can be slow. Use `include_pattern` to narrow the scope first.

src/config.py

@@ -34,6 +34,9 @@ class Config:
     tree_sitter_timeout: int = int(os.getenv("LARGEFILE_TREE_SITTER_TIMEOUT", "5"))
 
     max_dir_entries: int = int(os.getenv("LARGEFILE_MAX_DIR_ENTRIES", "200"))
+    max_dir_search_results: int = int(
+        os.getenv("LARGEFILE_MAX_DIR_SEARCH_RESULTS", "100")
+    )
     ignored_dir_patterns: list[str] = field(
         default_factory=lambda: [
             p.strip()

src/data_models.py

@@ -137,3 +137,17 @@ class DirectoryListing:
     total_dirs: int
     truncated: bool
     truncated_at: str | None = None
+
+
+@dataclass
+class DirectorySearchResult:
+    """Summary metadata for a multi-file search operation."""
+
+    path: str
+    pattern: str
+    include_pattern: str
+    total_matches: int
+    files_searched: int
+    files_with_matches: int
+    truncated: bool
+    truncated_at: str | None = None

src/mcp_schemas.py

@@ -19,6 +19,7 @@ def read_content(self, **kwargs: Any) -> Any: ...
     def edit_content(self, **kwargs: Any) -> Any: ...
     def revert_edit(self, **kwargs: Any) -> Any: ...
     def list_directory(self, **kwargs: Any) -> Any: ...
+    def search_directory(self, **kwargs: Any) -> Any: ...
 
 
 def get_tool_schemas() -> list[types.Tool]:
@@ -271,6 +272,73 @@ def get_tool_schemas() -> list[types.Tool]:
             },
             annotations=types.ToolAnnotations(readOnlyHint=True),
         ),
+        types.Tool(
+            name="search_directory",
+            description=(
+                "Search for a text pattern across all files in a directory. "
+                "Returns results grouped by file with line numbers and context. "
+                "Use include_pattern to filter by file extension (e.g. '*.py'). "
+                "Automatically ignores __pycache__, node_modules, and .git. "
+                "Prefer fuzzy=False (default) for multi-file search performance."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "absolute_dir_path": {
+                        "type": "string",
+                        "description": "The absolute path to the directory to search.",
+                    },
+                    "pattern": {
+                        "type": "string",
+                        "description": "Text pattern to search for.",
+                    },
+                    "include_pattern": {
+                        "type": "string",
+                        "description": (
+                            "fnmatch glob matched against file names (default: '*'). "
+                            "Examples: '*.py', '*.md', '*.ts'."
+                        ),
+                        "default": "*",
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Total match cap across all files. Defaults to server config (100).",
+                    },
+                    "context_lines": {
+                        "type": "integer",
+                        "description": "Lines of context before/after each match (default: 2).",
+                        "default": 2,
+                    },
+                    "fuzzy": {
+                        "type": "boolean",
+                        "description": "Enable fuzzy matching (default: false \u2014 expensive for many files).",
+                        "default": False,
+                    },
+                    "regex": {
+                        "type": "boolean",
+                        "description": "Enable Python regex matching (default: false).",
+                        "default": False,
+                    },
+                    "case_sensitive": {
+                        "type": "boolean",
+                        "description": "Case-sensitive search (default: false).",
+                        "default": False,
+                    },
+                    "invert": {
+                        "type": "boolean",
+                        "description": "Return non-matching lines, like grep -v (default: false).",
+                        "default": False,
+                    },
+                    "include_hidden": {
+                        "type": "boolean",
+                        "description": "Include dot-files and dot-dirs (default: false).",
+                        "default": False,
+                    },
+                },
+                "required": ["absolute_dir_path", "pattern"],
+            },
+            annotations=types.ToolAnnotations(readOnlyHint=True),
+        ),
     ]
 
 
@@ -297,6 +365,8 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             result = tools_module.revert_edit(**arguments)
         elif name == "list_directory":
             result = tools_module.list_directory(**arguments)
+        elif name == "search_directory":
+            result = tools_module.search_directory(**arguments)
         else:
             raise ValueError(f"Unknown tool: {name}")
 

src/tools.py

@@ -1,6 +1,7 @@
+import fnmatch
 import os
 import shutil
-from collections.abc import Callable
+from collections.abc import Callable, Generator
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -12,6 +13,7 @@
     ChangeResult,
     DirectoryEntry,
     DirectoryListing,
+    DirectorySearchResult,
     FileOverview,
     LongLineStats,
     SearchResult,
@@ -834,3 +836,188 @@ def list_directory(
         "truncated": listing.truncated,
         "truncated_at": listing.truncated_at,
     }
+
+
+# ---------------------------------------------------------------------------
+# Directory search helpers
+# ---------------------------------------------------------------------------
+
+
+def _iter_searchable_files(
+    dir_path: str,
+    include_pattern: str,
+    include_hidden: bool,
+    ignored_patterns: list[str],
+) -> Generator[str, None, None]:
+    """Yield absolute paths of files matching include_pattern under dir_path.
+
+    Args:
+        dir_path: Root directory to walk.
+        include_pattern: fnmatch pattern matched against file names.
+        include_hidden: Whether to yield files/dirs starting with '.'.
+        ignored_patterns: Directory names to skip entirely.
+
+    Yields:
+        Absolute file paths in sorted, deterministic order.
+    """
+    for root, dirs, files in os.walk(dir_path):
+        dirs[:] = sorted(
+            d
+            for d in dirs
+            if (include_hidden or not d.startswith(".")) and d not in ignored_patterns
+        )
+        for fname in sorted(files):
+            if not include_hidden and fname.startswith("."):
+                continue
+            if not fnmatch.fnmatch(fname, include_pattern):
+                continue
+            yield os.path.join(root, fname)
+
+
+@handle_tool_errors
+def search_directory(
+    absolute_dir_path: str,
+    pattern: str,
+    include_pattern: str = "*",
+    max_results: int | None = None,
+    context_lines: int = 2,
+    fuzzy: bool = False,
+    regex: bool = False,
+    case_sensitive: bool = False,
+    invert: bool = False,
+    include_hidden: bool = False,
+) -> dict:
+    """Search for a pattern across all files in a directory.
+
+    Walks the directory recursively, applies include_pattern filtering on
+    filenames, and runs search_file() on each candidate. Results are grouped
+    by file with relative paths from the search root. Binary and unreadable
+    files are skipped silently.
+
+    CRITICAL: You must use an absolute directory path.
+
+    Args:
+        absolute_dir_path: Absolute path to the directory to search.
+        pattern: Search pattern (exact text, fuzzy, or regex).
+        include_pattern: fnmatch glob matched against file names (default "*").
+            Examples: "*.py", "*.md", "*.ts".
+        max_results: Total match cap across all files. Defaults to server
+            config (LARGEFILE_MAX_DIR_SEARCH_RESULTS = 100).
+        context_lines: Lines of context before/after each match (default 2).
+        fuzzy: Enable fuzzy matching (default False — expensive for many files).
+        regex: Enable Python regex matching (default False).
+        case_sensitive: Case-sensitive search (default False for multi-file).
+        invert: Return non-matching lines, like grep -v (default False).
+        include_hidden: Include dot-files and dot-dirs (default False).
+
+    Returns:
+        Dict with results list grouped by file, match totals, and truncation status.
+    """
+    dir_path = normalize_path(absolute_dir_path)
+
+    if not os.path.isdir(dir_path):
+        raise FileAccessError(f"Not a directory or does not exist: {dir_path}")
+
+    effective_max = (
+        max_results if max_results is not None else config.max_dir_search_results
+    )
+    if effective_max < 1:
+        raise FileAccessError(f"Invalid max_results {effective_max}: must be >= 1")
+
+    total_matches = 0
+    files_searched = 0
+    files_with_matches = 0
+    truncated = False
+    truncated_at: str | None = None
+    results: list[dict] = []
+
+    for abs_path in _iter_searchable_files(
+        dir_path, include_pattern, include_hidden, config.ignored_dir_patterns
+    ):
+        try:
+            matches = search_file(
+                abs_path, pattern, fuzzy, regex, case_sensitive, invert
+            )
+        except Exception:
+            continue  # skip unreadable / binary files silently
+
+        files_searched += 1
+
+        if not matches:
+            continue
+
+        remaining = effective_max - total_matches
+        if remaining <= 0:
+            truncated = True
+            truncated_at = os.path.relpath(abs_path, dir_path).replace("\\", "/")
+            break
+
+        clipped = matches[:remaining]
+
+        try:
+            lines = read_file_lines(abs_path)
+        except Exception:
+            lines = []
+
+        match_dicts: list[dict] = []
+        for m in clipped:
+            line_num = m.line_number
+
+            context_before = [
+                lines[i - 1].rstrip("\n\r")
+                for i in range(max(1, line_num - context_lines), line_num)
+                if i <= len(lines)
+            ]
+            context_after = [
+                lines[i - 1].rstrip("\n\r")
+                for i in range(
+                    line_num + 1,
+                    min(len(lines) + 1, line_num + context_lines + 1),
+                )
+                if i <= len(lines)
+            ]
+            match_content, is_truncated = truncate_line(m.content)
+            match_dicts.append(
+                {
+                    "line_number": line_num,
+                    "match": match_content,
+                    "context_before": context_before,
+                    "context_after": context_after,
+                    "similarity_score": m.similarity_score,
+                    "match_type": m.match_type,
+                    "truncated": is_truncated,
+                }
+            )
+
+        total_matches += len(clipped)
+        files_with_matches += 1
+        rel_path = os.path.relpath(abs_path, dir_path).replace("\\", "/")
+        results.append({"file": rel_path, "matches": match_dicts})
+
+        if len(clipped) < len(matches):
+            truncated = True
+            truncated_at = rel_path
+            break
+
+    summary = DirectorySearchResult(
+        path=dir_path,
+        pattern=pattern,
+        include_pattern=include_pattern,
+        total_matches=total_matches,
+        files_searched=files_searched,
+        files_with_matches=files_with_matches,
+        truncated=truncated,
+        truncated_at=truncated_at,
+    )
+
+    return {
+        "path": summary.path,
+        "pattern": summary.pattern,
+        "include_pattern": summary.include_pattern,
+        "total_matches": summary.total_matches,
+        "files_searched": summary.files_searched,
+        "files_with_matches": summary.files_with_matches,
+        "truncated": summary.truncated,
+        "truncated_at": summary.truncated_at,
+        "results": results,
+    }