MCP Filesystem Server

Instructions

Args:
    path: Starting directory or file path
    pattern: Text or regex pattern to search for
    is_regex: Whether to treat pattern as regex
    case_sensitive: Whether search is case sensitive
    whole_word: Match whole words only
    include_patterns: Only include files matching these patterns
    exclude_patterns: Exclude files matching these patterns
    context_lines: Number of lines to show before AND after matches (like grep -C)
    context_before: Number of lines to show BEFORE matches (like grep -B)
    context_after: Number of lines to show AFTER matches (like grep -A)
    results_offset: Start at Nth match (0-based, for pagination)
    results_limit: Return at most this many matches (for pagination)
    max_results: Maximum total matches to find during search
    max_file_size_mb: Skip files larger than this size
    recursive: Whether to search subdirectories
    max_depth: Maximum directory depth to recurse
    count_only: Only show match counts per file
    format: Output format ('text' or 'json')
    ctx: MCP context

Returns:
    Search results

Implementation Reference

• mcp_filesystem/server.py:707-803 (registration)

  Registration of the 'grep_files' MCP tool. This decorator defines the tool schema via function parameters and serves as the entrypoint, instantiating GrepTools via get_components() and calling its grep_files method.

  async def grep_files(
      path: str,
      pattern: str,
      ctx: Context,
      is_regex: bool = False,
      case_sensitive: bool = True,
      whole_word: bool = False,
      include_patterns: Optional[List[str]] = None,
      exclude_patterns: Optional[List[str]] = None,
      context_lines: int = 0,
      context_before: int = 0,
      context_after: int = 0,
      results_offset: int = 0,
      results_limit: Optional[int] = None,
      max_results: int = 1000,
      max_file_size_mb: float = 10,
      recursive: bool = True,
      max_depth: Optional[int] = None,
      count_only: bool = False,
      format: str = "text",
  ) -> str:
      """Search for pattern in files, similar to grep.
  
      Args:
          path: Starting directory or file path
          pattern: Text or regex pattern to search for
          is_regex: Whether to treat pattern as regex
          case_sensitive: Whether search is case sensitive
          whole_word: Match whole words only
          include_patterns: Only include files matching these patterns
          exclude_patterns: Exclude files matching these patterns
          context_lines: Number of lines to show before AND after matches (like grep -C)
          context_before: Number of lines to show BEFORE matches (like grep -B)
          context_after: Number of lines to show AFTER matches (like grep -A)
          results_offset: Start at Nth match (0-based, for pagination)
          results_limit: Return at most this many matches (for pagination)
          max_results: Maximum total matches to find during search
          max_file_size_mb: Skip files larger than this size
          recursive: Whether to search subdirectories
          max_depth: Maximum directory depth to recurse
          count_only: Only show match counts per file
          format: Output format ('text' or 'json')
          ctx: MCP context
  
      Returns:
          Search results
      """
      try:
          components = get_components()
  
          # Fix regex escaping - if is_regex is True, handle backslash escaping
          pattern_fixed = pattern
          if is_regex and "\\" in pattern:
              # For patterns coming from JSON where backslashes are escaped,
              # we need to convert double backslashes to single backslashes
              pattern_fixed = pattern.replace("\\\\", "\\")
  
          results = await components["grep"].grep_files(
              path,
              pattern_fixed,
              is_regex,
              case_sensitive,
              whole_word,
              include_patterns,
              exclude_patterns,
              context_lines,
              context_before,
              context_after,
              max_results,
              max_file_size_mb,
              recursive,
              max_depth,
              count_only,
              results_offset=results_offset,
              results_limit=results_limit,
          )
  
          if format.lower() == "json":
              return json.dumps(results.to_dict(), indent=2)
          else:
              # Format as text with appropriate options
              show_line_numbers = True
              show_file_names = True
              show_context = context_lines > 0
              highlight = True
  
              return results.format_text(
                  show_line_numbers=show_line_numbers,
                  show_file_names=show_file_names,
                  count_only=count_only,
                  show_context=show_context,
                  highlight=highlight,
              )
  
      except Exception as e:
          return f"Error searching files: {str(e)}"

