@mastra/mcp-docs-server 1.1.41-alpha.0 → 1.1.42-alpha.10

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

@@ -52,7 +52,7 @@ export const weatherAgent = new Agent({
   instructions: `
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool },
 })
 ```
@@ -145,7 +145,7 @@ export const weatherAgent = new Agent({
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.
     Use the hazardsTool to provide information about potential weather hazards.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool, hazardsTool },
 })
 ```
@@ -162,14 +162,14 @@ const writer = new Agent({
   name: 'Writer',
   description: 'Drafts and edits written content',
   instructions: 'You are a skilled writer.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 export const supervisor = new Agent({
   id: 'supervisor',
   name: 'Supervisor',
   instructions: 'Coordinate the writer to produce content.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { writer },
 })
 ```
@@ -186,7 +186,7 @@ export const researchAgent = new Agent({
   id: 'research-agent',
   name: 'Research Agent',
   instructions: 'You are a research assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workflows: { researchWorkflow },
 })
 ```

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

@@ -52,7 +52,7 @@ const browser = new AgentBrowser({
 export const browserAgent = new Agent({
   id: 'browser-agent',
   name: 'Browser Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions: `You are a web automation assistant.
 

package/.docs/docs/browser/browser-viewer.md

@@ -73,7 +73,7 @@ const workspace = new Workspace({
 
 const browserAgent = new Agent({
   id: 'browser-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workspace,
   instructions: `You are a web automation assistant.
 Use browser-use commands to navigate and interact with websites.`,

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

@@ -72,7 +72,7 @@ export const webAgent = new Agent({
   id: 'web-agent',
   name: 'Web Agent',
   description: 'A web automation assistant that can navigate websites and complete tasks.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions:
     'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',

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

@@ -47,13 +47,13 @@ import { StagehandBrowser } from '@mastra/stagehand'
 
 const browser = new StagehandBrowser({
   headless: false,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 export const stagehandAgent = new Agent({
   id: 'stagehand-agent',
   name: 'Stagehand Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions: `You are a web automation assistant.
 
@@ -117,7 +117,7 @@ Use screenshots when you need to visually inspect the page — for example, eval
 ```typescript
 const browser = new StagehandBrowser({
   headless: false,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 
@@ -126,7 +126,7 @@ To disable the screenshot tool for models that do not support vision, use `exclu
 ```typescript
 const browser = new StagehandBrowser({
   headless: false,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   excludeTools: ['stagehand_screenshot'],
 })
 ```
@@ -140,7 +140,7 @@ const browser = new StagehandBrowser({
   env: 'BROWSERBASE',
   apiKey: process.env.BROWSERBASE_API_KEY,
   projectId: process.env.BROWSERBASE_PROJECT_ID,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 

package/.docs/docs/editor/overview.md

@@ -66,6 +66,41 @@ Once registered, you can manage agents through [Studio](https://mastra.ai/docs/s
 
 > **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
+## Code and database sources
+
+The editor stores agent overrides in one of two sources, set with the `source` option on `MastraEditor`:
+
+| Source         | Where overrides live                                      | Studio actions                                           |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------- |
+| `db` (default) | The configured storage backend.                           | Save and publish drafts.                                 |
+| `code`         | Per-agent JSON files on disk, tracked in your repository. | Download the override file or save it to the filesystem. |
+
+The default `db` source is best when non-developers iterate through Studio and you want versioning, drafts, and runtime version targeting. The `code` source is best when overrides should live in your repository alongside the rest of your code, reviewed through pull requests and deployed with your application.
+
+To use the code source, set `source: 'code'`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: {
+    /* your existing agents */
+  },
+  editor: new MastraEditor({
+    source: 'code',
+  }),
+})
+```
+
+When `source` is `'code'`, the editor writes each override to a deterministic JSON file under `./mastra/editor/agents/<agentId>.json`. Set `codePath` to change the directory. Because the files are deterministic, every save produces a clean diff you can commit and review.
+
+### Versioning with the code source
+
+The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file appears as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
+
+This means versions and rollbacks are managed through Git rather than through draft and publish actions.
+
 ## Studio
 
 Go to the **Agents** tab in Studio and select an agent to edit. Select the **Editor** tab. You'll be taken to the editor interface, where you can modify the agent's instructions, tools, and variables.
@@ -114,15 +149,16 @@ The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and
 
 The same operations are available over HTTP through the Mastra server. Use these when you want to manage stored agents from a separate service or from a non-TypeScript client:
 
-| Method   | Path                            | Description               |
-| -------- | ------------------------------- | ------------------------- |
-| `GET`    | `/stored/agents`                | List all stored agents.   |
-| `POST`   | `/stored/agents`                | Create a stored agent.    |
-| `GET`    | `/stored/agents/:storedAgentId` | Get a stored agent by ID. |
-| `PATCH`  | `/stored/agents/:storedAgentId` | Update a stored agent.    |
-| `DELETE` | `/stored/agents/:storedAgentId` | Delete a stored agent.    |
+| Method   | Path                                   | Description                                                      |
+| -------- | -------------------------------------- | ---------------------------------------------------------------- |
+| `GET`    | `/stored/agents`                       | List all stored agents.                                          |
+| `POST`   | `/stored/agents`                       | Create a stored agent.                                           |
+| `GET`    | `/stored/agents/:storedAgentId`        | Get a stored agent by ID.                                        |
+| `PATCH`  | `/stored/agents/:storedAgentId`        | Update a stored agent.                                           |
+| `DELETE` | `/stored/agents/:storedAgentId`        | Delete a stored agent.                                           |
+| `POST`   | `/stored/agents/:storedAgentId/export` | Export a stored agent's override as a deterministic JSON config. |
 
-The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, and `client.getStoredAgent()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
+The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
 
 ### Automated experimentation
 
@@ -149,6 +185,32 @@ When you edit a code-defined agent through the editor, only specific fields can
 
 Fields like the agent's `id`, `name`, and `model` come from your code and can't be changed through the editor for code-defined agents. The variables are also read-only.
 
+### Controlling what is editable
+
+Use the `editor` field on a code-defined agent to control which fields the editor can override. This lets you keep some fields code-owned while allowing edits to others:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5.5',
+  editor: { instructions: true, tools: { description: true } },
+})
+```
+
+The `editor` field accepts these shapes:
+
+| Value                              | Result                                                     |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Omitted                            | Instructions and tools are editable.                       |
+| `false`                            | Nothing is editable. The agent is locked.                  |
+| `{ instructions: true }`           | Instructions are editable.                                 |
+| `{ tools: true }`                  | Tool membership and descriptions are editable.             |
+| `{ tools: { description: true } }` | Only tool descriptions are editable. Membership is locked. |
+
+When a field is owned by code, Studio shows it as read-only and the server strips it from saved overrides, so the stored config only contains the fields you allow. See the [`editor` overrides reference](https://mastra.ai/reference/agents/agent) for the full type.
+
 ## Versioning
 
 Every time you save changes to an agent or prompt block, a new version snapshot is created. Versions give you a full history of your agent's configuration. You can roll back to any previous state, compare what changed between two snapshots, and target specific versions per request for A/B testing or gradual rollouts.

package/.docs/docs/evals/custom-scorers.md

@@ -44,7 +44,7 @@ const glutenCheckerScorer = createScorer({
   id: 'gluten-checker',
   description: 'Check if recipes contain gluten ingredients',
   judge: {                    // Optional: for prompt object steps
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
     instructions: 'You are a Chef that identifies if recipes contain gluten.'
   }
 })

package/.docs/docs/evals/datasets/running-experiments.md

@@ -104,7 +104,7 @@ const summary = await dataset.startExperiment({
 ```typescript
 import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
 
-const relevancy = createAnswerRelevancyScorer({ model: '__OPENAI_MODEL_MINI__' })
+const relevancy = createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' })
 
 const summary = await dataset.startExperiment({
   name: 'with-scorer-instances',

package/.docs/docs/evals/overview.md

@@ -57,11 +57,11 @@ import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals
 export const evaluatedAgent = new Agent({
   scorers: {
     relevancy: {
-      scorer: createAnswerRelevancyScorer({ model: '__OPENAI_MODEL_MINI__' }),
+      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
       sampling: { type: 'ratio', rate: 0.5 },
     },
     safety: {
-      scorer: createToxicityScorer({ model: '__OPENAI_MODEL_MINI__' }),
+      scorer: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
       sampling: { type: 'ratio', rate: 1 },
     },
   },

package/.docs/docs/getting-started/manual-install.md

@@ -113,7 +113,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    Add your API key:
 
    ```bash
-   GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
+   GOOGLE_API_KEY=<your-api-key>
    ```
 
    > **Note:** This guide uses Google Gemini, but you can use any supported [model provider](https://mastra.ai/models), including OpenAI, Anthropic, and more.

package/.docs/docs/mcp/mcp-apps.md

@@ -93,7 +93,7 @@ export const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You have access to interactive UI tools.',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: { calculatorTool },
 })
 ```
@@ -125,7 +125,7 @@ const mcpClient = new MCPClient({
 const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: await mcpClient.listTools(),
 })
 
@@ -270,7 +270,7 @@ const mcpClient = new MCPClient({
 const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: await mcpClient.listTools(),
 })
 

package/.docs/docs/mcp/overview.md

@@ -82,7 +82,7 @@ export const testAgent = new Agent({
       - US National Weather Service
 
       Answer questions using the information you find using the MCP Servers.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: await testMcpClient.listTools(),
 })
 ```

package/.docs/docs/memory/memory-processors.md

@@ -45,7 +45,7 @@ const agent = new Agent({
   id: 'test-agent',
   name: 'Test Agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'memory-store',
@@ -95,7 +95,7 @@ import { openai } from '@ai-sdk/openai'
 const agent = new Agent({
   name: 'semantic-agent',
   instructions: 'You are a helpful assistant with semantic memory',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'memory-store',
@@ -148,7 +148,7 @@ import { openai } from '@ai-sdk/openai'
 const agent = new Agent({
   name: 'working-memory-agent',
   instructions: 'You are an assistant with working memory',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'memory-store',
@@ -180,7 +180,7 @@ const customMessageHistory = new MessageHistory({
 const agent = new Agent({
   name: 'custom-memory-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({ id: 'memory-store', url: 'file:memory.db' }),
     lastMessages: 10, // This would normally add MessageHistory(10)
@@ -250,7 +250,7 @@ const contentBlocker = {
 const agent = new Agent({
   name: 'safe-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({ lastMessages: 10 }),
   // Your guardrail runs BEFORE memory saves
   outputProcessors: [contentBlocker],
@@ -289,7 +289,7 @@ const inputValidator = {
 const agent = new Agent({
   name: 'validated-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({ lastMessages: 10 }),
   // Your guardrail runs AFTER memory loads history
   inputProcessors: [inputValidator],

package/.docs/docs/memory/multi-user-threads.md

@@ -65,7 +65,7 @@ const memory = new Memory({
 export const collabAgent = new Agent({
   id: 'collab',
   name: 'CollabAgent',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   memory,
   instructions: `
 You are a collaborative document assistant. Multiple users talk to you in the SAME thread.

package/.docs/docs/memory/observational-memory.md

@@ -117,6 +117,25 @@ const memory = new Memory({
 
 In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
 
+### Buffer on idle
+
+Set `observation.bufferOnIdle` to `true` to run background observation buffering when an agent turn ends and the agent becomes idle. This is useful for apps that want short turns to be observed without waiting for the next turn or the `messageTokens` threshold.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+      observation: {
+        bufferOnIdle: true,
+      },
+    },
+  },
+})
+```
+
+`bufferOnIdle` is off by default. It is separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
+
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
 ## Benefits

package/.docs/docs/memory/semantic-recall.md

@@ -30,7 +30,7 @@ const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'agent-storage',
@@ -247,7 +247,7 @@ const agent = new Agent({
 })
 ```
 
-The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENROUTER_API_KEY`).
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY`). Google models also fall back to `GOOGLE_GENERATIVE_AI_API_KEY`.
 
 ### Using AI SDK Packages
 

package/.docs/docs/memory/storage.md

@@ -41,6 +41,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
 - [LanceDB](https://mastra.ai/reference/storage/lance)
 - [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
+- [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
 
 > **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
 
@@ -179,7 +180,7 @@ export const agent = new Agent({
   memory: new Memory({
     options: {
       generateTitle: {
-        model: '__OPENAI_MODEL_MINI__',
+        model: 'openai/gpt-5-mini',
         instructions: 'Generate a 1 word title',
       },
     },

package/.docs/docs/memory/working-memory.md

@@ -26,7 +26,7 @@ const agent = new Agent({
   id: 'personal-assistant',
   name: 'PersonalAssistant',
   instructions: 'You are a helpful personal assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     options: {
       workingMemory: {

package/.docs/docs/observability/metrics/overview.md

@@ -110,6 +110,7 @@ Before storage, all metric labels pass through a cardinality filter that blocks
 ## Next steps
 
 - [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
 - [Studio observability](https://mastra.ai/docs/studio/observability)
 - [Observability overview](https://mastra.ai/docs/observability/overview)