Tools Reference

Victauri exposes 35 MCP tools organized into standalone tools (one action per call) and compound tools (multiple actions via an action parameter).

All tools are accessible via MCP at /mcp or REST at POST /api/tools/{tool_name}.

Common parameters. Every tool that touches a webview accepts webview_label (aliases window, window_label) to pick the window; without it the default window is used (main, else the first visible one). Every compound tool takes a required action string naming the operation.

Backend Tools

These tools access the Rust backend directly — no webview proxy, no JavaScript evaluation.

app_info

Get application configuration, directory paths, environment, discovered databases, and process info.

Parameters: None required.

Returns: {config, paths, databases, process, environment}

list_app_dir

Browse files in app backend directories (data, config, log, local_data).

Parameters:

Returns: {root, entries: [{name, path, is_dir, size, modified}]}

A listing stops (and reports truncated) at 10,000 returned entries, 100,000 examined entries, or 5 s — whichever comes first — so a pattern that matches nothing in a huge tree still returns.

read_app_file

Read a file from one of the app’s backend directories.

Parameters:

Returns: UTF-8 text, or base64-encoded bytes when binary is true. Path-traversal-guarded. A read truncated at max_bytes in the middle of a multi-byte character drops the partial character and stays UTF-8 text.

query_db

Execute a read-only SQL query against a SQLite database in the app’s data directory.

Parameters:

Examples:

{"query": "SELECT * FROM users WHERE active = ?", "params": [true]}
{"query": "SELECT count(*) FROM items", "path": "app.db"}

Returns: {columns, rows, row_count, truncated, max_rows}

Limits: a 5 MB result budget charged cell by cell (the result is truncated rather than built past it), at most 256 result columns, 1 MB per value, LIKE/GLOB patterns up to 1000 bytes, a 5 s CPU deadline, a 1 s wait for a lock held by the app, and at most two database calls (query_db / db_health) running at once — a third gets a “busy” error. Duplicate result column names get :N keys (a, a:1) so no value is lost; columns lists exactly the keys each row carries. A single string function (LIKE, replace, instr) is one uninterruptible SQLite step, so a pathological call can overrun the deadline by seconds on its worker thread; the tool call itself returns at the deadline.

Read-only and path-traversal-guarded: writes (INSERT/UPDATE/…), stacked queries, ATTACH, and the write form of PRAGMA (PRAGMA x = y) are rejected. By default only the OS app-data directories are searched; if your app stores its DB elsewhere (a project/working dir or custom path), register the directory via VictauriBuilder::db_search_paths(["../data", "/abs/path"]) — then relative names and absolute paths within those roots become reachable.

Webview & IPC Tools

eval_js

Evaluate JavaScript in the webview and return the result.

Parameters:

Examples:

{"code": "document.title"}
{"code": "document.querySelectorAll('button').length"}
{"code": "await fetch('/api/data').then(r => r.json())"}

Auto-return: a single bare expression is auto-wrapped with return (document.title → return document.title). Multi-statement code must include an explicit return — e.g. localStorage.setItem('k','v'); return localStorage.getItem('k') — or be wrapped in an IIFE; otherwise only the first statement runs. async/await is supported.

JavaScript errors (thrown exceptions) return an MCP error with isError: true. undefined returns "undefined", null returns null. A syntax error is reported at once as a JavaScript parse error (“the code did not begin executing”) — code reported that way never runs later. A result JSON cannot represent (a circular object, a BigInt, a function) is reported as “the code ran, but its result could not be serialized”, never as a JavaScript error. A page reload under the call fails it promptly. Targeting a hidden or unresponsive window fails fast (~2s); and if a prior eval timed out, the next call re-probes and fails fast if the webview reloaded or the app stopped responding.

dom_snapshot

Capture a full accessible DOM tree with ref handles for every element.

Parameters:

Returns: Tree of elements with ref, role, name, children, and bounding box data. Descends into open shadow DOM and same-origin iframes (cross-origin frames are marked and skipped).

find_elements

Search for elements by CSS selector or text content. Returns an MCP error for invalid CSS selectors. Searches into open shadow roots and same-origin iframes — frame elements get ref handles and are fully interactable.