• mcp_filesystem/grep.py:251-351 (handler)

  Core handler implementation: GrepTools.grep_files method. Validates path, checks for ripgrep availability, and dispatches to ripgrep or Python fallback implementations.

  async def grep_files(
      self,
      path: Union[str, Path],
      pattern: str,
      is_regex: bool = False,
      case_sensitive: bool = True,
      whole_word: bool = False,
      include_patterns: Optional[List[str]] = None,
      exclude_patterns: Optional[List[str]] = None,
      context_lines: int = 0,
      context_before: int = 0,
      context_after: int = 0,
      max_results: int = 1000,
      max_file_size_mb: float = 10,
      recursive: bool = True,
      max_depth: Optional[int] = None,
      count_only: bool = False,
      results_offset: int = 0,
      results_limit: Optional[int] = None,
      show_progress: bool = False,
      progress_callback: Optional[Callable[[int, int], Any]] = None,
  ) -> GrepResult:
      """Search for pattern in files, similar to grep.
  
      Args:
          path: Starting directory or file path
          pattern: Text or regex pattern to search for
          is_regex: Whether to treat pattern as regex
          case_sensitive: Whether search is case sensitive
          whole_word: Match whole words only
          include_patterns: Only include files matching these patterns
          exclude_patterns: Exclude files matching these patterns
          context_lines: Number of lines to show before AND after matches (like grep -C)
          context_before: Number of lines to show BEFORE matches (like grep -B)
          context_after: Number of lines to show AFTER matches (like grep -A)
          max_results: Maximum total matches to find during search
          max_file_size_mb: Skip files larger than this size
          recursive: Whether to search subdirectories
          max_depth: Maximum directory depth to recurse
          count_only: Only show match counts per file
          results_offset: Start at Nth match (0-based, for pagination)
          results_limit: Return at most this many matches (for pagination)
          show_progress: Whether to show progress
          progress_callback: Optional callback for progress updates
  
      Returns:
          GrepResult object with matches and statistics
  
      Raises:
          ValueError: If path is outside allowed directories
      """
      abs_path, allowed = await self.validator.validate_path(path)
      if not allowed:
          raise ValueError(f"Path outside allowed directories: {path}")
  
      if self._ripgrep_available and not count_only:
          # Use ripgrep for better performance
          try:
              return await self._grep_with_ripgrep(
                  abs_path,
                  pattern,
                  is_regex,
                  case_sensitive,
                  whole_word,
                  include_patterns,
                  exclude_patterns,
                  context_lines,
                  context_before,
                  context_after,
                  max_results,
                  recursive,
                  max_depth,
                  results_offset,
                  results_limit,
              )
          except Exception as e:
              logger.warning(f"Ripgrep failed, falling back to Python: {e}")
  
      # Fall back to Python implementation
      return await self._grep_with_python(
          abs_path,
          pattern,
          is_regex,
          case_sensitive,
          whole_word,
          include_patterns,
          exclude_patterns,
          context_lines,
          context_before,
          context_after,
          max_results,
          max_file_size_mb,
          recursive,
          max_depth,
          count_only,
          show_progress,
          progress_callback,
          results_offset,
          results_limit,
      )

