MCP Filesystem Server

Instructions

Args:
    path: Starting directory
    recursive: Whether to search subdirectories
    exclude_patterns: Optional patterns to exclude
    format: Output format ('text' or 'json')
    ctx: MCP context

Returns:
    Empty directory information

Implementation Reference

• mcp_filesystem/advanced.py:680-771 (handler)

  Core implementation of find_empty_directories in AdvancedFileOperations class. Recursively scans directories to identify empty ones, handles path validation, exclusion patterns, and permission errors.

  async def find_empty_directories(
      self,
      root_path: Union[str, Path],
      recursive: bool = True,
      exclude_patterns: Optional[List[str]] = None,
  ) -> List[str]:
      """Find empty directories.
  
      Args:
          root_path: Starting directory
          recursive: Whether to search subdirectories
          exclude_patterns: Optional patterns to exclude
  
      Returns:
          List of empty directory paths
  
      Raises:
          ValueError: If root_path is outside allowed directories
      """
      abs_path, allowed = await self.validator.validate_path(root_path)
      if not allowed:
          raise ValueError(f"Path outside allowed directories: {root_path}")
  
      if not abs_path.is_dir():
          raise ValueError(f"Not a directory: {root_path}")
  
      # Compile exclude patterns if provided
      exclude_regexes = []
      if exclude_patterns:
          for exclude in exclude_patterns:
              try:
                  exclude_regexes.append(re.compile(exclude))
              except re.error:
                  logger.warning(f"Invalid exclude pattern: {exclude}")
  
      empty_dirs = []
  
      async def scan_for_empty_dirs(dir_path: Path) -> bool:
          """Scan for empty directories, return True if directory is empty."""
          try:
              entries = await anyio.to_thread.run_sync(list, dir_path.iterdir())
  
              if not entries:
                  # Found an empty directory
                  empty_dirs.append(str(dir_path))
                  return True
  
              # If not recursive, just check if this directory is empty
              if not recursive:
                  return False
  
              # Check if directory is empty after checking all subdirectories
              is_empty = True
  
              for entry in entries:
                  # Skip if matched by exclude pattern
                  path_str = str(entry)
                  excluded = False
                  for exclude_re in exclude_regexes:
                      if exclude_re.search(path_str):
                          excluded = True
                          break
  
                  if excluded:
                      # Treat excluded entries as if they don't exist
                      continue
  
                  if entry.is_file():
                      # Files make the directory non-empty
                      is_empty = False
                  elif entry.is_dir():
                      # Check if this subdir is allowed
                      entry_abs, entry_allowed = await self.validator.validate_path(
                          entry
                      )
                      if entry_allowed:
                          # If any subdirectory is non-empty, this directory is non-empty
                          subdir_empty = await scan_for_empty_dirs(entry)
                          if not subdir_empty:
                              is_empty = False
  
              if is_empty:
                  empty_dirs.append(str(dir_path))
  
              return is_empty
  
          except (PermissionError, FileNotFoundError):
              # Skip directories we can't access
              return False
  
      await scan_for_empty_dirs(abs_path)
      return empty_dirs

• mcp_filesystem/server.py:667-703 (registration)

  MCP tool registration for find_empty_directories. Delegates to AdvancedFileOperations implementation, handles JSON/text formatting, and error responses.

  @mcp.tool()
  async def find_empty_directories(
      path: str,
      ctx: Context,
      recursive: bool = True,
      exclude_patterns: Optional[List[str]] = None,
      format: str = "text",
  ) -> str:
      """Find empty directories.
  
      Args:
          path: Starting directory
          recursive: Whether to search subdirectories
          exclude_patterns: Optional patterns to exclude
          format: Output format ('text' or 'json')
          ctx: MCP context
  
      Returns:
          Empty directory information
      """
      try:
          components = get_components()
          results = await components["advanced"].find_empty_directories(
              path, recursive, exclude_patterns
          )
  
          if format.lower() == "json":
              return json.dumps(results, indent=2)
  
          # Format as text
          if not results:
              return "No empty directories found"
  
          return f"Found {len(results)} empty directories:\n\n" + "\n".join(results)
  
      except Exception as e:
          return f"Error finding empty directories: {str(e)}"