Parameters:

Examples:

{"selector": "button.primary"}
{"text": "Submit"}
{"role": "heading"}

invoke_command

Invoke a Tauri command from the backend.

Parameters:

Example:

{"command": "get_settings", "args": {}}
{"command": "search_context", "args": {"query": "hello"}}

screenshot

Capture a PNG screenshot of the application window.

Parameters:

Returns: Base64-encoded PNG image data.

Linux: capture requires X11 or XWayland (the common case, including CI under xvfb). A pure-Wayland session exposes no safe per-window capture path, so screenshot returns a clear error there rather than a wrong or blank image. Windows and macOS capture natively.

verify_state

Compare frontend and backend state to detect drift.

Parameters:

Example:

{
  "frontend_expr": "document.title",
  "backend_state": {"title": "My App"}
}

detect_ghost_commands

Classify every command the frontend invoked by its observed outcome: a command that succeeded at least once provably has a handler (counted in verified_handlers); one that only ever failed with “not found” is listed in confirmed_ghosts; plugin:* built-ins are excluded_builtins; frontend_only is the weak tier (absent from the #[inspectable] registry, which is a subset of the real handler set). Read reliability and note before treating frontend_only as a bug list.

Parameters:

Returns: confirmed_ghosts (each {name, error}), verified_handlers (a count), frontend_only, excluded_builtins, registry_only, total_frontend_commands, total_registry_commands, reliability (none/low/high) and note.

check_ipc_integrity

Verify the health of IPC communication.

Parameters:

Returns: {healthy, total_calls, pending_count, stale_count, error_count, stale_calls, errored_calls, warning}

wait_for

Wait for a condition to become true, polling until timeout. Use the expression and event conditions to await async backend work to true completion instead of guessing with a fixed sleep.

Parameters:

Conditions for async completion:

• expression — polls a JS expression until truthy (or == expected). It may await, so you can await a fire-and-forget command’s status directly. Level-triggered and race-free; needs no app changes. Returns { ok, value, elapsed_ms }.
• event — blocks until a named Tauri event fires (evaluated against the captured event bus, with a since_ms look-back). The app must emit the event and Victauri must capture it via VictauriBuilder::listen_events. Returns { ok, event, elapsed_ms }.

Example:

{"condition": "selector", "value": ".modal.open", "timeout_ms": 3000}
{"condition": "url", "value": "/dashboard"}
{"condition": "expression", "value": "(await window.__TAURI_INTERNALS__.invoke('get_status')).running === false", "timeout_ms": 30000}
{"condition": "event", "value": "analysis-complete", "timeout_ms": 30000}

The robust async pattern is invoke_command(...) then wait_for(expression|event, ...).

app_state

Read application-defined backend state through a registered probe. Probes give an agent first-class, discoverable access to domain state (a scoring pipeline’s version and stale-item count, a queue’s depth, cache stats) that would otherwise require query_db + log-grepping. A probe runs in the Rust process with no IPC round-trip and no frontend involvement — direct-backend introspection a browser-external tool cannot do.

Apps register probes via VictauriBuilder::probe("name", || serde_json::json!({ … })) (build your shared state as an Arc once, clone it into both .manage() and the probe).

Parameters:

Example:

{}                       // → { "probes": ["scoring", "queue"] }
{"probe": "scoring"}     // → { "pipeline_version": 5, "stale_items": 0 }

assert_semantic

Assert a condition about the application state using JS expressions.

Parameters:

Example:

{
  "expression": "document.title",
  "condition": "equals",
  "expected": "My App"
}

resolve_command

Resolve a natural language description to registered commands.

Parameters:

Example:

{"query": "show settings"}

get_registry

List all registered commands with their metadata.

Parameters:

Each argument lists its Rust name, and — when it differs — the key the frontend invokes it by: Tauri camelCases argument names by default (size_kb → sizeKb), so pass key (or name when there is no key) in invoke_command’s args.

get_memory_stats

Get real OS process memory usage.

Parameters: None.

Returns: {working_set_bytes, peak_working_set_bytes, page_fault_count, page_file_bytes}

get_plugin_info

Get plugin version, uptime, configuration, and capabilities.

Parameters: None.

get_diagnostics

Get detailed diagnostic information about the plugin state.

Parameters: None.

Compound Tools

Compound tools use an action parameter to select the specific operation.

interact

Element interactions with Playwright-grade actionability checks. Works on elements inside same-origin iframes too (refs from a snapshot/find resolve across frame boundaries).

An action the page refuses — element covered, disabled, hidden, detached, not a <select>, or ref not found — is a tool error (MCP isError: true; REST {"error": …}) whose text is the reason followed by [hint: RETRY_LATER] (the UI may still settle) or [hint: CHECK_INPUT] (wrong target). The same applies to input, inspect (e.g. get_styles on an unknown ref) and route add. (Before 0.9.0 these came back as a successful {"ok": false, "error": …} result.)

Trusted (OS-level) clicks: add "trusted": true to click to deliver a real OS mouse event (isTrusted: true) at the element’s center, instead of a synthetic DOM event — for app handlers that gate on event.isTrusted or browser features needing user activation. Implemented on Windows (Win32 SendInput); on macOS/Linux it returns a clear “not implemented” error so you fall back to the default synthetic click. The window is brought to the foreground first.

Example:

{"action": "click", "ref_id": "e3"}
{"action": "click", "ref_id": "e3", "trusted": true}
{"action": "select_option", "ref_id": "e9", "value": "us"}

input

Text input and keyboard operations.

Trusted (OS-level) input: add "trusted": true to type_text or press_key to deliver real OS keystrokes (isTrusted: true) into the focused element instead of synthetic DOM events. The target element (ref_id) is focused first. Implemented on Windows (Win32 SendInput); macOS/Linux fall back to synthetic input with a clear error.

Example:

{"action": "fill", "ref_id": "e5", "value": "hello@example.com"}
{"action": "type_text", "ref_id": "e5", "text": "Hello"}
{"action": "type_text", "ref_id": "e5", "text": "Hello", "trusted": true}
{"action": "press_key", "key": "Enter"}

Supported keys: Tab, Escape, Enter, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, F1-F12, and any single character.

window

Window management operations.

introspectability answers “which windows can Victauri actually see?” A window that returns introspectable: false while visible: true is almost always missing the victauri:default capability — Tauri’s per-window permission ACL silently blocks the bridge’s callback IPC, so eval_js/dom_snapshot/animation/find_elements see nothing with no error. The diagnostic names the exact capability file to edit. Required per window (not just main).

Example:

{"action": "list"}
{"action": "get_state", "label": "main"}
{"action": "resize", "label": "main", "width": 1200, "height": 800}
{"action": "introspectability"}

storage

Browser storage operations.

Example:

{"action": "set", "key": "theme", "value": "dark"}
{"action": "get", "key": "theme"}

navigate

Navigation and history operations.

Example:

{"action": "go_to", "url": "https://example.com"}
{"action": "get_history"}
{"action": "set_dialog_response", "dialog_type": "confirm", "dialog_action": "accept"}

recording

Time-travel recording for session capture and replay.

replay semantics. Recordings do not capture call arguments, so replay re-invokes only calls that succeeded with no arguments. Calls that had arguments, failed, or never completed are reported as skipped with a reason; commands blocked by the privacy allow/blocklist are reported as blocked. passed means the re-invocation succeeded — the response is not diffed against the original (only its JSON type is reported). Re-invoked commands run for real, so their side effects happen again.

Each call is re-invoked in the window that recorded it — a window’s Tauri capabilities are its own — and is skipped if that window no longer exists (it never falls back to main); webview_label only filters which recorded calls are replayed. Calls that were fulfilled or blocked by a network route (route add, which page script can also use) are recorded as mocked and never replayed: they never reached the backend. (Script in the recording window can still rewrite what the recording captures from that window — see Security.)

Example:

{"action": "start"}
{"action": "checkpoint", "label": "after-login"}
{"action": "get_events", "since_index": 0}
{"action": "stop"}
{"action": "replay"}

inspect

CSS inspection, accessibility, and performance profiling.

Example:

{"action": "get_styles", "ref_id": "e3", "properties": ["color", "font-size"]}
{"action": "get_bounding_boxes", "ref_ids": ["e1", "e2", "e3"]}
{"action": "audit_accessibility"}
{"action": "get_performance"}

The accessibility audit checks: missing alt text, unlabeled form inputs, empty buttons/links, heading hierarchy, color contrast (WCAG AA), ARIA role validity, positive tabindex, and missing document language/title.

Performance metrics include: navigation timing, resource summary, paint timing (FP/FCP), JS heap usage, long task count, and DOM statistics.

css

CSS injection for debugging and prototyping.

Example:

{"action": "inject", "css": "* { outline: 1px solid red; }"}
{"action": "remove"}

logs

Access all captured logs from the application.

Example:

{"action": "console", "level": "error"}
{"action": "network"}
{"action": "slow_ipc", "threshold_ms": 100}

ipc/network/slow_ipc return at most 100 entries by default and truncate large per-entry bodies (4 KB) — pass an explicit limit for more.

route

Network request interception — the Playwright route() equivalent, implemented purely in the JS bridge (no CDP; the same behaviour on all three Tauri webviews, within the fetch/XHR limits below). Matches webview fetch/XHR by URL and blocks, mocks, or delays them. Rules are page-scoped (cleared on reload).

add parameters:

Example:

{"action": "add", "pattern": "/api/users", "behavior": "fulfill", "status": 200, "body": {"users": []}}
{"action": "add", "pattern": "analytics", "behavior": "block"}
{"action": "add", "pattern": "*/slow", "match_type": "glob", "behavior": "delay", "delay_ms": 2000}
{"action": "matches"}

Scope: fetch supports all behaviors; XHR supports block/delay (fulfill is fetch-only). Top-level navigation, sub-resources (img/css), and WebSocket frames are not intercepted.

Tauri IPC is observe-only. The app’s real invoke traffic (http://ipc.localhost/… on Windows, ipc://localhost/… on macOS/Linux) is logged (logs ipc, and a rule may even show up in matches), but a rule does not control it — Tauri serves real IPC below the JS fetch layer the bridge can reach, so the call still goes through, undelayed. The fault tool does not touch the app’s real frontend IPC either: it only applies to commands you drive through invoke_command. Neither tool can reproduce a failure a user clicking the UI would hit.

trace

Screencast / visual timeline — captures the window at a fixed interval into a ring buffer via the native screenshot path (no CDP). Pairs with recording (events) and logs (network/console) to form a Playwright-trace-style bundle.

start defaults: interval_ms 500 (min 50, max 60000), max_frames 60 (max 600). Set with_events: true to also start the event recorder so the trace bundles the IPC/DOM/console timeline alongside the screencast.

Limits and lifecycle:

• A trace auto-stops after 30 minutes (an abandoned trace must not capture forever).
• The frame buffer is a ring (max_frames) and is also capped at 256 MB total; the oldest frames are dropped first.
• frames returns the newest frames that fit a 25 MB response cap (with a note when it had to drop older ones) — pass a smaller limit to page.
• Hidden windows are skipped: a frame is only captured while the target window is visible (a native capture of a hidden window would return stale or another window’s pixels), so a hidden period shows up as a gap, not a wrong image.
• stop (or the 30-minute auto-stop) also ends the recording that with_events started; a recording you started separately with recording start is left alone. The stopped session stays readable via recording get_events / export.
• Frames come from the native screenshot path, so the platform limits of screenshot apply (Linux needs X11/XWayland).

Example:

{"action": "start", "interval_ms": 250, "max_frames": 40, "with_events": true}
{"action": "status"}
{"action": "stop"}
{"action": "frames", "limit": 10}

Backend Introspection (Victauri-Exclusive)

These tools exploit Victauri’s position inside the Rust process to provide insights and control that browser-external tools like CDP cannot access.

introspect

Deep backend introspection — command performance profiling, IPC contract testing, coverage analysis, startup timing, capability auditing, process enumeration, and event bus monitoring.

db_health report. Opens the database read-only and returns: journal_mode, page_count, page_size, db_size_mb, freelist_count; the table list with per-table row_count (counted under a 5 s budget — tables not reached get row_count: null and row_counts_complete: false; the listing is capped and flagged by tables_truncated); and integrity_check from SQLite PRAGMA quick_check under its own 5 s budget. When the file may contain virtual tables and the host app has registered a non-built-in virtual-table module, the check runs table by table over ordinary tables only (integrity_check_kind: "quick_check (per table)", reason in integrity_check_note), so no app-registered module code runs; otherwise integrity_check_note is null. On a large database quick_check may report "not completed: … exceeded its budget …" — that means unknown, not corrupt. It never checkpoints or inspects the -wal file (wal_checkpoint is reported as “not run (read-only diagnostics)” in WAL mode).

Examples:

{"action": "command_timings", "slow_threshold_ms": 100}
{"action": "coverage"}
{"action": "command_catalog"}
{"action": "contract_record", "command": "get_settings"}
{"action": "contract_check"}
{"action": "startup_timing"}
{"action": "capabilities"}
{"action": "db_health"}
{"action": "plugin_state"}
{"action": "processes"}
{"action": "plugin_tasks"}
{"action": "event_bus"}

fault

Probe a backend command handler under failure for chaos engineering.

Scope: faults apply only to commands you run via the invoke_command tool — they do not intercept the app’s real user-driven IPC (window.__TAURI_INTERNALS__.invoke), which Tauri serves below the JS layer Victauri can reach. Use fault to test a handler’s error path when you drive it (e.g. “does my error branch return the right shape on a DB failure?”). It does not reproduce a failure a user clicking the UI would experience — that path is not interceptable cross-platform without CDP.

Fault types:

• delay — sleep delay_ms (max 120 000), then run the command normally.
• error — return [FAULT INJECTED] command '<name>': <error_message> without running the command.
• drop — return {} without running the command.
• corrupt — run the command for real (side effects happen), then return a fixed marker instead of its result: {"__corrupted":true,"original_length":<n>,"fault":"corrupt"}.

Rules auto-expire 15 minutes after they are injected (so a forgotten fault cannot sabotage a later run — re-inject to refresh) or after max_triggers hits (0 = unlimited).

Examples:

{"action": "inject", "command": "get_settings", "fault_type": "delay", "delay_ms": 2000}
{"action": "inject", "command": "save_data", "fault_type": "error", "error_message": "disk full"}
{"action": "inject", "command": "fetch_feed", "fault_type": "drop", "max_triggers": 3}
{"action": "list"}
{"action": "clear_all"}

explain

Natural-language narration of what happened in the app. Aggregates recent events over a time window and produces human-readable summaries, causal chains, or diffs.

Event source. While a recording is active, explain reads the recorder-fed event log. When nothing is recording, it reads the JS bridge’s own event stream on demand (IPC, DOM mutations, console, network, navigation) for the requested window — without storing it, so a later recording never double-counts. Victauri’s own internal traffic is filtered out. Network requests are counted as state changes and navigations as window events in the tallies.

Parameters:

Examples:

{"action": "summary"}
{"action": "summary", "seconds": 60}
{"action": "last_action"}
{"action": "diff", "seconds": 15}

animation

Quantitative, deterministic, cross-platform access to the webview’s animation engine via the Web Animations API. Works identically on WebView2 / WKWebView / WebKitGTK with no CDP. Closes the last blind spot in agent perception — screenshots are frozen instants; this lets an agent perceive time-based behaviour.

Parameters:

Filmstrip + transparent windows: scrub’s filmstrip uses native window capture, which cannot see transparent / GPU-composited windows (no DWM redirection surface). On such a window the capture now fails with an actionable error rather than returning a blank frame — use an opaque window, or list / sample / scrub without capture.

Examples:

{"action": "list"}
{"action": "scrub", "selector": "#sweep-toast", "points": 6, "capture": true}
{"action": "sample", "selector": "#sweep-toast", "record": true}
{"action": "sample", "record": false}