# MCP tools

Part of the Oya Browser docs. All of it: https://oyabrowser.com/docs.md

## analyze_page

Analyzes the current page. Returns the full page with every interactive element numbered, as markdown (the default), TOON or JSONL. The default is the one picked in the Oya Browser's settings, unless the server's `OYA_PAGE_FORMAT` pins one.

```
analyze_page()                  // markdown
analyze_page({ format: 'toon' }) // TOON: fewer tokens
analyze_page({ format: 'jsonl' }) // one JSON object per line
```

Returns:

- Page metadata, URL, title, viewport size, scroll position
- Full page content with element tags like `[#5 button "Submit"]` in markdown, or one `blocks[N]{id,region,kind,text,target,state}` row per block in TOON, or one JSON object per block in JSONL
- Element index, all elements listed with IDs, types, labels, visibility flags

Always call `analyze_page` before using `click` or `type`. Element IDs only exist after analysis and reset on every call.

## navigate

Navigate the browser to a URL.

```
navigate({ url: "https://example.com" })
```

After navigating, call `analyze_page` again, old element IDs are invalid on the new page.

## click

Click an interactive element by its ID number from `analyze_page`.

```
click({ element_id: 13 })
```

The element was tagged with `data-ac-id="13"` during analysis, so the click resolves via a single `querySelector`.

## type

Type text into an input element. Clears existing content first, then types character by character with realistic key events.

```
type({ element_id: 9, text: "hello world" })
```

## press_key

Press a keyboard key. Useful for submitting forms (Enter), dismissing dialogs (Escape), or navigating (Tab, arrows).

```
press_key({ key: "Enter" })
```

Supported keys: `Enter`, `Escape`, `Tab`, `Backspace`, `ArrowDown`, `ArrowUp`, or any character.

## screenshot

Capture the visible tab as a base64 PNG image.

```
screenshot()
```

## scroll

Scroll the page up or down.

```
scroll({ direction: "down", amount: 500 })
```

| Param | Type | Description |
| --- | --- | --- |
| `direction` | `"up"` \| `"down"` | Scroll direction |
| `amount` | number (optional) | Pixels to scroll, default 500 |

## Tab Management

### list_tabs

List all open tabs with ID, title, URL, and which is active.

```
list_tabs()
```

### open_tab

Open a new tab, optionally at a URL.

```
open_tab({ url: "https://gmail.com" })
```

### switch_tab

Switch to a tab by ID (from `list_tabs`).

```
switch_tab({ tab_id: 2 })
```

### close_tab

Close a tab. Closes the active tab if no ID specified.

```
close_tab({ tab_id: 3 })
```

## wait

Wait for an element matching a CSS selector to appear on the page.

```
wait({ selector: ".results", timeout: 10000 })
```