@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.7

package/.docs/raw/reference/storage/convex.mdx

@@ -0,0 +1,164 @@
+---
+title: "Reference: Convex Storage | Storage"
+description: Documentation for the Convex storage implementation in Mastra.
+---
+
+# Convex Storage
+
+The Convex storage implementation provides a serverless storage solution using [Convex](https://convex.dev), a full-stack TypeScript development platform with real-time sync and automatic caching.
+
+## Installation
+
+```bash copy
+npm install @mastra/convex@beta
+```
+
+## Convex Setup
+
+Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
+
+### 1. Set up Convex Schema
+
+In `convex/schema.ts`:
+
+```typescript copy
+import { defineSchema } from 'convex/server';
+import {
+  mastraThreadsTable,
+  mastraMessagesTable,
+  mastraResourcesTable,
+  mastraWorkflowSnapshotsTable,
+  mastraScoresTable,
+  mastraVectorIndexesTable,
+  mastraVectorsTable,
+  mastraDocumentsTable,
+} from '@mastra/convex/server';
+
+export default defineSchema({
+  mastra_threads: mastraThreadsTable,
+  mastra_messages: mastraMessagesTable,
+  mastra_resources: mastraResourcesTable,
+  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
+  mastra_scorers: mastraScoresTable,
+  mastra_vector_indexes: mastraVectorIndexesTable,
+  mastra_vectors: mastraVectorsTable,
+  mastra_documents: mastraDocumentsTable,
+});
+```
+
+### 2. Create the Storage Handler
+
+In `convex/mastra/storage.ts`:
+
+```typescript copy
+import { mastraStorage } from '@mastra/convex/server';
+
+export const handle = mastraStorage;
+```
+
+### 3. Deploy to Convex
+
+```bash copy
+npx convex dev
+# or for production
+npx convex deploy
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { ConvexStore } from "@mastra/convex";
+
+const storage = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "deploymentUrl",
+      type: "string",
+      description:
+        "Convex deployment URL (e.g., https://your-project.convex.cloud)",
+      isOptional: false,
+    },
+    {
+      name: "adminAuthToken",
+      type: "string",
+      description:
+        "Convex admin authentication token for backend access",
+      isOptional: false,
+    },
+    {
+      name: "storageFunction",
+      type: "string",
+      description:
+        "Path to the storage mutation function (default: 'mastra/storage:handle')",
+      isOptional: true,
+      defaultValue: "mastra/storage:handle",
+    },
+  ]}
+/>
+
+## Constructor Examples
+
+```ts
+import { ConvexStore } from "@mastra/convex";
+
+// Basic configuration
+const store = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+});
+
+// With custom storage function path
+const storeCustom = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+  storageFunction: "custom/path:handler",
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation uses typed Convex tables for each Mastra domain:
+
+| Domain         | Convex Table                | Purpose              |
+| -------------- | --------------------------- | -------------------- |
+| Threads        | `mastra_threads`            | Conversation threads |
+| Messages       | `mastra_messages`           | Chat messages        |
+| Resources      | `mastra_resources`          | User working memory  |
+| Workflows      | `mastra_workflow_snapshots` | Workflow state       |
+| Scorers        | `mastra_scorers`            | Evaluation data      |
+| Fallback       | `mastra_documents`          | Unknown tables       |
+
+### Architecture
+
+All typed tables include:
+
+- An `id` field for Mastra's record ID (distinct from Convex's auto-generated `_id`)
+- A `by_record_id` index for efficient lookups by Mastra ID
+
+This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.
+
+### Environment Variables
+
+Set these environment variables for your deployment:
+
+- `CONVEX_URL` – Your Convex deployment URL
+- `CONVEX_ADMIN_KEY` – Admin authentication token (get from Convex dashboard)
+
+## Related
+
+- [Convex Vector Store](../vectors/convex)
+- [Convex Documentation](https://docs.convex.dev/)
+

package/.docs/raw/reference/storage/lance.mdx

@@ -73,6 +73,39 @@ The LanceStorage implementation automatically handles schema creation and update
 - `jsonb`, `json` → Utf8 (serialized)
 - `binary` → Binary
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { LanceStorage } from "@mastra/lance";
+
+const storage = await LanceStorage.create("my-storage", "/path/to/db");
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { LanceStorage } from "@mastra/lance";
+
+const storage = await LanceStorage.create("my-storage", "/path/to/db");
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Deployment Options
 
 LanceDB storage can be configured for different deployment scenarios:

package/.docs/raw/reference/storage/libsql.mdx

@@ -74,3 +74,40 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_traces`: Stores telemetry and tracing data
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: "file:./storage.db",
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: "file:./storage.db",
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::

package/.docs/raw/reference/storage/mongodb.mdx

@@ -93,6 +93,45 @@ The storage implementation handles collection creation and management automatica
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { MongoDBStore } from "@mastra/mongodb";
+
+const storage = new MongoDBStore({
+  url: process.env.MONGODB_URL,
+  dbName: process.env.MONGODB_DATABASE,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the collections:
+
+```typescript copy
+import { MongoDBStore } from "@mastra/mongodb";
+
+const storage = new MongoDBStore({
+  url: process.env.MONGODB_URL,
+  dbName: process.env.MONGODB_DATABASE,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, collections won't be created and storage operations will fail silently or throw errors.
+:::
+
 ## Vector Search Capabilities
 
 MongoDB storage includes built-in vector search capabilities for AI applications:

package/.docs/raw/reference/storage/mssql.mdx

@@ -101,6 +101,43 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Direct Database and Pool Access
 
 `MSSQLStore` exposes the mssql connection pool as public fields:

package/.docs/raw/reference/storage/postgresql.mdx

@@ -101,6 +101,43 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript copy
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Now you can use the storage
+await storage.getThread({ threadId: "..." });
+```
+
+:::warning
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+:::
+
 ### Direct Database and Pool Access
 
 `PostgresStore` exposes both the underlying database object and the pg-promise instance as public fields:

package/.docs/raw/reference/streaming/ChunkType.mdx

@@ -1325,4 +1325,4 @@ for await (const chunk of stream.fullStream) {
 
 - [.stream()](./agents/stream) - Method that returns streams emitting these chunks
 - [MastraModelOutput](./agents/MastraModelOutput) - The stream object that emits these chunks
-- [workflow.streamVNext()](./workflows/streamVNext) - Method that returns streams emitting these chunks for workflows
+- [workflow.stream()](./workflows/stream) - Method that returns streams emitting these chunks for workflows

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -245,6 +245,17 @@ const aiSdkStream = await agent.stream("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "providerOptions",
+              type: "ProviderOptions",
+              isOptional: true,
+              description:
+                "Provider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`).",
+            },
+          ],
+        },
       ],
     },
     {
@@ -584,6 +595,50 @@ const aiSdkStream = await agent.stream("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
       ],
     },
   ]}
