@mastra/mcp-docs-server 1.2.7 → 1.2.8-alpha.17

package/.docs/docs/agent-builder/deploying.md

@@ -29,6 +29,7 @@ import { LibSQLStore } from '@mastra/libsql'
 
 new Mastra({
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: process.env.DATABASE_URL!,
     authToken: process.env.DATABASE_AUTH_TOKEN,
   }),

package/.docs/docs/agent-builder/integrations.md

@@ -37,9 +37,7 @@ import { MastraEditor } from '@mastra/editor'
 import { ComposioToolProvider } from '@mastra/editor/composio'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
   editor: new MastraEditor({
     toolProviders: {
       composio: new ComposioToolProvider({

package/.docs/docs/agent-builder/overview.md

@@ -67,7 +67,7 @@ import { createBuilderAgent } from '@mastra/editor/ee'
 import { LibSQLStore } from '@mastra/libsql'
 
 export const mastra = new Mastra({
-  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
   agents: { builderAgent: createBuilderAgent() },
   editor: new MastraEditor({
     builder: {

package/.docs/docs/agent-controller/overview.md

@@ -65,7 +65,7 @@ const agent = new Agent({
 const agentController = new AgentController({
   id: 'my-agent',
   agent,
-  storage: new LibSQLStore({ url: 'file:./data.db' }),
+  storage: new LibSQLStore({ id: 'agent-storage', url: 'file:./data.db' }),
   modes: [
     {
       id: 'plan',

package/.docs/docs/agents/overview.md

@@ -44,17 +44,31 @@ export const weatherTool = createTool({
     location: z.string().describe('City name'),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
   execute: async ({ location }) => {
     return {
-      output: `The weather in ${location} is sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Short list of known model IDs are:
+
+- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
+- `google/gemini-2.5-flash`
+
+Go to <https://mastra.ai/models> for a full list of supported models.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -83,16 +97,6 @@ export const weatherAgent = new Agent({
 })
 ```
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
-
-Short list of known model IDs are:
-
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
-- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
-- `google/gemini-2.5-flash`
-
-Go to <https://mastra.ai/models> for a full list of supported models.
-
 Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
 
 ```ts

package/.docs/docs/agents/skills.md

@@ -85,9 +85,7 @@ export const agent = new Agent({
   skills: [
     './skills/code-review', // path to a SKILL.md directory
     './skills/testing', // another filesystem skill
-    createSkill({
-      /* ... */
-    }), // inline skill
+    createSkill({/* ... */}), // inline skill
   ],
 })
 ```

package/.docs/docs/agents/structured-output.md

@@ -197,9 +197,9 @@ If your tools aren't being called when structured output is enabled, or you rece
 
 When your model doesn't support tools and structured output together, you have three options:
 
-1. **Use `jsonPromptInjection: true`** - Injects the schema into the prompt instead of using the API's `response_format` parameter
-2. **Use a separate structuring model** - Pass a `model` to `structuredOutput` to use a second LLM for structuring
-3. **Use `prepareStep`** - Handle tools and structured output in separate steps
+1. **Use `jsonPromptInjection`**: Set it to `'auto'` to select native structured output when supported and inline prompt injection otherwise, or choose an explicit injection mode
+2. **Use a separate structuring model**: Pass a `model` to `structuredOutput` to use a second LLM for structuring
+3. **Use `prepareStep`**: Handle tools and structured output in separate steps
 
 Each approach is detailed in the sections below.
 
@@ -209,9 +209,7 @@ Structured output support varies across LLMs due to differences in their APIs. T
 
 ### `jsonPromptInjection`
 
-By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
-
-If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Set `jsonPromptInjection: 'auto'` to let Mastra choose the mode from its model capability data. Mastra uses native structured output for supported models and inline prompt injection for unsupported models or models without capability data.
 
 ```typescript
 import { z } from 'zod'
@@ -224,13 +222,20 @@ const response = await testAgent.generate('Help me plan my day.', {
         activities: z.array(z.string()),
       }),
     ),
-    jsonPromptInjection: true,
+    jsonPromptInjection: 'auto',
   },
 })
 
 console.log(response.object)
 ```
 
+Use an explicit mode when you need to override the capability-based choice:
+
+- `false` or omitted: Use the provider's native structured output.
+- `'inline'`: Add the schema instructions to the latest user message.
+- `true` or `'system'`: Add the schema instructions to the system message.
+- `'auto'`: Use native structured output when the model supports it. Otherwise, use inline prompt injection.
+
 > **Gemini 2.5 with tools:** Gemini 2.5 models don't support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
 >
 > ```typescript
@@ -246,6 +251,8 @@ console.log(response.object)
 
 When `model` is provided to the `structuredOutput` property, Mastra uses a separate internal agent to handle the structured output. The main agent will handle all of the steps (including tool calling) and the structured output model will handle only the generation of structured output.
 
+**For AI agents:** The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`, `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6` or `google/gemini-2.5-pro`. Use `/` and not `:` as a separator. Example: `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise. By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`.
+
 ```typescript
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {

package/.docs/docs/agents/using-tools.md

@@ -14,7 +14,7 @@ Use tools when an agent needs additional context or information from remote reso
 
 Import [`createTool`](https://mastra.ai/reference/tools/create-tool) from `@mastra/core/tools` and define a tool with an `id`, `description`, `inputSchema`, `outputSchema`, and `execute` function.
 
-This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
+This example creates a tool that fetches weather data from an API. The `execute` function receives input validated against `inputSchema` as its first argument and an optional execution context as its second. You can destructure the input fields directly in the function signature.
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -27,15 +27,21 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    const { location } = inputData
-
-    const response = await fetch(`https://wttr.in/${location}?format=3`)
-    const weather = await response.text()
+  execute: async ({ location }, { abortSignal }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=j1`, {
+      signal: abortSignal,
+    })
+    const data = await response.json()
 
-    return { weather }
+    return {
+      location,
+      temperatureCelsius: Number(data.current_condition[0].temp_C),
+      conditions: data.current_condition[0].weatherDesc[0].value,
+    }
   },
 })
 ```
@@ -76,10 +82,12 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -101,11 +109,13 @@ export const weatherTool = createTool({
   ),
   outputSchema: toStandardJsonSchema(
     v.object({
-      weather: v.string(),
+      location: v.string(),
+      temperatureCelsius: v.number(),
+      conditions: v.string(),
     }),
   ),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -123,10 +133,12 @@ export const weatherTool = createTool({
     location: 'string',
   }),
   outputSchema: type({
-    weather: 'string',
+    location: 'string',
+    temperatureCelsius: 'number',
+    conditions: 'string',
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -193,6 +205,47 @@ export const researchAgent = new Agent({
 })
 ```
 
+## Share tools across agents
+
+Direct imports are the best choice when one tool is used by multiple agents. Each agent imports the tool and adds it to its `tools` record. Dependencies remain explicit and each agent can be used independently.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  // Rest of the tool definition...
+})
+```
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: 'Answer questions about current weather.',
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
+})
+```
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool'
+
+export const travelAgent = new Agent({
+  id: 'travel-agent',
+  name: 'Travel Agent',
+  instructions: 'Help users plan trips.',
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
+})
+```
+
+If you need to access tools from the Mastra instance, see [`Mastra.getTool()`](https://mastra.ai/reference/core/getTool), [`Mastra.getToolById()`](https://mastra.ai/reference/core/getToolById), [`Mastra.listTools()`](https://mastra.ai/reference/core/listTools), and the [`Agent` reference](https://mastra.ai/reference/agents/agent).
+
 ## Shape output for the model
 
 Use `toModelOutput` when your tool returns rich structured data for your application, but you want the model to receive a smaller or multimodal representation. This keeps model context focused while preserving the full tool result in your app.
@@ -205,8 +258,8 @@ export const weatherTool = createTool({
 
     return {
       location,
-      temperature: data.current_condition[0].temp_F,
-      condition: data.current_condition[0].weatherDesc[0].value,
+      temperatureCelsius: Number(data.current_condition[0].temp_C),
+      conditions: data.current_condition[0].weatherDesc[0].value,
       weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
       source: data,
     }
@@ -217,7 +270,7 @@ export const weatherTool = createTool({
       value: [
         {
           type: 'text',
-          text: `${output.location}: ${output.temperature}F and ${output.condition}`,
+          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
         },
         { type: 'image-url', url: output.weatherIconUrl },
       ],
@@ -321,23 +374,24 @@ export const weatherTool = createTool({
   id: 'weather-tool',
   description: 'Get weather information',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    temperature: z.number(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
     conditions: z.string(),
   }),
   // Called when the complete input is available
   onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Weather requested for: ${input.city}`)
+    console.log(`Weather requested for: ${input.location}`)
   },
-  execute: async input => {
-    const weather = await fetchWeather(input.city)
+  execute: async ({ location }) => {
+    const weather = await fetchWeather(location)
     return weather
   },
   // Called after successful execution
   onOutput: ({ output, toolName }) => {
-    console.log(`${toolName} result: ${output.temperature}°F, ${output.conditions}`)
+    console.log(`${toolName} result: ${output.temperatureCelsius}°C, ${output.conditions}`)
   },
 })
 ```

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

@@ -105,5 +105,6 @@ This adds `browser_record` and `browser_record_caption` to the agent's toolset.
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/docs/browser/firecrawl.md

@@ -0,0 +1,129 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Firecrawl
+
+The `@mastra/browser-firecrawl` package provides browser automation using the [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser). It provisions remote browser sessions through the Firecrawl API and drives them with the same deterministic, accessibility-first tools as [AgentBrowser](https://mastra.ai/docs/browser/agent-browser).
+
+`FirecrawlBrowser` extends `AgentBrowser`, so agents get the same toolset (`browser_goto`, `browser_snapshot`, `browser_click`, and so on) while the browser itself runs in Firecrawl's hosted infrastructure. No local Chromium install is needed.
+
+## When to use Firecrawl
+
+Use Firecrawl when you need:
+
+- Hosted browser sessions without managing local Chromium binaries
+- Browser automation in environments that can't launch a local browser
+- Per-thread sandbox isolation with automatic session cleanup
+- Named Firecrawl profiles that persist cookies and login state between sessions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/browser-firecrawl
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/browser-firecrawl
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/browser-firecrawl
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/browser-firecrawl
+```
+
+Set your Firecrawl API key:
+
+```bash
+FIRECRAWL_API_KEY=fc-...
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { FirecrawlBrowser } from '@mastra/browser-firecrawl'
+
+const browser = new FirecrawlBrowser({
+  apiKey: process.env.FIRECRAWL_API_KEY,
+})
+
+export const firecrawlAgent = new Agent({
+  id: 'firecrawl-agent',
+  name: 'Firecrawl Agent',
+  model: 'openai/gpt-5.5',
+  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`,
+})
+```
+
+If `apiKey` is omitted, the provider reads `FIRECRAWL_API_KEY` from the environment.
+
+## Session scope
+
+`FirecrawlBrowser` follows the same `scope` option as `AgentBrowser`:
+
+- `'thread'` (default): Each conversation thread gets its own Firecrawl sandbox session. Sessions are deleted when the thread's browser closes.
+- `'shared'`: One Firecrawl sandbox session is shared across all threads and deleted when the browser closes.
+
+```typescript
+const browser = new FirecrawlBrowser({
+  scope: 'shared',
+})
+```
+
+## Session options
+
+Pass Firecrawl-specific session options under the `firecrawl` key. These map to the Firecrawl `browser()` API:
+
+```typescript
+const browser = new FirecrawlBrowser({
+  firecrawl: {
+    ttl: 600,
+    activityTtl: 120,
+    profile: {
+      name: 'my-profile',
+      saveChanges: true,
+    },
+  },
+})
+```
+
+- `ttl`: Maximum session lifetime in seconds.
+- `activityTtl`: Idle timeout in seconds before Firecrawl recycles the session.
+- `profile`: Named Firecrawl profile that persists cookies and login state. Set `saveChanges: true` to save profile changes when the session ends.
+
+> **Note:** The nested `firecrawl.profile` option refers to a profile stored in Firecrawl's infrastructure. It's different from the top-level `profile` option inherited from `AgentBrowser`, which is a local Playwright user-data directory path.
+
+## Self-hosted Firecrawl
+
+To use a self-hosted Firecrawl API, set `apiUrl`:
+
+```typescript
+const browser = new FirecrawlBrowser({
+  apiUrl: 'https://firecrawl.internal.example.com',
+})
+```
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
+- [FirecrawlBrowser reference](https://mastra.ai/reference/browser/firecrawl-browser)

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

@@ -4,10 +4,11 @@
 
 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 browser automation libraries and a CLI provider for agents that drive browsers through command-line tools.
 
-Mastra supports two SDK providers and one CLI provider:
+Mastra supports three SDK providers and one CLI provider:
 
 - [**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.
+- [**FirecrawlBrowser**](https://mastra.ai/docs/browser/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
 - [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
 - [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
@@ -86,7 +87,19 @@ 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.
+All SDK providers support connecting to cloud browser services instead of launching a local browser.
+
+### Firecrawl Browser Sandbox (FirecrawlBrowser native)
+
+FirecrawlBrowser provisions hosted sessions through the Firecrawl API:
+
+```typescript
+import { FirecrawlBrowser } from '@mastra/browser-firecrawl'
+
+const browser = new FirecrawlBrowser({
+  apiKey: process.env.FIRECRAWL_API_KEY,
+})
+```
 
 ### Browserbase (Stagehand native)
 
@@ -167,6 +180,7 @@ const browser = new AgentBrowser({
 
 - [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/capabilities/channels/other-adapters.md

@@ -2,7 +2,7 @@
 
 # More
 
-Mastra channels use Chat SDK adapters, so the pages in this section are not the full list of supported platforms. Use any Chat SDK platform adapter that exports an adapter factory compatible with `channels.adapters`.
+Mastra channels use Chat SDK adapters, so the pages in this section aren't the full list of supported platforms. Use any Chat SDK platform adapter that exports an adapter factory compatible with `channels.adapters`.
 
 ## Adapter catalog
 

package/.docs/docs/capabilities/channels/overview.md

@@ -58,6 +58,7 @@ import { yourAgent } from './agents/your-agent'
 export const mastra = new Mastra({
   agents: { yourAgent },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: process.env.DATABASE_URL,
   }),
 })