add_vm_share

Instructions

Implementation Reference

• src/mcp_utm/server.py:232-245 (handler)

  MCP tool handler for 'add_vm_share'. Decorated with @mcp.tool(), it accepts VM name and host directory path, delegates to utm.add_vm_share(), and returns the updated share list.

  @mcp.tool()
  def add_vm_share(name: str, path: str) -> dict:
      """Add a host directory as a VirtioFS share on a VM.
  
      Creates a security-scoped bookmark so the share persists across boots
      and works with Apple VF clones. The directory appears inside the guest
      at /Volumes/My Shared Files/<folder-name>.
  
      Args:
          name: VM name (must be stopped)
          path: Host directory path to share (e.g. "/Users/you/project")
      """
      shares = utm.add_vm_share(name, path)
      return {"name": name, "shares": shares}

• src/mcp_utm/applescript.py:623-632 (helper)

  Core implementation of add_vm_share. Validates the path, lists current shares, deduplicates by normalized path, appends the new path, and calls set_vm_shares() to persist via AppleScript.

  def add_vm_share(name: str, path: str) -> list[str]:
      """Add a shared directory to a VM without removing existing shares."""
      _validate_path(path)
      current = list_vm_shares(name)
      normalized = path.rstrip("/")
      existing = [p.rstrip("/") for p in current]
      if normalized in existing:
          return current
      current.append(path)
      return set_vm_shares(name, current)

• src/mcp_utm/applescript.py:598-620 (helper)

  set_vm_shares() — the lower-level helper that constructs the AppleScript to update the UTM VM registry with the full list of share paths.

  def set_vm_shares(name: str, paths: list[str]) -> list[str]:
      """Replace all shared directories for a VM."""
      _validate_vm_name(name)
      for p in paths:
          _validate_path(p)
  
      if not paths:
          script = f'''
          tell application "UTM"
              set vm to virtual machine named "{_esc(name)}"
              update registry of vm with {{}}
          end tell
          '''
      else:
          share_items = ", ".join(f'POSIX file "{_esc(p)}"' for p in paths)
          script = f'''
          tell application "UTM"
              set vm to virtual machine named "{_esc(name)}"
              update registry of vm with {{{share_items}}}
          end tell
          '''
      _run(script)
      return list_vm_shares(name)

• src/mcp_utm/applescript.py:580-595 (helper)

  list_vm_shares() — helper used by add_vm_share to retrieve current shares from a VM via AppleScript.

  def list_vm_shares(name: str) -> list[str]:
      """List shared directories registered for a VM. Returns POSIX paths."""
      _validate_vm_name(name)
      script = f'''
      tell application "UTM"
          set vm to virtual machine named "{_esc(name)}"
          set shares to registry of vm
          set output to ""
          repeat with s in shares
              set output to output & (POSIX path of s) & linefeed
          end repeat
          return output
      end tell
      '''
      raw = _run(script)
      return [p.strip() for p in raw.strip().split("\n") if p.strip()]

• src/mcp_utm/server.py:12-12 (registration)

  Tool registration: 'add_vm_share' is registered by the @mcp.tool() decorator on the handler function. mcp = FastMCP('utm') creates the server instance that manages tool registration.

  from . import applescript as utm