@mastra/mcp-docs-server 1.1.22-alpha.12 → 1.1.22-alpha.13

package/.docs/docs/browser/agent-browser.md

@@ -0,0 +1,75 @@
+# AgentBrowser
+
+The `@mastra/agent-browser` package provides browser automation using Playwright with accessibility-first element targeting. Elements are identified by refs from the page's accessibility tree, making interactions reliable across different page layouts.
+
+## When to use AgentBrowser
+
+Use AgentBrowser when you need:
+
+- Reliable element targeting through accessibility refs
+- Fine-grained control over browser actions
+- Playwright's robust automation capabilities
+- Support for keyboard shortcuts and complex interactions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/agent-browser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agent-browser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agent-browser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agent-browser
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  headless: false,
+})
+
+export const browserAgent = new Agent({
+  id: 'browser-agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions: `You are a web automation assistant.
+
+When interacting with pages:
+1. Use browser_snapshot to get the current page state and element refs
+2. Use the refs (like @e1, @e2) to target elements for clicks and typing
+3. After actions, take another snapshot to verify the result`,
+})
+```
+
+## Element refs
+
+AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.
+
+> **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/docs/browser/overview.md

@@ -0,0 +1,136 @@
+# Browser overview
+
+Browser support enables agents to navigate websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap popular browser automation libraries.
+
+Mastra supports two browser SDK providers:
+
+- [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
+- [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+
+## When to use browser
+
+Use browser when your agent needs to:
+
+- Navigate websites and interact with page elements
+- Fill out forms and submit data
+- Extract structured data from web pages
+- Automate multi-step web workflows
+- Take actions that require a real browser (JavaScript rendering, authentication flows)
+
+## How it works
+
+When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser: navigating to URLs, selecting elements, typing text, and reading page content.
+
+Each provider offers a different set of tools optimized for its approach.
+
+## Quickstart
+
+Install your provider of choice, for this example you'll use the AgentBrowser provider.
+
+**npm**:
+
+```bash
+npm install @mastra/agent-browser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agent-browser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agent-browser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agent-browser
+```
+
+Create a new browser instance:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  headless: false,
+})
+```
+
+Assign the browser to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { browser } from '../browsers'
+
+export const webAgent = new Agent({
+  id: 'web-agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions:
+    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
+})
+```
+
+The agent automatically receives all browser tools from the provider.
+
+## Cloud providers
+
+Both SDK providers support connecting to cloud browser services instead of launching a local browser.
+
+### Browserbase (Stagehand native)
+
+Stagehand has native Browserbase integration:
+
+```typescript
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+})
+```
+
+### CDP URL (any provider)
+
+Connect to any browser exposing a Chrome DevTools Protocol (CDP) endpoint:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  cdpUrl: process.env.BROWSER_CDP_URL,
+  headless: true,
+})
+```
+
+This works with any [CDP-compatible](https://chromedevtools.github.io/devtools-protocol/) browser service.
+
+## Screencast
+
+Browser providers stream a live video feed of the browser to the Mastra Studio UI. This lets you watch the agent interact with pages in real-time.
+
+Screencast is enabled by default and can be configured:
+
+```typescript
+const browser = new AgentBrowser({
+  screencast: {
+    enabled: true,
+    format: 'jpeg',
+    quality: 80,
+    maxWidth: 1280,
+    maxHeight: 720,
+  },
+})
+```
+
+## Next steps
+
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/browser/stagehand.md

@@ -0,0 +1,128 @@
+# Stagehand
+
+The `@mastra/stagehand` package provides browser automation using the [Stagehand SDK](https://docs.browserbase.com/stagehand/introduction) from Browserbase. Stagehand uses AI to understand page context and locate elements, enabling natural language descriptions instead of explicit selectors.
+
+## When to use Stagehand
+
+Use Stagehand when you need:
+
+- Natural language element targeting ("select the login button")
+- AI-powered data extraction from pages
+- Native Browserbase cloud integration
+- Simpler tool interface for common actions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/stagehand
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/stagehand
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/stagehand
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/stagehand
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  headless: false,
+  model: 'openai/gpt-5.4',
+})
+
+export const stagehandAgent = new Agent({
+  id: 'stagehand-agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions: `You are a web automation assistant.
+
+Use stagehand tools to interact with pages:
+- stagehand_navigate to go to URLs
+- stagehand_act to perform actions described in natural language
+- stagehand_extract to get structured data from the page
+- stagehand_observe to find available actions on the page`,
+})
+```
+
+## Natural language actions
+
+When the agent uses the `stagehand_act` tool, it accepts natural language descriptions of actions:
+
+- "Press the Sign In button"
+- "Type `'[user@example.com](mailto:user@example.com)'` in the email field"
+- "Select 'United States' from the country dropdown"
+
+Stagehand's AI interprets the action and finds the appropriate element on the page.
+
+## Data extraction
+
+When the agent uses the `stagehand_extract` tool, it can pull structured data from pages.
+
+Example instruction: "Extract the product name, price, and availability"
+
+The tool returns structured data based on page content:
+
+```json
+{
+  "name": "Widget Pro",
+  "price": "$29.99",
+  "availability": "In Stock"
+}
+```
+
+## Observing actions
+
+When the agent uses the `stagehand_observe` tool, it analyzes the current page and returns possible actions.
+
+Example instruction: "What actions can I take on this login form?"
+
+Returns a list of available actions:
+
+```json
+[
+  { "action": "Press 'Sign In' button", "element": "button" },
+  { "action": "Type in 'Email' field", "element": "input" },
+  { "action": "Open 'Forgot Password' link", "element": "a" }
+]
+```
+
+## Browserbase
+
+Stagehand has native Browserbase integration for cloud browser infrastructure:
+
+```typescript
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+  model: 'openai/gpt-5.4',
+})
+```
+
+> **Note:** See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser)

