List all visible top-level X11 windows with id, title, and geometry.

Use this first to discover the exact window title you need for capture_window or capture_region. Each entry has: id, title, desktop, x, y, width, height.

Capture an entire window identified by its title (case-insensitive substring match).

Args: title: Window title or substring of it (case-insensitive). Use list_windows to find candidates. When multiple windows match, the call fails and lists the matching titles — provide a more specific substring or set exact=True. exact: If True, match the title exactly (case-sensitive).

Returns the screenshot as a PNG image. The window's geometry is logged but not returned alongside the image (call list_windows for geometry details).

Capture a rectangular screen region as a PNG image.

Args: x: Top-left X. Absolute screen coordinate, or relative to the window identified by title when that is given. y: Top-left Y. Absolute screen coordinate, or relative to the window identified by title when that is given. width: Region width in pixels. height: Region height in pixels. title: Optional window title. When set, x/y are treated as offsets from that window's top-left corner (use list_windows to find the title).

Returns the region as a PNG image.

Read a text file. Returns up to limit lines starting at line offset (1-indexed offset, line 1 = offset 0).

Args: path: File path (absolute, or relative to the server's working dir). ~ is expanded. offset: Line number to start at (0 = first line). Use this to page through large files. limit: Maximum number of lines to return (default 2000).

Returns: path, content, total_lines, returned_lines, offset, truncated.

Write or append text to a file.

Args: path: Destination file path. ~ is expanded. content: Text content to write. append: If True, append to the file instead of overwriting. create_parents: Create parent directories if they do not exist.

Returns: path, bytes_written, appended.

List entries in a directory.

Args: path: Directory path (default: current directory). ~ is expanded. include_hidden: Include dotfiles/dotdirs (default False).

Returns: path, entries (name/path/type/size), count.

Create a directory.

Args: path: Directory path to create. ~ is expanded. parents: Create parent directories as needed (default True).

Returns: path, created, exists.

Move or rename a file or directory.

Args: path: Source path. destination: Destination path. overwrite: Overwrite destination if it exists (default False; errors otherwise).

Returns: source, destination, moved.

Delete a file or directory.

Args: path: Path to delete. Symlinks are unlinked (their targets are preserved). recursive: Required True to delete a directory tree. Files are deleted regardless of this flag.

Returns: path, deleted.

Return metadata for a file, directory, or symlink.

Returns: path, type, size, modified (ISO-8601 UTC), is_symlink, permissions.

Find files matching a glob pattern (recursive).

Args: path: Directory to search in (default current dir). pattern: Glob pattern, e.g. **/*.py, *.txt, src/**/*.json. include_hidden: Include dotfiles (default False). max_results: Cap on number of matches (default 500).

Returns: path, pattern, matches, count, truncated.

Search file contents for a regex pattern (recursive).

Args: path: Directory (or single file) to search. pattern: Regex pattern to search for (required). include_hidden: Include dotfiles (default False). file_glob: Only search files matching this glob (default *, all files). case_sensitive: Case-sensitive match (default False). max_matches: Cap on number of result lines (default 100). context_lines: Lines of context to include around each match (default 0).

Returns: path, pattern, file_glob, matches, count, files_scanned, truncated.

Capture a specific Qt widget by its objectName via the proxy agent.

Requires a Qt application that has called qt_mcp.agent.start_agent(window) and is connected to this server's Unix domain socket.

Args: widget_name: The widget's objectName. Use list_capturable_widgets to discover valid names.

Returns the widget as a PNG image.

List the objectNames of widgets in the attached Qt app.

Requires a Qt application that has called qt_mcp.agent.start_agent(window) and is connected to this server's Unix domain socket.

Returns: {"widgets": ["name1", ...], "count": N}.

Check whether a Qt app is currently attached via the proxy agent.

Always works, no error. Useful for clients to poll.

Returns: {"attached": bool, "socket_path": str}.