Sympathy-MCP

Instructions

Args:
    vm: Name of the host (as configured in hosts.toml).
    local_path: Path to the file on the local host.
    remote_path: Absolute destination path on the remote host.

Returns:
    Success confirmation or error message.

Implementation Reference

• src/sympathy_mcp/server.py:171-192 (handler)

  MCP tool handler decorated with @mcp.tool() that wraps the core implementation. Handles errors and returns user-friendly messages. This is the main entry point for MCP clients calling the tool.

  async def vm_file_push(
      vm: str,
      local_path: str,
      remote_path: str,
  ) -> str:
      """Push a file from the local host to a remote host via SCP.
  
      Args:
          vm: Name of the host (as configured in hosts.toml).
          local_path: Path to the file on the local host.
          remote_path: Absolute destination path on the remote host.
  
      Returns:
          Success confirmation or error message.
      """
      try:
          result = await _vm_file_push(vm, local_path, remote_path)
          if result.exit_code == 0:
              return f"Successfully pushed {local_path} -> {vm}:{remote_path}"
          return f"ERROR pushing file: {result.stderr.strip()}"
      except (ValueError, KeyError, FileNotFoundError, RuntimeError, OSError) as e:
          return f"ERROR: {e}"

• src/sympathy_mcp/transport.py:297-322 (handler)

  Core implementation of vm_file_push that performs SCP file transfer from local host to remote host. Validates paths, checks file existence, and executes the SCP command.

  async def vm_file_push(
      vm: str,
      local_path: str,
      remote_path: str,
  ) -> ExecResult:
      """Push a file from the local host to a remote host via SCP.
  
      Args:
          vm: Name of the host (as configured in hosts.toml).
          local_path: Path to the file on the local host.
          remote_path: Absolute destination path on the remote host.
  
      Returns:
          ExecResult with operation details.
      """
      host = _resolve_host(vm)
      _validate_local_path(local_path)
      _validate_path(remote_path)
  
      if not Path(local_path).is_file():
          raise FileNotFoundError(f"Local file not found: {local_path}")
  
      return await _run_scp(
          host,
          [local_path, f"{host.scp_prefix}{remote_path}"],
      )

• src/sympathy_mcp/transport.py:55-71 (schema)

  Input validation functions _validate_path and _validate_local_path that validate remote and local file paths (check for empty strings, null bytes, and absolute paths).

  def _validate_path(path: str) -> None:
      """Validate a file path on the remote host (basic safety checks)."""
      if not path or not path.strip():
          raise ValueError("Path cannot be empty")
      if "\x00" in path:
          raise ValueError("Path cannot contain null bytes")
      if not path.startswith("/"):
          raise ValueError(f"Path must be absolute (start with /): '{path}'")
  
  
  def _validate_local_path(path: str) -> None:
      """Validate a local file path on the host."""
      if not path or not path.strip():
          raise ValueError("Local path cannot be empty")
      if "\x00" in path:
          raise ValueError("Path cannot contain null bytes")

• src/sympathy_mcp/transport.py:27-33 (schema)

  ExecResult dataclass defining the return type structure with stdout, stderr, and exit_code fields used by the vm_file_push function.

  @dataclass
  class ExecResult:
      """Result of running a command on a remote host."""
  
      stdout: str
      stderr: str
      exit_code: int

• src/sympathy_mcp/server.py:26-26 (registration)

  Import statement that imports vm_file_push from transport module as _vm_file_push, connecting the MCP handler to the core implementation.

  vm_file_push as _vm_file_push,