@@ -713,7 +768,7 @@ await agent.stream("message for agent", {
   },
   // Output processors for streaming response validation
   outputProcessors: [
-    new ModerationProcessor({ model: "openai/gpt-4.1-nano" }),
+    new ModerationProcessor({ model: "openrouter/openai/gpt-oss-safeguard-20b" }),
     new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
   ],
 });

package/.docs/raw/reference/streaming/workflows/observeStream.mdx

@@ -18,7 +18,7 @@ run.stream({
   },
 });
 
-const { stream } = await run.observeStream();
+const stream = await run.observeStream();
 
 for await (const chunk of stream) {
   console.log(chunk);
@@ -33,17 +33,15 @@ for await (const chunk of stream) {
 
 The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
-- **`start`**: Workflow execution begins
-- **`step-start`**: A step begins execution
-- **`tool-call`**: A tool call is initiated
-- **`tool-call-streaming-start`**: Tool call streaming begins
-- **`tool-call-delta`**: Incremental tool output updates
-- **`step-result`**: A step completes with results
-- **`step-finish`**: A step finishes execution
-- **`finish`**: Workflow execution completes
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
 
 ## Related
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
 - [Run.stream()](./stream)
+- [Run.resumeStream()](./resumeStream)

package/.docs/raw/reference/streaming/workflows/{resumeStreamVNext.mdx → resumeStream.mdx}

@@ -1,22 +1,18 @@
 ---
-title: "Reference: Run.resumeStreamVNext() (Experimental) | Streaming"
-description: Documentation for the `Run.resumeStreamVNext()` method in workflows, which enables real-time resumption and streaming of suspended workflow runs.
+title: "Reference: Run.resumeStream() | Streaming"
+description: Documentation for the `Run.resumeStream()` method in workflows, which enables real-time resumption and streaming of suspended workflow runs.
 ---
 
-# Run.resumeStreamVNext() (Experimental)
+# Run.resumeStream()
 
-:::caution Experimental Feature
-This is an experimental API that may change in future versions. The `resumeStreamVNext()` method is part of the enhanced streaming system that will eventually replace the current streaming methods. Use with caution in production environments.
-:::
-
-The `.resumeStreamVNext()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
+The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
 
 ## Usage example
 
 ```typescript showLineNumbers copy
 const run = await workflow.createRun();
 
-const stream = run.streamVNext({
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
@@ -25,7 +21,7 @@ const stream = run.streamVNext({
 const result = await stream.result;
 
 if (result!.status === "suspended") {
-  const resumedStream = await run.resumeStreamVNext({
+  const resumedStream = await run.resumeStream({
     resumeData: {
       value: "resume data",
     },
@@ -72,6 +68,50 @@ if (result!.status === "suspended") {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
       ],
     },
   ]}
@@ -119,4 +159,4 @@ The stream emits various event types during workflow execution. Each event has a
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
-- [Run.streamVNext()](./streamVNext)
+- [Run.stream()](./stream)