Sympathy-MCP

Instructions

Implementation Reference

• src/sympathy_mcp/transport.py:325-350 (handler)

  Main implementation of vm_file_pull - pulls a file from a remote host to the local host via SCP. Validates inputs, creates local directory if needed, and uses _run_scp to perform the transfer.
  async def vm_file_pull( vm: str, remote_path: str, local_path: str, ) -> ExecResult: """Pull a file from a remote host to the local host via SCP. Args: vm: Name of the host (as configured in hosts.toml). remote_path: Absolute path to the file on the remote host. local_path: Destination path on the local host. Returns: ExecResult with operation details. """ host = _resolve_host(vm) _validate_path(remote_path) _validate_local_path(local_path) local_dir = Path(local_path).parent local_dir.mkdir(parents=True, exist_ok=True) return await _run_scp( host, [f"{host.scp_prefix}{remote_path}", local_path], )
• src/sympathy_mcp/server.py:195-217 (registration)

  MCP tool registration wrapper for vm_file_pull. Decorated with @mcp.tool(), this function calls the underlying transport implementation and formats the result as a user-friendly string with success/error messages.
  @mcp.tool() async def vm_file_pull( vm: str, remote_path: str, local_path: str, ) -> str: """Pull a file from a remote host to the local host via SCP. Args: vm: Name of the host (as configured in hosts.toml). remote_path: Absolute path to the file on the remote host. local_path: Destination path on the local host. Returns: Success confirmation or error message. """ try: result = await _vm_file_pull(vm, remote_path, local_path) if result.exit_code == 0: return f"Successfully pulled {vm}:{remote_path} -> {local_path}" return f"ERROR pulling file: {result.stderr.strip()}" except (ValueError, KeyError, RuntimeError, OSError) as e: return f"ERROR: {e}"
• src/sympathy_mcp/transport.py:55-62 (helper)

  Path validation helper - validates that remote paths are non-empty, contain no null bytes, and are absolute (start with '/'). Used by vm_file_pull to validate the remote_path parameter.
  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}'")
• src/sympathy_mcp/transport.py:65-70 (helper)

  Local path validation helper - validates that local paths are non-empty and contain no null bytes. Used by vm_file_pull to validate the local_path parameter.
  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:193-197 (helper)

  Host resolution helper - resolves a VM/host name to its SSH configuration from the loaded config. Used by vm_file_pull to get the HostConfig for the target VM.
  def _resolve_host(vm: str) -> HostConfig: """Resolve a VM/host name to its SSH config.""" _validate_host_name(vm) config = _get_config() return config.get_host(vm)