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

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/.docs/reference/observability/tracing/exporters/arthur.md

@@ -0,0 +1,122 @@
+# ArthurExporter
+
+Sends Tracing data to [Arthur Engine](https://github.com/arthur-ai/arthur-engine) using OpenTelemetry and OpenInference semantic conventions.
+
+## Constructor
+
+```typescript
+new ArthurExporter(config: ArthurExporterConfig)
+```
+
+## `ArthurExporterConfig`
+
+```typescript
+type ArthurExporterConfig = Omit<OtelExporterConfig, 'provider' | 'exporter'> & {
+  apiKey?: string
+  endpoint?: string
+  taskId?: string
+  headers?: Record<string, string>
+}
+```
+
+Inherits from `OtelExporterConfig` (excluding `provider` and `exporter`), which includes:
+
+- `timeout?: number` - Export timeout in milliseconds (default: 30000)
+- `batchSize?: number` - Number of spans per batch (default: 512)
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: WARN)
+- `resourceAttributes?: Record<string, any>` - Custom resource attributes
+
+### Metadata passthrough
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload. Add them via `tracingOptions.metadata` (e.g., `companyId`, `tier`). Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
+## Methods
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to the configured endpoint.
+
+### export
+
+```typescript
+async export(spans: ReadOnlySpan[]): Promise<void>
+```
+
+Batch exports spans using OpenTelemetry with OpenInference semantic conventions.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to the configured endpoint without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { ArthurExporter } from '@mastra/arthur'
+
+// Set ARTHUR_API_KEY and ARTHUR_BASE_URL (optionally ARTHUR_TASK_ID)
+const exporter = new ArthurExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { ArthurExporter } from '@mastra/arthur'
+
+const exporter = new ArthurExporter({
+  apiKey: process.env.ARTHUR_API_KEY!,
+  endpoint: 'http://localhost:3030',
+  taskId: process.env.ARTHUR_TASK_ID, // Optional
+})
+```
+
+## `OpenInference` semantic conventions
+
+The ArthurExporter implements [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
+
+## Tags support
+
+The ArthurExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are mapped to the native OpenInference `tag.tags` semantic convention.
+
+### Usage
+
+```typescript
+const result = await agent.generate('Hello', {
+  tracingOptions: {
+    tags: ['production', 'experiment-v2', 'user-request'],
+  },
+})
+```
+
+### How Tags Are Stored
+
+Tags are stored using the OpenInference `tag.tags` attribute:
+
+```json
+{
+  "tag.tags": ["production", "experiment-v2", "user-request"]
+}
+```
+
+## Related
+
+- [ArthurExporter Documentation](https://mastra.ai/docs/observability/tracing/exporters/arthur)
+- [Arthur Engine documentation](https://docs.arthur.ai/)
+- [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)

package/.docs/reference/observability/tracing/exporters/langfuse.md

@@ -16,7 +16,8 @@ interface LangfuseExporterConfig extends BaseExporterConfig {
   secretKey?: string
   baseUrl?: string
   realtime?: boolean
-  options?: any
+  environment?: string
+  release?: string
 }
 ```
 
@@ -25,23 +26,17 @@ Extends `BaseExporterConfig`, which includes:
 - `logger?: IMastraLogger` - Logger instance
 - `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
 
-## Methods
+## Properties
 
-### `exportTracingEvent`
+### `client`
 
 ```typescript
-async exportTracingEvent(event: TracingEvent): Promise<void>
+get client(): LangfuseClient | undefined
 ```
 
-Exports a tracing event to Langfuse.
-
-### export
-
-```typescript
-async export(spans: ReadOnlySpan[]): Promise<void>
-```
+The `LangfuseClient` instance for advanced Langfuse features. Returns `undefined` when the exporter is disabled (missing credentials). Use this for prompt management, evaluations, datasets, and direct API access.
 
-Batch exports spans to Langfuse.
+## Methods
 
 ### flush
 
@@ -49,7 +44,7 @@ Batch exports spans to Langfuse.
 async flush(): Promise<void>
 ```
 
