MCP Filesystem Server

Instructions

Args:
    source: Source path
    destination: Destination path
    overwrite: Whether to overwrite existing destination
    ctx: MCP context

Returns:
    Success or error message

Implementation Reference

• mcp_filesystem/server.py:233-257 (handler)

  MCP tool handler for 'move_file'. This is the entry point decorated with @mcp.tool(), handling input parameters, error catching, and delegating to the core operations.move_file method.

  @mcp.tool()
  async def move_file(
      source: str,
      destination: str,
      ctx: Context,
      overwrite: bool = False,
  ) -> str:
      """Move or rename files and directories.
  
      Args:
          source: Source path
          destination: Destination path
          overwrite: Whether to overwrite existing destination
          ctx: MCP context
  
      Returns:
          Success or error message
      """
      try:
          components = get_components()
          await components["operations"].move_file(source, destination, overwrite)
          return f"Successfully moved {source} to {destination}"
      except Exception as e:
          return f"Error moving file: {str(e)}"

• mcp_filesystem/operations.py:354-395 (helper)

  Core implementation of the move_file logic in FileOperations class. Validates paths using PathValidator, checks existence and overwrite conditions, then performs the move using shutil.move in a thread.

  async def move_file(
      self,
      source: Union[str, Path],
      destination: Union[str, Path],
      overwrite: bool = False,
  ) -> None:
      """Move or rename a file or directory.
  
      Args:
          source: Source path
          destination: Destination path
          overwrite: Whether to overwrite destination if it exists
  
      Raises:
          ValueError: If paths are outside allowed directories
          FileNotFoundError: If source does not exist
          FileExistsError: If destination exists and overwrite is False
      """
      source_path, source_allowed = await self.validator.validate_path(source)
      if not source_allowed:
          raise ValueError(f"Source path outside allowed directories: {source}")
  
      dest_path, dest_allowed = await self.validator.validate_path(destination)
      if not dest_allowed:
          raise ValueError(
              f"Destination path outside allowed directories: {destination}"
          )
  
      # Check if source exists
      if not source_path.exists():
          raise FileNotFoundError(f"Source does not exist: {source}")
  
      # Check if destination exists and we're not overwriting
      if dest_path.exists() and not overwrite:
          raise FileExistsError(f"Destination already exists: {destination}")
  
      try:
          # Use shutil.move which handles cross-filesystem moves
          await anyio.to_thread.run_sync(shutil.move, source_path, dest_path)
      except (PermissionError, shutil.Error) as e:
          raise ValueError(f"Cannot move file: {e}")