• mcp_filesystem/grep.py:79-218 (helper)

  GrepResult class: Manages grep search results, including matches, statistics, errors, and provides serialization and text formatting methods.

  class GrepResult:
      """Result of a grep operation."""
  
      def __init__(self):
          """Initialize an empty grep result."""
          self.matches: List[GrepMatch] = []
          self.file_counts: Dict[str, int] = {}
          self.total_matches = 0
          self.files_searched = 0
          self.errors: Dict[str, str] = {}
  
      def add_match(self, match: GrepMatch) -> None:
          """Add a match to the results.
  
          Args:
              match: GrepMatch to add
          """
          self.matches.append(match)
          self.total_matches += 1
  
          # Update file counts
          if match.file_path in self.file_counts:
              self.file_counts[match.file_path] += 1
          else:
              self.file_counts[match.file_path] = 1
  
      def add_file_error(self, file_path: str, error: str) -> None:
          """Add a file error to the results.
  
          Args:
              file_path: Path to the file with the error
              error: Error message
          """
          self.errors[file_path] = error
  
      def increment_files_searched(self) -> None:
          """Increment the count of files searched."""
          self.files_searched += 1
  
      def to_dict(self) -> Dict:
          """Convert to dictionary representation.
  
          Returns:
              Dictionary with all results
          """
          return {
              "matches": [match.to_dict() for match in self.matches],
              "file_counts": self.file_counts,
              "total_matches": self.total_matches,
              "files_searched": self.files_searched,
              "errors": self.errors,
          }
  
      def format_text(
          self,
          show_line_numbers: bool = True,
          show_file_names: bool = True,
          count_only: bool = False,
          show_context: bool = True,
          highlight: bool = True,
      ) -> str:
          """Format results as text.
  
          Args:
              show_line_numbers: Include line numbers in output
              show_file_names: Include file names in output
              count_only: Only show match counts per file
              show_context: Show context lines if available
              highlight: Highlight matches
  
          Returns:
              Formatted string with results
          """
          if count_only:
              lines = [
                  f"Found {self.total_matches} matches in {len(self.file_counts)} files:"
              ]
              for file_path, count in sorted(self.file_counts.items()):
                  lines.append(f"{file_path}: {count} matches")
              return "\n".join(lines)
  
          if not self.matches:
              return "No matches found"
  
          lines = []
          current_file = None
  
          for match in self.matches:
              # Add file header if changed
              if show_file_names and match.file_path != current_file:
                  current_file = match.file_path
                  lines.append(f"\n{current_file}:")
  
              # Add context before
              if show_context and match.context_before:
                  for i, context in enumerate(match.context_before):
                      context_line_num = match.line_number - len(match.context_before) + i
                      if show_line_numbers:
                          lines.append(f"{context_line_num:>6}: {context}")
                      else:
                          lines.append(f"{context}")
  
              # Add matching line
              line_prefix = ""
              if show_line_numbers:
                  line_prefix = f"{match.line_number:>6}: "
  
              if highlight:
                  # Highlight the match in the line
                  line = match.line_content
                  highlighted = (
                      line[: match.match_start]
                      + ">>>"
                      + line[match.match_start : match.match_end]
                      + "<<<"
                      + line[match.match_end :]
                  )
                  lines.append(f"{line_prefix}{highlighted}")
              else:
                  lines.append(f"{line_prefix}{match.line_content}")
  
              # Add context after
              if show_context and match.context_after:
                  for i, context in enumerate(match.context_after):
                      context_line_num = match.line_number + i + 1
                      if show_line_numbers:
                          lines.append(f"{context_line_num:>6}: {context}")
                      else:
                          lines.append(f"{context}")
  
          # Add summary
          summary = (
              f"\nFound {self.total_matches} matches in {len(self.file_counts)} files"
          )
          if self.errors:
              summary += f" ({len(self.errors)} files had errors)"
          lines.append(summary)
  
          return "\n".join(lines)

• mcp_filesystem/grep.py:22-77 (helper)

  GrepMatch class: Data structure for individual search matches, including file path, line details, match position, and context lines.

  class GrepMatch:
      """Represents a single grep match."""
  
      def __init__(
          self,
          file_path: str,
          line_number: int,
          line_content: str,
          match_start: int,
          match_end: int,
          context_before: Optional[List[str]] = None,
          context_after: Optional[List[str]] = None,
      ):
          """Initialize a grep match.
  
          Args:
              file_path: Path to the file containing the match
              line_number: Line number of the match (1-based)
              line_content: Content of the matching line
              match_start: Start index of the match within the line
              match_end: End index of the match within the line
              context_before: Lines before the match
              context_after: Lines after the match
          """
          self.file_path = file_path
          self.line_number = line_number
          self.line_content = line_content
          self.match_start = match_start
          self.match_end = match_end
          self.context_before = context_before or []
          self.context_after = context_after or []
  
      def to_dict(self) -> Dict:
          """Convert to dictionary representation.
  
          Returns:
              Dictionary with match information
          """
          return {
              "file_path": self.file_path,
              "line_number": self.line_number,
              "line_content": self.line_content,
              "match_start": self.match_start,
              "match_end": self.match_end,
              "context_before": self.context_before,
              "context_after": self.context_after,
          }
  
      def __str__(self) -> str:
          """Get string representation.
  
          Returns:
              Formatted string with match information
          """
          return f"{self.file_path}:{self.line_number}: {self.line_content}"

• mcp_filesystem/server.py:48-84 (helper)

  get_components function instantiates GrepTools with PathValidator for security and caches shared components used by all tools.

  def get_components() -> Dict[str, Any]:
      """Initialize and return shared components.
  
      Returns cached components if already initialized.
  
      Returns:
          Dictionary with initialized components
      """
      # Return cached components if available
      if _components_cache:
          return _components_cache
  
      # Initialize components
      allowed_dirs_typed: List[Union[str, Path]] = get_allowed_dirs()
      validator = PathValidator(allowed_dirs_typed)
      operations = FileOperations(validator)
      advanced = AdvancedFileOperations(validator, operations)
      grep = GrepTools(validator)
  
      # Store in cache
      _components = {
          "validator": validator,
          "operations": operations,
          "advanced": advanced,
          "grep": grep,
          "allowed_dirs": validator.get_allowed_dirs(),
      }
  
      # Update cache
      _components_cache.update(_components)
  
      logger.info(
          f"Initialized filesystem components with allowed directories: {validator.get_allowed_dirs()}"
      )
  
      return _components