> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplink.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> Catalog of the uplink_* tools exposed by the Uplink MCP server

All tools are namespaced `uplink_*` so they don't collide with tools from other MCP servers. Group by purpose:

## Session lifecycle

### `uplink_connect`

Start a new Uplink session and return a 6-digit pairing code (primary) + URL (fallback).

**Input:**

* `projectId` *(string, optional)* — Uplink project ID. Defaults to the API key owner's Playground project.

**Returns:** `sessionId`, `linkUrl`, `relayUrl`, `jwt`, `pairingCode` (6 digits), `pairingCodeExpiresInSeconds`.

### `uplink_wait_for_device`

Block until a device pairs with the active session, then return its metadata.

**Input:**

* `timeout_ms` *(number, optional)* — How long to wait. Default 25000 (under the OTP TTL so the model can refresh the code if needed); max 600000.

**Returns:** `deviceId`, `deviceModel`, `platform`, `platformVersion`, `deviceType`.

### `uplink_refresh_pairing_code`

Mint a fresh 6-digit code for the active session — useful if the previous code expired (30s TTL) before pairing.

**Returns:** `code`, `ttlSeconds`.

### `uplink_get_qr`

Render the active session's pairing URL as an ASCII QR code for scanning. Opt-in — only called when the user explicitly asks.

### `uplink_session_status`

Return whether a session is active and whether a device is paired.

**Returns:** `connected` (bool), `sessionId`, `hasDevice` (bool).

## Page-driven tools

These dispatch to the same handlers the JavaScript SDK uses. They require an active paired session.

### `uplink_get_current_url`

Returns the current URL of the device's active page.

### `uplink_get_dom_snapshot`

Snapshot the DOM of the active device. Returns the body tree (formatted for LLM consumption) plus head metadata (title, base, meta tags, link rels).

### `uplink_evaluate_javascript`

Run a JS expression or statement block in the device's page context.

**Input:**

* `expression` *(string)* — JS to evaluate. Can be a single expression (`document.title`) or a statement block (`const r = await fetch(...); return r.json()`).

### `uplink_await_network_request`

Wait for the next network request whose URL contains `url_pattern`.

**Input:**

* `url_pattern` *(string)* — substring to match against the request URL.
* `timeout_ms` *(number, optional)* — default 15000, max 60000.

**Returns:** method, URL, status, headers, body preview.

### `uplink_run_script`

Execute a script against the device with `page` and `console` bound in scope. Returns counts of captured flows + logs plus any error.

**Input:**

* `code` *(string)* — JS source to execute.
* `wait_for_idle_ms` *(number, optional)* — settling window after script resolves; default 3000, max 10000.

## Inspection tools

The MCP server captures logs, network requests, and page commands in a per-session ring buffer. These tools query that buffer.

### `uplink_read_logs`

Return captured console logs from `uplink_run_script` invocations.

**Input:**

* `level` *(enum: log/info/warn/error/debug, optional)* — filter by level.
* `limit` *(number, optional)* — most-recent N entries.

### `uplink_search_network`

Search captured network requests by URL substring.

**Input:**

* `url_pattern` *(string)* — substring to match.
* `limit` *(number, optional)*.

**Returns:** matches with method, URL, status, headers, and body previews. Use `uplink_get_network_request` to fetch a single entry by id.

### `uplink_get_network_request`

Fetch a single captured network request by id (from `uplink_search_network`).

**Input:**

* `id` *(number)* — network request id.

### `uplink_list_commands`

List captured page commands (method, args, result/error, timing) emitted during `uplink_run_script`.

**Input:**

* `method` *(string, optional)* — filter by page method (e.g. `"goto"`, `"click"`).
* `limit` *(number, optional)*.

### `uplink_get_command_result`

Fetch a single captured command by id (from `uplink_list_commands`).

**Input:**

* `id` *(number)* — command id.

## Buffer sizes

The recorder retains:

* 1000 logs
* 500 network requests (with 1KB body previews; full bodies fetched on demand by id)
* 200 commands

Older entries evict FIFO when limits are hit.