@mastra/mcp-docs-server 1.1.6 → 1.1.7-alpha.0

package/.docs/models/providers.md

@@ -19,9 +19,11 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Berget.AI](https://mastra.ai/models/providers/berget)
 - [Cerebras](https://mastra.ai/models/providers/cerebras)
 - [Chutes](https://mastra.ai/models/providers/chutes)
+- [CloudFerro Sherlock](https://mastra.ai/models/providers/cloudferro-sherlock)
 - [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)
 - [Cortecs](https://mastra.ai/models/providers/cortecs)
 - [Deep Infra](https://mastra.ai/models/providers/deepinfra)
+- [evroc](https://mastra.ai/models/providers/evroc)
 - [FastRouter](https://mastra.ai/models/providers/fastrouter)
 - [Fireworks AI](https://mastra.ai/models/providers/fireworks-ai)
 - [Firmware](https://mastra.ai/models/providers/firmware)
@@ -40,6 +42,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Llama](https://mastra.ai/models/providers/llama)
 - [LMStudio](https://mastra.ai/models/providers/lmstudio)
 - [LucidQuery AI](https://mastra.ai/models/providers/lucidquery)
+- [Meganova](https://mastra.ai/models/providers/meganova)
 - [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax)
 - [MiniMax (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn)
 - [MiniMax Coding Plan (minimax.io)](https://mastra.ai/models/providers/minimax-coding-plan)
@@ -55,11 +58,15 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [NovitaAI](https://mastra.ai/models/providers/novita-ai)
 - [Nvidia](https://mastra.ai/models/providers/nvidia)
 - [Ollama Cloud](https://mastra.ai/models/providers/ollama-cloud)
+- [OpenCode Go](https://mastra.ai/models/providers/opencode-go)
 - [OpenCode Zen](https://mastra.ai/models/providers/opencode)
 - [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)
 - [Perplexity](https://mastra.ai/models/providers/perplexity)
+- [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)
 - [Poe](https://mastra.ai/models/providers/poe)
 - [Privatemode AI](https://mastra.ai/models/providers/privatemode-ai)
+- [QiHang](https://mastra.ai/models/providers/qihang-ai)
+- [Qiniu](https://mastra.ai/models/providers/qiniu-ai)
 - [Requesty](https://mastra.ai/models/providers/requesty)
 - [Scaleway](https://mastra.ai/models/providers/scaleway)
 - [SiliconFlow](https://mastra.ai/models/providers/siliconflow)

package/.docs/reference/agents/network.md

@@ -44,6 +44,10 @@ await agent.network(`
 
 **maxSteps?:** (`number`): Maximum number of steps to run during execution.
 
+**abortSignal?:** (`AbortSignal`): Signal to abort the network execution. When aborted, the network stops routing, cancels any in-progress sub-agent, tool, or workflow execution, and skips saving partial results to memory.
+
+**onAbort?:** (`(event: { primitiveType: string; primitiveId: string; iteration: number }) => void | Promise<void>`): Callback fired when the network is aborted. Receives an event with the type and ID of the primitive that was executing when the abort occurred.
+
 **memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }The conversation thread, as a string ID or an object with an \`id\` and optional \`metadata\`.resource:stringIdentifier for the user or resource associated with the thread.options?:MemoryConfigConfiguration for memory behavior, like message history and semantic recall.
 
 **tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
@@ -62,6 +66,10 @@ await agent.network(`
 
 **traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
 
+**onStepFinish?:** (`(event: any) => Promise<void> | void`): Callback fired after each LLM step within a sub-agent execution. Receives step details including finish reason and token usage.
+
+**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback fired when an error occurs during sub-agent execution.
+
 ## Returns
 
 **stream:** (`MastraAgentNetworkStream<NetworkChunkType>`): A custom stream that extends ReadableStream\<NetworkChunkType> with additional network-specific properties
@@ -130,4 +138,33 @@ const final = await stream.object
 When using structured output, additional chunk types are emitted:
 
 - `network-object`: Emitted with partial objects during streaming
-- `network-object-result`: Emitted with the final structured object
+- `network-object-result`: Emitted with the final structured object
+
+## Aborting a Network
+
+Use `abortSignal` to cancel a running network. When aborted, the network stops routing, cancels any in-progress sub-agent, tool, or workflow execution, and does not save partial results to memory.
+
+```typescript
+const controller = new AbortController()
+
+// Abort after 30 seconds
+setTimeout(() => controller.abort(), 30_000)
+
+const stream = await agent.network('Research this topic thoroughly', {
+  abortSignal: controller.signal,
+  onAbort: ({ primitiveType, primitiveId, iteration }) => {
+    console.log(`Aborted ${primitiveType} "${primitiveId}" at iteration ${iteration}`)
+  },
+})
+
+for await (const chunk of stream) {
+  if (
+    chunk.type === 'routing-agent-abort' ||
+    chunk.type === 'agent-execution-abort' ||
+    chunk.type === 'tool-execution-abort' ||
+    chunk.type === 'workflow-execution-abort'
+  ) {
+    console.log('Network was aborted')
+  }
+}
+```

package/.docs/reference/ai-sdk/with-mastra.md

@@ -56,4 +56,8 @@ const { text } = await generateText({
 
 ## Returns
 
-A wrapped model compatible with `generateText`, `streamText`, `generateObject`, and `streamObject`.
+A wrapped model compatible with `generateText`, `streamText`, `generateObject`, and `streamObject`.
+
+## Streaming behavior
+
+Output processors that implement `processOutputResult` run after the stream finishes. Consume the stream to completion to persist message history and semantic recall.

package/.docs/reference/deployer/vercel.md

@@ -45,13 +45,14 @@ export const mastra = new Mastra({
 
 ## Constructor options
 
-The deployer accepts overrides that are written to the Vercel Output API function config (`.vc-config.json`):
+The deployer accepts the following options:
 
+- `studio?: boolean` — Deploy [Studio](https://mastra.ai/docs/getting-started/studio) alongside your API as static assets served from Vercel's Edge CDN. Defaults to `false`.
 - `maxDuration?: number` — Function execution timeout (in seconds)
 - `memory?: number` — Function memory (in MB)
 - `regions?: string[]` — Regions to deploy the function (e.g. `['sfo1','iad1']`)
 
-These options are merged into `.vercel/output/functions/index.func/.vc-config.json` while preserving default fields (`handler`, `launcherType`, `runtime`, `shouldAddHelpers`).
+The `maxDuration`, `memory`, and `regions` options are merged into `.vercel/output/functions/index.func/.vc-config.json` while preserving default fields (`handler`, `launcherType`, `runtime`, `shouldAddHelpers`).
 
 ### Example with overrides
 
@@ -61,6 +62,7 @@ import { VercelDeployer } from '@mastra/deployer-vercel'
 
 export const mastra = new Mastra({
   deployer: new VercelDeployer({
+    studio: true,
     maxDuration: 600,
     memory: 1536,
     regions: ['sfo1', 'iad1'],
@@ -74,13 +76,34 @@ After running `mastra build`, the deployer generates a `.vercel/output` director
 
 The output contains:
 
-- **config.json** — Routing configuration that directs all requests to your function
+- **config.json** — Routing configuration that directs requests to the appropriate handler
 - **functions/** — Your Mastra server bundled as a serverless function
+- **static/** — Studio SPA assets (only when `studio: true`)
+
+Without studio:
+
+```bash
+.vercel/
+└── output/
+    ├── config.json
+    └── functions/
+        └── index.func/
+            ├── .vc-config.json
+            ├── index.mjs
+            └── node_modules/
+```
+
+With `studio: true`:
 
 ```bash
 .vercel/
 └── output/
     ├── config.json
+    ├── static/
+    │   ├── index.html
+    │   └── assets/
+    │       ├── *.js
+    │       └── *.css
     └── functions/
         └── index.func/
             ├── .vc-config.json
@@ -88,4 +111,6 @@ The output contains:
             └── node_modules/
 ```
 
+When studio is enabled, the routing is configured so that `/api/*` requests are handled by the serverless function, static assets (JS, CSS) are served from Vercel's Edge CDN with no function invocations, and all other paths fall back to `index.html` for client-side routing.
+
 This folder is generated during build and should not be committed to version control.

package/.docs/reference/harness/harness-class.md

@@ -2,6 +2,8 @@
 
 **Added in:** `@mastra/core@1.5.0`
 
+> **Warning:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
+
 The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
 
 ## Usage example
@@ -106,6 +108,10 @@ Each entry in the `subagents` array defines a subagent the harness can spawn.
 
 **defaultModelId?:** (`string`): Default model ID for this subagent type.
 
+**maxSteps?:** (`number`): Optional maximum number of steps for the spawned subagent. Defaults to \`50\` when omitted.
+
+**stopWhen?:** (`LoopOptions['stopWhen']`): Optional stop condition for the spawned subagent.
+
 ## Properties
 
 **id:** (`string`): Harness identifier, set at construction.
@@ -302,6 +308,23 @@ Update the title of the current thread.
 await harness.renameThread({ title: 'Updated title' })
 ```
 
+#### `cloneThread({ sourceThreadId?, title?, resourceId? })`
+
+Clone an existing thread and switch to the clone. Copies all messages, acquires a lock on the new thread, releases the lock on the previous thread, and emits a `thread_created` event. If `sourceThreadId` is omitted, the current thread is cloned. When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, OM records are cloned with remapped message IDs.
+
+```typescript
+// Clone the current thread
+const cloned = await harness.cloneThread()
+
+// Clone a specific thread with a custom title
+const cloned = await harness.cloneThread({
+  sourceThreadId: 'thread-abc123',
+  title: 'Alternative approach',
+})
+```
+
+See [`Memory.cloneThread()`](https://mastra.ai/reference/memory/cloneThread) for details on what gets cloned.
+
 #### `getResourceId()`
 
 Return the current resource ID.
@@ -329,9 +352,9 @@ const session = await harness.getSession()
 
 ### Messages
 
-#### `sendMessage({ content, images? })`
+#### `sendMessage({ content, files?, requestContext? })`
 
-Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically.
+Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically. If you provide `requestContext`, the harness forwards it to tools and subagents during the run.
 
 ```typescript
 await harness.sendMessage({ content: 'Explain the authentication flow' })
@@ -364,6 +387,34 @@ Retrieve the first user message for a given thread.
 const firstMsg = await harness.getFirstUserMessageForThread({ threadId: 'thread-abc123' })
 ```
 
+### Memory
+
+The `memory` property exposes thread management operations. These are also available as top-level methods on the harness.
+
+#### `memory.createThread({ title? })`
+
+Create a new thread. Same as `harness.createThread()`.
+
+#### `memory.switchThread({ threadId })`
+
+Switch to a different thread. Same as `harness.switchThread()`.
+
+#### `memory.listThreads(options?)`
+
+List threads from storage. Same as `harness.listThreads()`.
+
+#### `memory.renameThread({ title })`
+
+Update the title of the current thread. Same as `harness.renameThread()`.
+
+#### `memory.deleteThread({ threadId })`
+
+Delete a thread and all its messages from storage. If the deleted thread is the currently active thread, the thread lock is released and the harness clears its active thread. Emits a `thread_deleted` event.
+
+```typescript
+await harness.memory.deleteThread({ threadId: 'thread-abc123' })
+```
+
 ### Flow control
 
 #### `abort()`
@@ -374,7 +425,7 @@ Abort any in-progress generation.
 harness.abort()
 ```
 
-#### `steer({ content })`
+#### `steer({ content, requestContext? })`
 
 Steer the agent mid-stream by injecting an instruction into the current generation.
 
@@ -382,7 +433,7 @@ Steer the agent mid-stream by injecting an instruction into the current generati
 harness.steer({ content: 'Focus on security implications' })
 ```
 
-#### `followUp({ content })`
+#### `followUp({ content, requestContext? })`
 
 Queue a follow-up message to be sent after the current generation completes. If no operation is running, sends the message immediately.
 
@@ -392,7 +443,7 @@ harness.followUp({ content: 'Now apply those changes' })
 
 ### Tool approvals
 
-#### `respondToToolApproval({ decision })`
+#### `respondToToolApproval({ decision, requestContext? })`
 
 Respond to a pending tool approval request. Called when a `tool_approval_required` event is received.
 
@@ -494,7 +545,7 @@ Return the current workspace instance, or `undefined` if no workspace is configu
 const workspace = harness.getWorkspace()
 ```
 
-#### `resolveWorkspace()`
+#### `resolveWorkspace({ requestContext? })`
 
 Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
 
@@ -659,6 +710,7 @@ The harness emits events through registered listeners. The following table lists
 | `model_changed`            | The active model changed.                                           |
 | `thread_changed`           | The active thread changed.                                          |
 | `thread_created`           | A new thread was created.                                           |
+| `thread_deleted`           | A thread was deleted.                                               |
 | `state_changed`            | Harness state was updated.                                          |
 | `agent_start`              | The agent started processing.                                       |
 | `agent_end`                | The agent finished processing.                                      |

package/.docs/reference/index.md

@@ -106,7 +106,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Tool Call Accuracy Scorers](https://mastra.ai/reference/evals/tool-call-accuracy)
 - [Toxicity](https://mastra.ai/reference/evals/toxicity)
 - [Harness Class](https://mastra.ai/reference/harness/harness-class)
-- [createMastraCode()](https://mastra.ai/reference/mastra-code/createMastraCode)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)
 - [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
@@ -267,6 +266,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.start()](https://mastra.ai/reference/workflows/run-methods/start)
 - [.startAsync()](https://mastra.ai/reference/workflows/run-methods/startAsync)
 - [.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
+- [DaytonaSandbox](https://mastra.ai/reference/workspace/daytona-sandbox)
 - [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [GCSFilesystem](https://mastra.ai/reference/workspace/gcs-filesystem)
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)

package/.docs/reference/memory/cloneThread.md

@@ -44,6 +44,8 @@ const { thread, clonedMessages } = await memory.cloneThread({
 
 **clonedMessages:** (`MastraDBMessage[]`): Array of the cloned messages with new IDs assigned to the new thread.
 
+**messageIdMap?:** (`Record<string, string>`): A mapping from source message IDs to their corresponding cloned message IDs.
+
 ### Clone Metadata
 
 The cloned thread's metadata includes a `clone` property with:
@@ -127,4 +129,14 @@ const results = await memory.recall({
   threadId: thread.id,
   vectorSearchString: 'search query',
 })
-```
+```
+
+## Observational Memory
+
+When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, `cloneThread()` automatically clones the OM records associated with the source thread. The behavior depends on the OM scope:
+
+- **Thread-scoped OM**: The OM record is cloned to the new thread. All internal message ID references are remapped to point to the cloned messages.
+- **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
+- **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
+
+Only the current (most recent) OM generation is cloned — older history generations are not copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

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

@@ -107,6 +107,8 @@ export const agent = new Agent({
 
 ### Shared token budget
 
+When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
@@ -132,10 +134,10 @@ export const agent = new Agent({
 })
 ```
 
-When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
-
 ### Custom model
 
+By passing a `model` in the config, you can use any model from Mastra's model router.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'

package/.docs/reference/streaming/agents/stream.md

@@ -211,6 +211,40 @@ await agent.stream('message for agent', {
 })
 ```
 
+## OpenAI WebSocket Transport
+
+Opt into OpenAI Responses WebSocket streaming via `providerOptions.openai.transport`. This only applies to streaming calls and is currently supported for direct OpenAI models (for example, `openai/gpt-4o`). If WebSocket streaming is unavailable, Mastra falls back to HTTP streaming. By default, Mastra closes the WebSocket when the stream finishes.
+
+```ts
+const stream = await agent.stream('Hello', {
+  providerOptions: {
+    openai: {
+      transport: 'websocket', // 'websocket' | 'fetch' | 'auto'
+      websocket: {
+        url: 'wss://api.openai.com/v1/responses',
+        closeOnFinish: true, // default
+      },
+    },
+  },
+})
+```
+
+To keep the connection open after the stream finishes, set `closeOnFinish: false` and close it manually.
+
+```ts
+const stream = await agent.stream('Hello', {
+  providerOptions: {
+    openai: {
+      transport: 'websocket',
+      websocket: { closeOnFinish: false },
+    },
+  },
+})
+
+// Later, when you're done with the connection:
+stream.transport?.close()
+```
+
 ## Related
 
 - [Generating responses](https://mastra.ai/docs/agents/overview)

package/.docs/reference/tools/create-tool.md

@@ -27,6 +27,52 @@ export const tool = createTool({
 })
 ```
 
+## Example with `toModelOutput`
+
+Use `toModelOutput` when your tool should return rich internal data to your app, but the model should receive either a simplified value or multimodal content.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get weather for a city',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    city: z.string(),
+    temperature: z.number(),
+    condition: z.string(),
+    radarImageUrl: z.string().url(),
+  }),
+  execute: async ({ city }) => ({
+    city,
+    temperature: 72,
+    condition: 'sunny',
+    radarImageUrl: 'https://example.com/radar/seattle.png',
+  }),
+  toModelOutput: output => {
+    return {
+      type: 'content',
+      value: [
+        { type: 'text', text: `${output.city}: ${output.temperature}F and ${output.condition}` },
+        { type: 'image-url', url: output.radarImageUrl },
+      ],
+    }
+  },
+})
+```
+
+The tool still returns the full `execute` result to your application, while the model receives the transformed `toModelOutput` value.
+
+`toModelOutput` can return:
+
+- `type: 'text'`
+- `type: 'json'`
+- `type: 'content'` with parts like `text`, `image-url`, `image-data`, `file-url`, `file-data`, `file-id`, `image-file-id`, or `custom`
+
 ## Example with MCP Annotations
 
 When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
@@ -74,6 +120,8 @@ export const weatherTool = createTool({
 
 **outputSchema?:** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
 
+**toModelOutput?:** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
+
 **suspendSchema?:** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
 
 **resumeSchema?:** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.