ssh-mcp

Instructions

Implementation Reference

• src/ssh_mcp/server.py:273-297 (handler)

  The 'download_file' MCP tool handler function. Decorated with @mcp.tool() to register it as an MCP tool. Takes server name, remote_path, and local_path parameters, initializes the SSH manager, and delegates to _ssh.download() for the actual SFTP transfer.

  @mcp.tool()
  async def download_file(
      server: str,
      remote_path: str,
      local_path: str,
  ) -> str:
      """Download a file from a remote server via SFTP.
  
      Args:
          server: Server name (e.g. 'pro-dicentra').
          remote_path: Absolute path to remote file.
          local_path: Absolute local destination path.
  
      Returns:
          Confirmation message with file size.
      """
      try:
          _init()
  
          result = await _ssh.download(server, remote_path, local_path)
          return result
  
      except Exception as e:
          logger.error(f"Error downloading file from {server}: {e}")
          return f"Error downloading file from {server}: {e}"

• src/ssh_mcp/ssh.py:435-484 (helper)

  The core implementation of the download functionality in SSHManager.download(). Validates the remote path, establishes an SSH connection, uses SFTP to download the file, logs the operation for audit purposes, and returns a confirmation message with file size.

  async def download(
      self, server_name: str, remote_path: str, local_path: str
  ) -> str:
      """Download file from remote server via SFTP.
  
      Args:
          server_name: Server name from registry
          remote_path: Remote file path
          local_path: Local destination path
  
      Returns:
          Confirmation message with file size
      """
      try:
          # Validate remote path
          _validate_remote_path(remote_path)
  
          start_time = time.monotonic()
          conn = await self._get_connection(server_name)
  
          # Start SFTP client
          async with conn.start_sftp_client() as sftp:
              # Download file
              await sftp.get(remote_path, local_path)
  
              # Get file size for confirmation
              local_size = Path(local_path).stat().st_size
              duration_ms = int((time.monotonic() - start_time) * 1000)
  
              # Audit log download
              self._audit.info(
                  "server=%s operation=download remote_path=%s local_path=%s bytes=%s duration_ms=%s",
                  server_name,
                  remote_path,
                  local_path,
                  local_size,
                  duration_ms,
              )
  
              return f"Downloaded {server_name}:{remote_path} to {local_path} ({local_size} bytes)"
  
      except (
          asyncssh.DisconnectError,
          asyncssh.PermissionDenied,
          asyncssh.SFTPError,
          OSError,
      ) as e:
          error_msg = f"Download failed from {server_name}: {e}"
          logger.error(error_msg)
          raise RuntimeError(error_msg) from e

• src/ssh_mcp/ssh.py:61-78 (helper)

  Path validation helper function that blocks parent directory traversal (..) and access to sensitive paths for SFTP operations, providing security controls for the download_file tool.

  def _validate_remote_path(path: str) -> None:
      """Validate remote path for SFTP operations.
  
      Args:
          path: Remote path to validate
  
      Raises:
          ValueError: If path contains parent traversal or sensitive paths
      """
      # Block parent directory traversal
      if ".." in path:
          raise ValueError(f"Path traversal detected: {path}")
  
      # Block access to sensitive paths
      normalized_path = path.lower()
      for sensitive in _SENSITIVE_PATHS:
          if sensitive in normalized_path:
              raise ValueError(f"Access to sensitive path blocked: {path}")

• src/ssh_mcp/ssh.py:34-43 (schema)

  Defines sensitive paths that are blocked in SFTP operations (like /etc/shadow, .ssh/id_rsa, etc.) as a security measure to prevent downloading sensitive files.

  # Sensitive paths that should be blocked in SFTP operations
  _SENSITIVE_PATHS = [
      "/etc/shadow",
      "/etc/passwd",
      ".ssh/authorized_keys",
      ".ssh/id_rsa",
      ".ssh/id_ed25519",
      ".ssh/id_ecdsa",
      ".ssh/id_dsa",
  ]