package/.docs/reference/browser/agent-browser.md

@@ -0,0 +1,374 @@
+# AgentBrowser class
+
+The `AgentBrowser` class provides deterministic browser automation using the [agent-browser](https://github.com/vercel-labs/agent-browser) library. It uses accessibility tree snapshots and element refs (e.g., `@e5`) for precise, reproducible interactions.
+
+Use `AgentBrowser` when you need reliable, deterministic browser automation. For AI-powered interactions using natural language, see [`StagehandBrowser`](https://mastra.ai/reference/browser/stagehand-browser).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  scope: 'thread',
+})
+
+export const browserAgent = new Agent({
+  name: 'browser-agent',
+  instructions: `You can browse the web. Use browser_snapshot to see the page structure,
+then interact with elements using their refs (e.g., @e5).`,
+  model: 'openai/gpt-5.4',
+  browser,
+})
+```
+
+## Constructor parameters
+
+**headless** (`boolean`): Whether to run the browser in headless mode (no visible UI). (Default: `true`)
+
+**viewport** (`{ width: number; height: number }`): Browser viewport dimensions. (Default: `{ width: 1280, height: 720 }`)
+
+**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `30000`)
+
+**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL for connecting to an existing browser. Useful for cloud browser providers.
+
+**scope** (`'shared' | 'thread'`): Browser instance scope. 'shared' shares one browser across all threads. 'thread' gives each thread its own browser. (Default: `'thread' (or 'shared' when cdpUrl is provided)`)
+
+**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser is ready.
+
+**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked before the browser closes.
+
+**screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
+
+## Tools
+
+`AgentBrowser` provides 15 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
+
+### Core tools
+
+| Tool               | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `browser_goto`     | Navigate to a URL                                 |
+| `browser_snapshot` | Get accessibility tree snapshot with element refs |
+| `browser_click`    | Click an element by ref                           |
+| `browser_type`     | Type text into an element                         |
+| `browser_press`    | Press keyboard keys                               |
+| `browser_select`   | Select option from dropdown                       |
+| `browser_scroll`   | Scroll the page or element                        |
+| `browser_close`    | Close the browser                                 |
+
+### Extended tools
+
+| Tool               | Description                                     |
+| ------------------ | ----------------------------------------------- |
+| `browser_hover`    | Hover over an element                           |
+| `browser_back`     | Go back in browser history                      |
+| `browser_dialog`   | Handle browser dialogs (alert, confirm, prompt) |
+| `browser_wait`     | Wait for element state changes                  |
+| `browser_tabs`     | Manage browser tabs (list, new, switch, close)  |
+| `browser_drag`     | Drag and drop elements                          |
+| `browser_evaluate` | Execute JavaScript in the page (escape hatch)   |
+
+## Tool reference
+
+### `browser_goto`
+
+Navigate to a URL.
+
+```text
+// Tool input
+{
+  "url": "https://example.com",
+  "waitUntil": "domcontentloaded",
+  "timeout": 30000
+}
+```
+
+| Parameter   | Type                                            | Description                                     |
+| ----------- | ----------------------------------------------- | ----------------------------------------------- |
+| `url`       | `string`                                        | URL to navigate to                              |
+| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
+| `timeout`   | `number`                                        | Navigation timeout in ms (optional)             |
+
+### `browser_snapshot`
+
+Get an accessibility tree snapshot of the page. Returns element refs like `@e5` that you use with other tools.
+
+```text
+// Tool input
+{
+  "interactiveOnly": true,
+  "maxDepth": 10
+}
+```
+
+| Parameter         | Type      | Description                                  |
+| ----------------- | --------- | -------------------------------------------- |
+| `interactiveOnly` | `boolean` | Only include interactive elements (optional) |
+| `maxDepth`        | `number`  | Maximum tree depth (optional)                |
+
+**Example output:**
+
+```text
+[document] Example Page
+  [banner]
+    [link @e1] Home
+    [link @e2] About
+  [main]
+    [heading @e3] Welcome
+    [textbox @e4] Search...
+    [button @e5] Submit
+```
+
+### `browser_click`
+
+Click an element using its ref from the snapshot.
+
+```text
+{
+  "ref": "@e5",
+  "button": "left",
+  "clickCount": 1,
+  "modifiers": ["Control", "Shift"]
+}
+```
+
+| Parameter    | Type                            | Description                                    |
+| ------------ | ------------------------------- | ---------------------------------------------- |
+| `ref`        | `string`                        | Element ref from snapshot (required)           |
+| `button`     | `"left" \| "right" \| "middle"` | Mouse button (optional)                        |
+| `clickCount` | `number`                        | Number of activations, 2 for double (optional) |
+| `modifiers`  | `string[]`                      | Modifier keys (optional)                       |
+
+### `browser_type`
+
+Type text into an input element.
+
+```text
+// Tool input
+{
+  "ref": "@e4",
+  "text": "search query",
+  "clear": true,
+  "delay": 50
+}
+```
+
+| Parameter | Type      | Description                               |
+| --------- | --------- | ----------------------------------------- |
+| `ref`     | `string`  | Element ref from snapshot (required)      |
+| `text`    | `string`  | Text to type (required)                   |
+| `clear`   | `boolean` | Clear existing content first (optional)   |
+| `delay`   | `number`  | Delay between keystrokes in ms (optional) |
+
+### `browser_press`
+
+Press keyboard keys.
+
+```text
+// Tool input
+{
+  "key": "Enter",
+  "modifiers": ["Control"]
+}
+
+// Key combinations
+{ "key": "Control+a" }
+{ "key": "Control+c" }
+```
+
+| Parameter   | Type       | Description                                                       |
+| ----------- | ---------- | ----------------------------------------------------------------- |
+| `key`       | `string`   | Key name (e.g., "Enter", "Tab", "Escape", "Control+a") (required) |
+| `modifiers` | `string[]` | Modifier keys (optional)                                          |
+
+### `browser_select`
+
+Select an option from a dropdown. Provide one of `value`, `label`, or `index`.
+
+```text
+// Tool input - by value
+{
+  "ref": "@e10",
+  "value": "option-value"
+}
+
+// Tool input - by label
+{
+  "ref": "@e10",
+  "label": "Option Text"
+}
+
+// Tool input - by index
+{
+  "ref": "@e10",
+  "index": 0
+}
+```
+
+### `browser_scroll`
+
+Scroll the page or a specific element.
+
+```text
+// Tool input
+{
+  "direction": "down",
+  "amount": 300,
+  "ref": "@e15"
+}
+```
+
+| Parameter   | Type                                  | Description                                           |
+| ----------- | ------------------------------------- | ----------------------------------------------------- |
+| `direction` | `"up" \| "down" \| "left" \| "right"` | Scroll direction (required)                           |
+| `amount`    | `number`                              | Pixels to scroll, default 300 (optional)              |
+| `ref`       | `string`                              | Element to scroll, scrolls page if omitted (optional) |
+
+### `browser_hover`
+
+Hover over an element to trigger hover effects.
+
+```text
+// Tool input
+{
+  "ref": "@e7"
+}
+```
+
+### `browser_back`
+
+Go back in browser history.
+
+```text
+// Tool input (no parameters required)
+
+```
+
+### `browser_dialog`
+
+Handle browser dialogs (alert, confirm, prompt). Click an element that triggers a dialog and handle it.
+
+```text
+// Tool input
+{
+  "triggerRef": "@e5",
+  "action": "accept",
+  "text": "response"
+}
+```
+
+| Parameter    | Type                    | Description                                 |
+| ------------ | ----------------------- | ------------------------------------------- |
+| `triggerRef` | `string`                | Element that triggers the dialog (required) |
+| `action`     | `"accept" \| "dismiss"` | How to handle the dialog (required)         |
+| `text`       | `string`                | Text for prompt dialogs (optional)          |
+
+### `browser_wait`
+
+Wait for an element to reach a specific state.
+
+```text
+// Tool input
+{
+  "ref": "@e20",
+  "state": "visible",
+  "timeout": 30000
+}
+```
+
+| Parameter | Type                                                | Description                        |
+| --------- | --------------------------------------------------- | ---------------------------------- |
+| `ref`     | `string`                                            | Element ref to wait for (optional) |
+| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | State to wait for (optional)       |
+| `timeout` | `number`                                            | Max wait time in ms (optional)     |
+
+### `browser_tabs`
+
+Manage browser tabs.
+
+```text
+// List all tabs
+{ "action": "list" }
+
+// Open new tab
+{ "action": "new", "url": "https://example.com" }
+
+// Switch to tab by index
+{ "action": "switch", "index": 0 }
+
+// Close tab by index
+{ "action": "close", "index": 1 }
+```
+
+### `browser_drag`
+
+Drag an element to a target location.
+
+```text
+// Tool input
+{
+  "sourceRef": "@e10",
+  "targetRef": "@e20"
+}
+```
+
+| Parameter   | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `sourceRef` | `string` | Element to drag (required)     |
+| `targetRef` | `string` | Drop target element (required) |
+
+### `browser_evaluate`
+
+Execute JavaScript in the page context. Use as an escape hatch when other tools don't cover your use case.
+
+```text
+// Tool input
+{
+  "script": "document.title",
+  "returnValue": true
+}
+```
+
+| Parameter     | Type      | Description                             |
+| ------------- | --------- | --------------------------------------- |
+| `script`      | `string`  | JavaScript to execute (required)        |
+| `returnValue` | `boolean` | Whether to return the result (optional) |
+
+### `browser_close`
+
+Close the browser and clean up resources.
+
+```text
+// Tool input (no parameters required)
+
+```
+
+## How refs work
+
+The `browser_snapshot` tool returns an accessibility tree with element refs like `@e1`, `@e2`, etc. These refs are stable identifiers you use with other tools:
+
+1. Call `browser_snapshot` to see the page structure
+2. Find the element you want to interact with
+3. Use its ref with interaction tools like `browser_type` or `browser_scroll`.
+
+```text
+// 1. Get snapshot
+// Returns: [textbox @e4] Search... [link @e5] Home
+
+// 2. Type in the search box
+{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }
+
+// 3. Navigate to home
+{ "tool": "browser_goto", "input": { "url": "https://example.com" } }
+```
+
+## Related
+
+- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class reference
+- [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser): AI-powered alternative
+- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide
+- [agent-browser guide](https://mastra.ai/docs/browser/agent-browser): Usage guide

package/.docs/reference/browser/mastra-browser.md

@@ -0,0 +1,284 @@
+# MastraBrowser class
+
+The `MastraBrowser` class is the abstract base class for browser automation providers. It defines the common interface for launching browsers, managing thread isolation, streaming screencasts, and handling input events.
+
+You don't instantiate `MastraBrowser` directly. Instead, use a provider implementation:
+
+- [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser): Deterministic browser automation using refs
+- [`StagehandBrowser`](https://mastra.ai/reference/browser/stagehand-browser): AI-powered browser automation using natural language
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  scope: 'thread',
+})
+
+export const browserAgent = new Agent({
+  name: 'browser-agent',
+  instructions: 'You can browse the web to find information.',
+  model: 'openai/gpt-5.4',
+  browser,
+})
+```
+
+## Constructor parameters
+
+**headless** (`boolean`): Whether to run the browser in headless mode (no visible UI). (Default: `true`)
+
+**viewport** (`{ width: number; height: number }`): Browser viewport dimensions. Controls the size of the browser window. (Default: `{ width: 1280, height: 720 }`)
+
+**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+
+**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL, HTTP endpoint, or sync/async provider function. When provided, connects to an existing browser instead of launching a new one. HTTP endpoints are resolved to WebSocket internally. Can't be used with scope: 'thread' (automatically uses shared scope).
+
+**scope** (`'shared' | 'thread'`): Browser instance scope across threads. 'shared' means all threads share a single browser instance. 'thread' means each thread gets its own browser instance (full isolation). (Default: `'thread' (or 'shared' when cdpUrl is provided)`)
+
+**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser reaches 'ready' status.
+
+**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked before the browser is closed.
+
+**screencast** (`ScreencastOptions`): Configuration for streaming browser frames.
+
+**screencast.format** (`'jpeg' | 'png'`): Image format for screencast frames.
+
+**screencast.quality** (`number`): Image quality (1-100). Only applies to JPEG format.
+
+**screencast.maxWidth** (`number`): Maximum width for screencast frames.
+
+**screencast.maxHeight** (`number`): Maximum height for screencast frames.
+
+**screencast.everyNthFrame** (`number`): Capture every Nth frame to reduce bandwidth.
+
+## Properties
+
+The following properties (`id`, `name`, `provider`) are abstract and must be defined by concrete provider implementations:
+
+**id** (`string`): Unique identifier for this browser instance. Abstract - defined by provider.
+
+**name** (`string`): Human-readable name of the browser provider (e.g., 'AgentBrowser', 'StagehandBrowser'). Abstract - defined by provider.
+
+**provider** (`string`): Provider identifier (e.g., 'vercel-labs/agent-browser', 'browserbase/stagehand'). Abstract - defined by provider.
+
+**headless** (`boolean`): Whether the browser is running in headless mode.
+
+**status** (`BrowserStatus`): Current browser status: 'pending', 'launching', 'ready', 'error', 'closing', or 'closed'.
+
+## Methods
+
+### Lifecycle
+
+#### `ensureReady()`
+
+Ensures the browser is launched and ready for use. Automatically called before tool execution. Implemented in the base class.
+
+```typescript
+await browser.ensureReady()
+```
+
+#### `close()`
+
+Closes the browser and cleans up all resources. Implemented in the base class with race-condition-safe handling.
+
+```typescript
+await browser.close()
+```
+
+#### `isBrowserRunning()`
+
+Checks if the browser is currently running.
+
+```typescript
+const isRunning = browser.isBrowserRunning()
+```
+
+**Returns:** `boolean`
+
+### Thread management
+
+#### `setCurrentThread(threadId)`
+
+Sets the current thread ID for browser operations. Used internally by the agent runtime.
+
+```typescript
+browser.setCurrentThread('thread-123')
+```
+
+#### `getCurrentThread()`
+
+Gets the current thread ID.
+
+```typescript
+const threadId = browser.getCurrentThread()
+```
+
+**Returns:** `string`
+
+#### `hasThreadSession(threadId)`
+
+Checks if a thread has an active browser session.
+
+```typescript
+const hasSession = browser.hasThreadSession('thread-123')
+```
+
+**Returns:** `boolean`
+
+#### `closeThreadSession(threadId)`
+
+Closes a specific thread's browser session. For 'thread' scope, this closes that thread's browser instance. For 'shared' scope, this clears the thread's state.
+
+```typescript
+await browser.closeThreadSession('thread-123')
+```
+
+### Tools
+
+#### `getTools()`
+
+Returns the browser tools for use with agents. Each provider returns different tools based on its paradigm.
+
+```typescript
+const tools = browser.getTools()
+```
+
+**Returns:** `Record<string, Tool>`
+
+### Screencast
+
+#### `startScreencast(options?, threadId?)`
+
+Starts streaming browser frames. Returns a `ScreencastStream` that emits frame events.
+
+```typescript
+const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')
+
+stream.on('frame', frame => {
+  console.log('Frame received:', frame.data.length, 'bytes')
+})
+
+stream.on('stop', reason => {
+  console.log('Screencast stopped:', reason)
+})
+```
+
+**Returns:** `Promise<ScreencastStream>`
+
+### Input injection
+
+#### `injectMouseEvent(params, threadId?)`
+
+Injects a mouse event into the browser. Used by Studio for live interaction.
+
+```typescript
+await browser.injectMouseEvent({
+  type: 'mousePressed',
+  x: 100,
+  y: 200,
+  button: 'left',
+  clickCount: 1,
+})
+```
+
+#### `injectKeyboardEvent(params, threadId?)`
+
+Injects a keyboard event into the browser. Used by Studio for live interaction.
+
+```typescript
+await browser.injectKeyboardEvent({
+  type: 'keyDown',
+  key: 'Enter',
+  code: 'Enter',
+})
+```
+
+### State
+
+#### `getState(threadId?)`
+
+Gets the current browser state including URL and tabs.
+
+```typescript
+const state = await browser.getState('thread-123')
+console.log('Current URL:', state.currentUrl)
+console.log('Tabs:', state.tabs)
+```
+
+**Returns:** `Promise<BrowserState>`
+
+```typescript
+interface BrowserState {
+  currentUrl: string | null
+  tabs: BrowserTabState[]
+  activeTabIndex: number
+}
+
+interface BrowserTabState {
+  id: string
+  url: string
+  title: string
+}
+```
+
+#### `getCurrentUrl(threadId?)`
+
+Gets the current page URL.
+
+```typescript
+const url = await browser.getCurrentUrl()
+```
+
+**Returns:** `Promise<string | null>`
+
+## Browser scope
+
+The `scope` option controls how browser instances are shared across conversation threads:
+
+| Scope      | Description                                 | Use case                                 |
+| ---------- | ------------------------------------------- | ---------------------------------------- |
+| `'shared'` | All threads share a single browser instance | Cost-efficient for non-conflicting tasks |
+| `'thread'` | Each thread gets its own browser instance   | Full isolation for concurrent users      |
+
+```typescript
+// Shared browser for all threads
+const sharedBrowser = new AgentBrowser({
+  scope: 'shared',
+})
+
+// Isolated browser per thread
+const isolatedBrowser = new AgentBrowser({
+  scope: 'thread',
+})
+```
+
+When using `cdpUrl` to connect to an external browser, the scope automatically falls back to `'shared'` since you can't spawn new browser instances.
+
+## Cloud browser providers
+
+Connect to cloud browser services using the `cdpUrl` option:
+
+```typescript
+// Static CDP URL
+const browser = new AgentBrowser({
+  cdpUrl: 'wss://browser.example.com/ws',
+})
+
+// Dynamic CDP URL (e.g., session-based)
+const browser = new AgentBrowser({
+  cdpUrl: async () => {
+    const session = await createBrowserSession()
+    return session.wsUrl
+  },
+})
+```
+
+## Related
+
+- [AgentBrowser](https://mastra.ai/reference/browser/agent-browser): Deterministic browser automation
+- [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser): AI-powered browser automation
+- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide to browser automation

package/.docs/reference/browser/stagehand-browser.md

@@ -0,0 +1,290 @@
+# StagehandBrowser class
+
+The `StagehandBrowser` class provides AI-powered browser automation using [Stagehand](https://github.com/browserbase/stagehand). It uses natural language instructions for interactions instead of element refs.
+
+Use `StagehandBrowser` when you want AI to interpret and execute browser actions from natural language. For deterministic automation using element refs, see [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  headless: true,
+  model: 'openai/gpt-5.4',
+  selfHeal: true,
+})
+
+export const browserAgent = new Agent({
+  name: 'browser-agent',
+  instructions: `You can browse the web using natural language.
+Use stagehand_act to perform actions like "click the login button".
+Use stagehand_extract to get data from pages.`,
+  model: 'openai/gpt-5.4',
+  browser,
+})
+```
+
+## Constructor parameters
+
+**headless** (`boolean`): Whether to run the browser in headless mode. (Default: `true`)
+
+**viewport** (`{ width: number; height: number }`): Browser viewport dimensions. (Default: `{ width: 1280, height: 720 }`)
+
+**env** (`'LOCAL' | 'BROWSERBASE'`): Environment to run the browser in. Use 'BROWSERBASE' for cloud execution. (Default: `'LOCAL'`)
+
+**apiKey** (`string`): Browserbase API key. Required when env is 'BROWSERBASE'.
+
+**projectId** (`string`): Browserbase project ID. Required when env is 'BROWSERBASE'.
+
+**model** (`string | ModelConfiguration`): Model configuration for AI operations. Can be a string like 'openai/gpt-5.4' or an object with modelName, apiKey, and baseURL. (Default: `'openai/gpt-5.4'`)
+
+**selfHeal** (`boolean`): Enable self-healing selectors. When enabled, Stagehand uses AI to find elements even when initial selectors fail. (Default: `true`)
+
+**domSettleTimeout** (`number`): Timeout in milliseconds for DOM to settle after actions. (Default: `5000`)
+
+**verbose** (`0 | 1 | 2`): Logging verbosity level. 0 = silent, 1 = errors only, 2 = verbose. (Default: `1`)
+
+**systemPrompt** (`string`): Custom system prompt for AI operations.
+
+**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL or HTTP endpoint for connecting to an existing browser. HTTP endpoints are resolved to WebSocket internally.
+
+**scope** (`'shared' | 'thread'`): Browser instance scope across threads. (Default: `'thread' (or 'shared' when cdpUrl is provided)`)
+
+**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+
+**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser is ready.
+
+**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked before the browser closes.
+
+**screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
+
+## Tools
+
+`StagehandBrowser` provides 6 AI-powered tools for browser automation:
+
+| Tool                 | Description                                         |
+| -------------------- | --------------------------------------------------- |
+| `stagehand_act`      | Perform actions using natural language instructions |
+| `stagehand_extract`  | Extract structured data from pages                  |
+| `stagehand_observe`  | Discover actionable elements on a page              |
+| `stagehand_navigate` | Navigate to a URL                                   |
+| `stagehand_tabs`     | Manage browser tabs                                 |
+| `stagehand_close`    | Close the browser                                   |
+
+## Tool reference
+
+### `stagehand_act`
+
+Perform an action using natural language instructions. The AI interprets your instruction and executes the appropriate browser action.
+
+```text
+// Tool input
+{
+  "instruction": "click the login button",
+  "variables": { "username": "john" },
+  "useVision": true,
+  "timeout": 30000
+}
+
+// With variable substitution
+{
+  "instruction": "type %email% into the email field",
+  "variables": { "email": "user@example.com" }
+}
+```
+
+| Parameter     | Type                     | Description                                          |
+| ------------- | ------------------------ | ---------------------------------------------------- |
+| `instruction` | `string`                 | Natural language instruction (required)              |
+| `variables`   | `Record<string, string>` | Variables for %variableName% substitution (optional) |
+| `useVision`   | `boolean`                | Enable vision capabilities (optional)                |
+| `timeout`     | `number`                 | Timeout in ms (optional)                             |
+
+**Returns:**
+
+```typescript
+interface ActResult {
+  success: boolean
+  message?: string
+  action?: string
+  url?: string
+}
+```
+
+### `stagehand_extract`
+
+Extract structured data from a page using natural language instructions.
+
+```text
+// Basic extraction
+{
+  "instruction": "extract all product names and prices"
+}
+
+// With schema for structured output
+{
+  "instruction": "extract the product information",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "price": { "type": "number" },
+      "inStock": { "type": "boolean" }
+    }
+  }
+}
+```
+
+**Returns:**
+
+```typescript
+interface ExtractResult<T = unknown> {
+  success: boolean
+  data?: T
+  hint?: string
+  error?: string
+  url?: string
+}
+```
+
+### `stagehand_observe`
+
+Discover actionable elements on a page. Returns a list of elements with their selectors and descriptions.
+
+```text
+// Find specific elements
+{
+  "instruction": "find all buttons related to checkout"
+}
+
+// Find all interactive elements
+{
+  "onlyVisible": true
+}
+```
+
+| Parameter     | Type      | Description                                               |
+| ------------- | --------- | --------------------------------------------------------- |
+| `instruction` | `string`  | Natural language instruction (optional, omit to find all) |
+| `onlyVisible` | `boolean` | Only include visible elements (optional)                  |
+| `timeout`     | `number`  | Timeout in ms (optional)                                  |
+
+**Returns:**
+
+```typescript
+interface ObserveResult {
+  success: boolean
+  actions: StagehandAction[]
+  url?: string
+}
+
+interface StagehandAction {
+  selector: string
+  description: string
+  method?: string
+  arguments?: string[]
+}
+```
+
+### `stagehand_navigate`
+
+Navigate to a URL.
+
+```text
+// Tool input
+{
+  "url": "https://example.com",
+  "waitUntil": "domcontentloaded"
+}
+```
+
+| Parameter   | Type                                            | Description                                     |
+| ----------- | ----------------------------------------------- | ----------------------------------------------- |
+| `url`       | `string`                                        | URL to navigate to (required)                   |
+| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
+
+### `stagehand_tabs`
+
+Manage browser tabs.
+
+```text
+// List all tabs
+{ "action": "list" }
+
+// Open new tab
+{ "action": "new", "url": "https://example.com" }
+
+// Switch to tab by index
+{ "action": "switch", "index": 0 }
+
+// Close tab by index (or current if omitted)
+{ "action": "close", "index": 1 }
+```
+
+### `stagehand_close`
+
+Close the browser and clean up resources.
+
+```text
+// Tool input (no parameters required)
+
+```
+
+## Using Browserbase
+
+Run Stagehand in the cloud using Browserbase:
+
+```typescript
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+  model: 'openai/gpt-5.4',
+})
+```
+
+## Model configuration
+
+Configure the AI model for Stagehand operations:
+
+```typescript
+// String format: "provider/model"
+const browser = new StagehandBrowser({
+  model: 'openai/gpt-5.4',
+})
+
+// Object format for custom configuration
+const browser = new StagehandBrowser({
+  model: {
+    modelName: 'gpt-5.4',
+    apiKey: process.env.OPENAI_API_KEY,
+    baseURL: 'https://api.openai.com/v1',
+  },
+})
+```
+
+Supported providers:
+
+- OpenAI: `"openai/gpt-5.4"`, `"openai/gpt-5.4-mini"`
+- Anthropic: `"anthropic/claude-3-5-sonnet-20241022"`
+
+## AgentBrowser vs StagehandBrowser
+
+| Aspect          | AgentBrowser               | StagehandBrowser      |
+| --------------- | -------------------------- | --------------------- |
+| **Approach**    | Deterministic refs (`@e5`) | Natural language      |
+| **Precision**   | Exact element targeting    | AI interpretation     |
+| **Flexibility** | Requires a snapshot first  | Direct instructions   |
+| **Use case**    | Reproducible automation    | Adaptive automation   |
+| **Speed**       | Faster (no AI inference)   | Slower (AI inference) |
+
+Choose `AgentBrowser` for precise, reproducible automation. Choose `StagehandBrowser` for flexible, natural language interactions.
+
+## Related
+
+- [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class reference
+- [AgentBrowser](https://mastra.ai/reference/browser/agent-browser): Deterministic alternative
+- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide
+- [Stagehand guide](https://mastra.ai/docs/browser/stagehand): Usage guide

package/.docs/reference/index.md

@@ -39,6 +39,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Okta](https://mastra.ai/reference/auth/okta)
 - [Supabase](https://mastra.ai/reference/auth/supabase)
 - [WorkOS](https://mastra.ai/reference/auth/workos)
+- [AgentBrowser](https://mastra.ai/reference/browser/agent-browser)
+- [MastraBrowser Class](https://mastra.ai/reference/browser/mastra-browser)
+- [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
 - [create-mastra](https://mastra.ai/reference/cli/create-mastra)
 - [mastra](https://mastra.ai/reference/cli/mastra)
 - [Agents API](https://mastra.ai/reference/client-js/agents)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.22-alpha.13
+
+### Patch Changes
+
+- Updated dependencies [[`a50d220`](https://github.com/mastra-ai/mastra/commit/a50d220b01ecbc5644d489a3d446c3bd4ab30245)]:
+  - @mastra/core@1.23.0-alpha.9
+
 ## 1.1.22-alpha.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.22-alpha.12",
+  "version": "1.1.22-alpha.13",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.23.0-alpha.8",
+    "@mastra/core": "1.23.0-alpha.9",
     "@mastra/mcp": "^1.4.1"
   },
   "devDependencies": {
@@ -48,7 +48,7 @@
     "vitest": "4.0.18",
     "@internal/lint": "0.0.79",
     "@internal/types-builder": "0.0.54",
-    "@mastra/core": "1.23.0-alpha.8"
+    "@mastra/core": "1.23.0-alpha.9"
   },
   "homepage": "https://mastra.ai",
   "repository": {