@mastra/mcp-docs-server 1.1.22-alpha.9 → 1.1.23-alpha.0

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

@@ -0,0 +1,163 @@
+# Arthur exporter
+
+[Arthur](https://arthur.ai/) provides an observability and evaluation platform for AI applications through [Arthur Engine](https://github.com/arthur-ai/arthur-engine) (open-source). The Arthur exporter sends traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/arthur@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/arthur@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/arthur@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/arthur@latest
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Arthur Engine instance**: Follow the [Docker Compose deployment guide](https://docs.arthur.ai/docs/arthur-genai-engine-docker-compose-deployment-guide) to start an Arthur Engine
+2. **API key**: [Generate an API key](https://docs.arthur.ai/docs/api-keys-management) from the Arthur Engine UI at `http://localhost:3030`
+3. **Task ID** (optional): [Create a task](https://docs.arthur.ai/docs/create-a-task) to route traces to a specific task
+
+### Task routing
+
+Arthur Engine associates traces with tasks in two ways:
+
+- **By service name**: Set `serviceName` in the observability config. Arthur Engine automatically routes traces to the task matching that name, creating it if needed.
+- **By task ID**: Pass a pre-existing `taskId` to the exporter to send traces to a specific task directly.
+
+If both are provided, `taskId` takes precedence.
+
+### Environment variables
+
+```bash
+# Required
+ARTHUR_API_KEY=your-api-key
+ARTHUR_BASE_URL=http://localhost:3030
+
+# Optional - route traces to a pre-existing task by ID
+ARTHUR_TASK_ID=your-task-id
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { ArthurExporter } from '@mastra/arthur'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      arthur: {
+        serviceName: 'my-service',
+        exporters: [new ArthurExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { ArthurExporter } from '@mastra/arthur'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      arthur: {
+        serviceName: 'my-service',
+        exporters: [
+          new ArthurExporter({
+            apiKey: process.env.ARTHUR_API_KEY!,
+            endpoint: process.env.ARTHUR_BASE_URL!,
+            taskId: process.env.ARTHUR_TASK_ID,
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Configuration options
+
+### Complete Configuration
+
+```typescript
+new ArthurExporter({
+  // Arthur Configuration
+  apiKey: 'your-api-key', // Required
+  endpoint: 'http://localhost:3030', // Required
+  taskId: 'your-task-id', // Optional
+
+  // Optional OTLP settings
+  headers: {
+    'x-custom-header': 'value', // Additional headers for OTLP requests
+  },
+
+  // Debug and performance tuning
+  logLevel: 'debug', // Logging: debug | info | warn | error
+  batchSize: 512, // Batch size before exporting spans
+  timeout: 30000, // Timeout in ms before exporting spans
+
+  // Custom resource attributes
+  resourceAttributes: {
+    'deployment.environment': process.env.NODE_ENV,
+    'service.version': process.env.APP_VERSION,
+  },
+})
+```
+
+### Custom metadata
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload and surface in Arthur. You can add them via `tracingOptions.metadata`:
+
+```ts
+await agent.generate(input, {
+  tracingOptions: {
+    metadata: {
+      companyId: 'acme-co',
+      tier: 'enterprise',
+    },
+  },
+})
+```
+
+Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
+## OpenInference semantic conventions
+
+This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [ArthurExporter reference](https://mastra.ai/reference/observability/tracing/exporters/arthur)
+- [Arthur Engine documentation](https://docs.arthur.ai/)
+- [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)
+- [OpenInference Specification](https://github.com/Arize-ai/openinference/tree/main/spec)

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

@@ -82,9 +82,8 @@ export const mastra = new Mastra({
             publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
             secretKey: process.env.LANGFUSE_SECRET_KEY!,
             baseUrl: process.env.LANGFUSE_BASE_URL,
-            options: {
-              environment: process.env.NODE_ENV,
-            },
+            environment: process.env.NODE_ENV,
+            release: process.env.GIT_COMMIT,
           }),
         ],
       },
@@ -136,12 +135,9 @@ new LangfuseExporter({
   realtime: process.env.NODE_ENV === 'development', // Dynamic mode selection
   logLevel: 'info', // Diagnostic logging: debug | info | warn | error
 
-  // Langfuse-specific options
-  options: {
-    environment: process.env.NODE_ENV, // Shows in UI for filtering
-    version: process.env.APP_VERSION, // Track different versions
-    release: process.env.GIT_COMMIT, // Git commit hash
-  },
+  // Langfuse-specific settings
+  environment: process.env.NODE_ENV, // Shows in Langfuse UI for filtering
+  release: process.env.GIT_COMMIT, // Git commit hash for version tracking
 })
 ```
 
@@ -156,26 +152,26 @@ Use `withLangfusePrompt` with `buildTracingOptions` for the cleanest API:
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { buildTracingOptions } from '@mastra/observability'
-import { withLangfusePrompt } from '@mastra/langfuse'
-import { Langfuse } from 'langfuse'
+import { LangfuseExporter, withLangfusePrompt } from '@mastra/langfuse'
 
-// Reads credentials from LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_BASE_URL env vars
-const langfuse = new Langfuse()
+const exporter = new LangfuseExporter()
 
-// Fetch the prompt from Langfuse Prompt Management
-const prompt = await langfuse.getPrompt('customer-support')
+// Fetch the prompt from Langfuse Prompt Management via the client
+const prompt = await exporter.client.prompt.get('customer-support', { type: 'text' })
 
 export const supportAgent = new Agent({
   name: 'support-agent',
-  instructions: prompt.prompt, // Use the prompt text from Langfuse
+  instructions: prompt.compile(), // Use the prompt text from Langfuse
   model: 'openai/gpt-5.4',
   defaultGenerateOptions: {
-    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+    tracingOptions: buildTracingOptions(
+      withLangfusePrompt({ name: prompt.name, version: prompt.version }),
+    ),
   },
 })
 ```
 
-The `withLangfusePrompt` helper automatically extracts `name`, `version`, and `id` from the Langfuse prompt object.
+The `withLangfusePrompt` helper accepts `name` and `version` fields for prompt linking. Langfuse v5 requires both fields.
 
 ### Manual Fields
 
@@ -183,26 +179,16 @@ You can also pass manual fields if you're not using the Langfuse SDK:
 
 ```typescript
 const tracingOptions = buildTracingOptions(withLangfusePrompt({ name: 'my-prompt', version: 1 }))
-
-// Or with just an ID
-const tracingOptions = buildTracingOptions(withLangfusePrompt({ id: 'prompt-uuid-12345' }))
 ```
 
 ### Prompt Object Fields
 
-The prompt object supports these fields:
-
-| Field     | Type   | Description                        |
-| --------- | ------ | ---------------------------------- |
-| `name`    | string | The prompt name in Langfuse        |
-| `version` | number | The prompt version number          |
-| `id`      | string | The prompt UUID for direct linking |
-
-You can link prompts using either:
+The prompt object requires both `name` and `version`:
 
-- `id` alone (the UUID uniquely identifies a prompt version)
-- `name` + `version` together
-- All three fields
+| Field     | Type   | Description                 |
+| --------- | ------ | --------------------------- |
+| `name`    | string | The prompt name in Langfuse |
+| `version` | number | The prompt version number   |
 
 When set on a `MODEL_GENERATION` span, the Langfuse exporter automatically links the generation to the corresponding prompt.
 

package/.docs/models/gateways/openrouter.md

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 167 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 170 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -45,6 +45,7 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-sonnet-4.5`                                   |
 | `anthropic/claude-sonnet-4.6`                                   |
 | `arcee-ai/trinity-large-preview:free`                           |
+| `arcee-ai/trinity-large-thinking`                               |
 | `arcee-ai/trinity-mini:free`                                    |
 | `black-forest-labs/flux.2-flex`                                 |
 | `black-forest-labs/flux.2-klein-4b`                             |
@@ -82,6 +83,8 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemma-3n-e2b-it:free`                                   |
 | `google/gemma-3n-e4b-it`                                        |
 | `google/gemma-3n-e4b-it:free`                                   |
+| `google/gemma-4-26b-a4b-it`                                     |
+| `google/gemma-4-31b-it`                                         |
 | `inception/mercury`                                             |
 | `inception/mercury-2`                                           |
 | `inception/mercury-coder`                                       |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3603 models from 98 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3605 models from 98 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/deepseek.md

@@ -32,7 +32,7 @@ for await (const chunk of stream) {
 
 | Model                        | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ---------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `deepseek/deepseek-chat`     | 128K    |       |           |       |       |       | $0.28      | $0.42       |
+| `deepseek/deepseek-chat`     | 131K    |       |           |       |       |       | $0.28      | $0.42       |
 | `deepseek/deepseek-reasoner` | 128K    |       |           |       |       |       | $0.28      | $0.42       |
 
 ## Advanced configuration

package/.docs/models/providers/google.md

@@ -67,8 +67,8 @@ for await (const chunk of stream) {
 | `google/gemma-3-4b-it`                              | 33K     |       |           |       |       |       | —          | —           |
 | `google/gemma-3n-e2b-it`                            | 8K      |       |           |       |       |       | —          | —           |
 | `google/gemma-3n-e4b-it`                            | 8K      |       |           |       |       |       | —          | —           |
-| `google/gemma-4-26b`                                | 256K    |       |           |       |       |       | —          | —           |
-| `google/gemma-4-31b`                                | 256K    |       |           |       |       |       | —          | —           |
+| `google/gemma-4-26b-it`                             | 256K    |       |           |       |       |       | —          | —           |
+| `google/gemma-4-31b-it`                             | 256K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -97,7 +97,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "google/gemma-4-31b"
+      ? "google/gemma-4-31b-it"
       : "google/gemini-1.5-flash";
   }
 });