Tools exposed by Oryon MCP

Reference for all tools exposed by the Oryon MCP Server. For installation and client setup, see Setup.

The server runs in attach mode: the system under test (SUT) is the Java UI application, for example a Syrius FX/Swing client. It is started independently, with the Oryon agent listening on a known host and port, and the MCP server connects to it exactly as the Oryon IDE does.

Two conventions run through the whole tool set:

  • ref for interaction. Every element in a snapshot is tagged with a [ref], and all element-scoped tools take one. Refs are snapshot-scoped: take a fresh snapshot after any UI change, as refs from an older snapshot fail loudly rather than acting on the wrong element.
  • XPath for export. XPath is not used to drive the UI, only to persist a locator. Resolve one with oryon_get_xpath when you need to embed it in a generated Oryon script.

Interaction is fully generic: there is no tool per UI method. oryon_list_commands discovers at runtime what the connected module supports, and oryon_execute_command invokes it.

Connection

Tools that attach to, inspect, and detach from the running SUT. Attaching is attempted automatically on startup, so these are mainly needed to recover from a restart or a dropped connection.

oryon_status

Reports the connection status to the SUT: whether it is connected and ready, which Oryon agent module is in use, whether that module supports auto-wait, and whether a UI tree has been received. Takes no parameters.

oryon_connect

Connects (or reconnects) to the running SUT. Use it when the SUT was started or restarted after the MCP server, or to recover from a disconnect. Restarting the SUT and calling this again is the supported crash-recovery path. Takes no parameters.

oryon_disconnect

Detaches from the SUT without stopping it. Takes no parameters.

Inspection

Read-only tools that let an AI agent see the current state of the application, and turn what it sees into a durable locator.

Typical use cases:

  • Explore an unfamiliar application screen before deciding what to automate
  • Obtain the XPath of an element to embed in a generated Oryon script
  • Capture visual evidence of the current state

oryon_snapshot

Returns a compact snapshot of the current UI as a tree of elements, each tagged with a [ref] used to interact with it. Invisible elements and pure layout containers are left out, menus are collapsed to their number of items, and while a modal window is open only its content is shown.

Passing a ref returns the subtree of that element instead of the whole UI, which is useful to expand a collapsed menu and keeps the refs you already hold valid. Take a fresh snapshot without ref after any UI change.

Key parameters:

  • ref (optional; returns only that element’s subtree. Omit for the whole UI)

oryon_get_xpath

Resolves a snapshot ref to a robust Oryon XPath, produced by the same generator the IDE recorder uses, so a locator obtained here is as durable as an IDE-recorded one. This is the value to embed in a generated Oryon script.

Key parameters:

  • ref (required)

oryon_screenshot

Takes a screenshot of the whole SUT and returns it as a PNG image. Takes no parameters.

Interaction

Drives the application. Rather than mirroring every facade method as its own tool, the applicable commands of the connected module are discovered at runtime, through the same mechanism behind the IDE’s F6 popup. This keeps the tool surface small and works for any module.

Typical use cases:

  • Reproduce a manual scenario step by step to work out what a script needs to do
  • Drive the application to the state a test should start from
  • Read a value back from the UI to assert on it

A typical flow:

  1. Take a snapshot with oryon_snapshot.
  2. Discover what an element supports with oryon_list_commands.
  3. Act on it with oryon_execute_command, which returns a fresh snapshot when the UI changed.
  4. Resolve durable locators with oryon_get_xpath and assemble the script.
  5. Validate the result with oryon_run_script.

oryon_list_commands

Lists the commands that can be executed on the element referenced by ref (click, setText, setComboBoxSelection, getText, …), together with their parameters and return type. Commands are ordered by relevance, so element-specific ones come before generic ones. Call this before oryon_execute_command to discover what a given element supports.

Key parameters:

  • ref (required)

oryon_execute_command

Executes a command returned by oryon_list_commands on the element referenced by ref. Returns the command result and, when the UI actually changed, a fresh snapshot; the snapshot is omitted when nothing changed, which keeps pure queries such as getText cheap.

Key parameters:

  • ref (required)
  • command (required; the command name, as listed by oryon_list_commands)
  • args (optional; the arguments in the order listed. Omit for commands without arguments, and never include the target element itself, which is taken from the ref)

Scripting

Runs a Groovy script against the SUT with the same bindings it will have as an Oryon keyword, so a generated script can be validated in place before it is committed.

Typical use cases:

  • Validate a script the AI agent just generated, against the real application
  • Replay several steps in a single call instead of one command at a time

oryon_run_script

Runs a Groovy script against the SUT and reports its outcome: the output, the console, and on failure the error together with the failing script line. The script receives the same bindings as an Oryon keyword: gui (the facade: gui.click(xpath), gui.setText(xpath, text), …), session, input (the JSON passed in) and output (output.add(key, value)).

Elements are addressed by XPath here, not by ref, so use oryon_get_xpath to obtain one first. As for a command, a fresh snapshot is appended when the UI changed.

Key parameters:

  • script (required; the Groovy script source)
  • input (optional; a JSON object bound as input)
  • timeoutMs (optional, default 60000; how long the script may run before it is cancelled)