MCP Filesystem Server

Instructions

Implementation Reference

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

  Core handler function that implements the logic to find empty directories by recursively scanning directories, skipping excluded patterns, and validating paths.
  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 with @mcp.tool() decorator. This wrapper function handles input parameters, delegates to the advanced component for core logic, and formats the output as text or JSON.
  @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)}"