-Force flushes any buffered spans to Langfuse without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+Force flushes any buffered spans and scores to Langfuse without shutting down. Useful in serverless environments where you need to ensure data is exported before the runtime terminates.
 
 ### shutdown
 
@@ -57,7 +52,7 @@ Force flushes any buffered spans to Langfuse without shutting down the exporter.
 async shutdown(): Promise<void>
 ```
 
-Flushes pending data and shuts down the client.
+Flushes pending data and shuts down both the span processor and the client.
 
 ## Usage
 
@@ -85,10 +80,11 @@ const exporter = new LangfuseExporter({
 
 ## Span mapping
 
-- Root spans → Langfuse traces
-- `MODEL_GENERATION` spans → Langfuse generations
+Mastra spans are converted to OTel format and sent to Langfuse via `LangfuseSpanProcessor`. Langfuse automatically maps spans based on their `gen_ai.*` attributes:
+
+- Spans with a `model` attribute → Langfuse generations
 - All other spans → Langfuse spans
-- Event spans → Langfuse events
+- Parent-child relationships are preserved via OTel trace/span IDs
 
 ## Prompt linking
 
@@ -96,22 +92,21 @@ Link LLM generations to [Langfuse Prompt Management](https://langfuse.com/docs/p
 
 ```typescript
 import { buildTracingOptions } from '@mastra/observability'
-import { withLangfusePrompt } from '@mastra/langfuse'
-import { Langfuse } from 'langfuse'
+import { LangfuseExporter, withLangfusePrompt } from '@mastra/langfuse'
 
-const langfuse = new Langfuse({
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
-  secretKey: process.env.LANGFUSE_SECRET_KEY!,
-})
+const exporter = new LangfuseExporter()
 
-const prompt = await langfuse.getPrompt('customer-support')
+// Fetch prompt via the Langfuse client
+const prompt = await exporter.client.prompt.get('customer-support', { type: 'text' })
 
 const agent = new Agent({
   name: 'support-agent',
-  instructions: prompt.prompt,
+  instructions: prompt.compile(),
   model: 'openai/gpt-5.4',
   defaultGenerateOptions: {
-    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+    tracingOptions: buildTracingOptions(
+      withLangfusePrompt({ name: prompt.name, version: prompt.version }),
+    ),
   },
 })
 ```
@@ -123,12 +118,8 @@ const agent = new Agent({
 Adds Langfuse prompt metadata to tracing options.
 
 ```typescript
-// With Langfuse SDK prompt object
-withLangfusePrompt(prompt)
-
-// With manual fields
+// Link by name and version (required for Langfuse v5)
 withLangfusePrompt({ name: 'my-prompt', version: 1 })
-withLangfusePrompt({ id: 'prompt-uuid' })
 ```
 
-When `metadata.langfuse.prompt` is set on a `MODEL_GENERATION` span (with either `id` alone, or `name` + `version`), the exporter automatically links the generation to the prompt in Langfuse.
+The prompt metadata is passed through as span attributes and Langfuse links the generation to the corresponding prompt.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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
+
+- Updated dependencies [[`ac7baf6`](https://github.com/mastra-ai/mastra/commit/ac7baf66ef1db15e03975ef4ebb02724f015a391), [`0df8321`](https://github.com/mastra-ai/mastra/commit/0df832196eeb2450ab77ce887e8553abdd44c5a6), [`61109b3`](https://github.com/mastra-ai/mastra/commit/61109b34feb0e38d54bee4b8ca83eb7345b1d557), [`33f1ead`](https://github.com/mastra-ai/mastra/commit/33f1eadfa19c86953f593478e5fa371093b33779)]:
+  - @mastra/core@1.23.0-alpha.8
+
 ## 1.1.22-alpha.10
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.22-alpha.11",
+  "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.7",
+    "@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.7"
+    "@mastra/core": "1.23.0-alpha.9"
   },
   "homepage": "https://mastra.ai",
   "repository": {