@mastra/mcp-docs-server 0.13.20 → 0.13.21-alpha.0

package/.docs/raw/reference/agents/generateVNext.mdx

@@ -0,0 +1,519 @@
+---
+title: "Reference: Agent.generateVNext() (Experimental) | Agents | Mastra Docs"
+description: "Documentation for the `Agent.generateVNext()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
+---
+
+import { GenerateVNextCallout } from "@/components/generateVNext-callout.tsx"
+
+# Agent.generateVNext() (Experimental)
+
+<GenerateVNextCallout />
+
+The `.generateVNext()` method enables non-streaming response generation from an agent, with enhanced capabilities and flexible output formats. It accepts messages and optional generation options, supporting both Mastra’s native format and AI SDK v5 compatibility.
+
+## Usage example
+
+```typescript copy
+// Default Mastra format
+const mastraResult = await agent.generateVNext("message for agent");
+
+// AI SDK v5 compatible format
+const aiSdkResult = await agent.generateVNext("message for agent", {
+  format: 'aisdk'
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]",
+      description: "The messages to send to the agent. Can be a single string, array of strings, or structured message objects.",
+    },
+    {
+      name: "options",
+      type: "AgentExecutionOptions<Output, StructuredOutput, Format>",
+      isOptional: true,
+      description: "Optional configuration for the generation process.",
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "format",
+      type: "'mastra' | 'aisdk'",
+      isOptional: true,
+      defaultValue: "'mastra'",
+      description: "Determines the output format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
+    },
+    {
+      name: "maxSteps",
+      type: "number",
+      isOptional: true,
+      description: "Maximum number of steps to run during execution.",
+    },
+    {
+      name: "scorers",
+      type: "MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>",
+      isOptional: true,
+      description: "Evaluation scorers to run on the execution results.",
+      properties: [
+        {
+          parameters: [{
+            name: "scorer",
+            type: "string",
+            isOptional: false,
+            description: "Name of the scorer to use."
+          }]
+        },
+        {
+          parameters: [{
+            name: "sampling",
+            type: "ScoringSamplingConfig",
+            isOptional: true,
+            description: "Sampling configuration for the scorer.",
+            properties: [
+              {
+                parameters: [{
+                  name: "type",
+                  type: "'none' | 'ratio'",
+                  isOptional: false,
+                  description: "Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling."
+                }]
+              },
+              {
+                parameters: [{
+                  name: "rate",
+                  type: "number",
+                  isOptional: true,
+                  description: "Sampling rate (0-1). Required when type is 'ratio'."
+                }]
+              }
+            ]
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      isOptional: true,
+      description: "AI tracing context for span hierarchy and metadata.",
+    },
+    {
+      name: "returnScorerData",
+      type: "boolean",
+      isOptional: true,
+      description: "Whether to return detailed scoring data in the response.",
+    },
+    {
+      name: "onChunk",
+      type: "(chunk: ChunkType) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called for each chunk during generation.",
+    },
+    {
+      name: "onError",
+      type: "({ error }: { error: Error | string }) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called when an error occurs during generation.",
+    },
+    {
+      name: "onAbort",
+      type: "(event: any) => Promise<void> | void",
+      isOptional: true,
+      description: "Callback function called when the generation is aborted.",
+    },
+    {
+      name: "activeTools",
+      type: "Array<keyof ToolSet> | undefined",
+      isOptional: true,
+      description: "Array of tool names that should be active during execution. If undefined, all available tools are active.",
+    },
+    {
+      name: "abortSignal",
+      type: "AbortSignal",
+      isOptional: true,
+      description: "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
+    },
+    {
+      name: "prepareStep",
+      type: "PrepareStepFunction<any>",
+      isOptional: true,
+      description: "Callback function called before each step of multi-step execution.",
+    },
+    {
+      name: "context",
+      type: "ModelMessage[]",
+      isOptional: true,
+      description: "Additional context messages to provide to the agent.",
+    },
+    {
+      name: "structuredOutput",
+      type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
+      isOptional: true,
+      description: "Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.",
+      properties: [
+        {
+          parameters: [{
+            name: "schema",
+            type: "z.ZodSchema<S>",
+            isOptional: false,
+            description: "Zod schema defining the expected output structure."
+          }]
+        },
+        {
+          parameters: [{
+            name: "model",
+            type: "MastraLanguageModel",
+            isOptional: true,
+            description: "Language model to use for structured output generation. If not provided, uses the agent's default model."
+          }]
+        },
+        {
+          parameters: [{
+            name: "errorStrategy",
+            type: "'strict' | 'warn' | 'fallback'",
+            isOptional: true,
+            description: "Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values."
+          }]
+        },
+        {
+          parameters: [{
+            name: "fallbackValue",
+            type: "<S extends ZodTypeAny>",
+            isOptional: true,
+            description: "Fallback value to use when schema validation fails and errorStrategy is 'fallback'."
+          }]
+        },
+        {
+          parameters: [{
+            name: "instructions",
+            type: "string",
+            isOptional: true,
+            description: "Additional instructions for structured output generation."
+          }]
+        }
+      ]
+    },
+    {
+      name: "outputProcessors",
+      type: "Processor[]",
+      isOptional: true,
+      description: "Output processors to use for this execution (overrides agent's default).",
+    },
+    {
+      name: "inputProcessors",
+      type: "Processor[]",
+      isOptional: true,
+      description: "Input processors to use for this execution (overrides agent's default).",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description: "Custom instructions that override the agent's default instructions for this execution.",
+    },
+    {
+      name: "output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description: "Schema for structured output generation (Zod schema or JSON Schema).",
+    },
+    {
+      name: "memory",
+      type: "object",
+      isOptional: true,
+      description: "Memory configuration for conversation persistence and retrieval.",
+      properties: [
+        {
+          parameters: [{
+            name: "thread",
+            type: "string | { id: string; metadata?: Record<string, any>, title?: string }",
+            isOptional: false,
+            description: "Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title."
+          }]
+        },
+        {
+          parameters: [{
+            name: "resource",
+            type: "string",
+            isOptional: false,
+            description: "Resource identifier for organizing conversations by user, session, or context."
+          }]
+        },
+        {
+          parameters: [{
+            name: "options",
+            type: "MemoryConfig",
+            isOptional: true,
+            description: "Additional memory configuration options for conversation management."
+          }]
+        }
+      ]
+    },
+    {
+      name: "onFinish",
+      type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
+      isOptional: true,
+      description: "Callback fired when generation completes. Type varies by format.",
+    },
+    {
+      name: "onStepFinish",
+      type: "StreamTextOnStepFinishCallback<any> | never",
+      isOptional: true,
+      description: "Callback fired after each generation step. Type varies by format.",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      isOptional: true,
+      description: "Deprecated. Use memory.resource instead. Identifier for the resource/user.",
+    },
+    {
+      name: "telemetry",
+      type: "TelemetrySettings",
+      isOptional: true,
+      description: "Telemetry collection settings for observability.",
+      properties: [
+        {
+          parameters: [{
+            name: "isEnabled",
+            type: "boolean",
+            isOptional: true,
+            description: "Whether telemetry collection is enabled."
+          }]
+        },
+        {
+          parameters: [{
+            name: "recordInputs",
+            type: "boolean",
+            isOptional: true,
+            description: "Whether to record input data in telemetry."
+          }]
+        },
+        {
+          parameters: [{
+            name: "recordOutputs",
+            type: "boolean",
+            isOptional: true,
+            description: "Whether to record output data in telemetry."
+          }]
+        },
+        {
+          parameters: [{
+            name: "functionId",
+            type: "string",
+            isOptional: true,
+            description: "Identifier for the function being executed."
+          }]
+        }
+      ]
+    },
+    {
+      name: "modelSettings",
+      type: "CallSettings",
+      isOptional: true,
+      description: "Model-specific settings like temperature, topP, etc.",
+      properties: [
+        {
+          parameters: [{
+            name: "temperature",
+            type: "number",
+            isOptional: true,
+            description: "Controls randomness in generation (0-2). Higher values make output more random."
+          }]
+        },
+        {
+          parameters: [{
+            name: "maxRetries",
+            type: "number",
+            isOptional: true,
+            description: "Maximum number of retry attempts for failed requests."
+          }]
+        },
+        {
+          parameters: [{
+            name: "topP",
+            type: "number",
+            isOptional: true,
+            description: "Nucleus sampling parameter (0-1). Controls diversity of generated text."
+          }]
+        },
+        {
+          parameters: [{
+            name: "topK",
+            type: "number",
+            isOptional: true,
+            description: "Top-k sampling parameter. Limits vocabulary to k most likely tokens."
+          }]
+        },
+        {
+          parameters: [{
+            name: "presencePenalty",
+            type: "number",
+            isOptional: true,
+            description: "Penalty for token presence (-2 to 2). Reduces repetition."
+          }]
+        },
+        {
+          parameters: [{
+            name: "frequencyPenalty",
+            type: "number",
+            isOptional: true,
+            description: "Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens."
+          }]
+        },
+        {
+          parameters: [{
+            name: "stopSequences",
+            type: "string[]",
+            isOptional: true,
+            description: "Array of strings that will stop generation when encountered."
+          }]
+        }
+      ]
+    },
+    {
+      name: "threadId",
+      type: "string",
+      isOptional: true,
+      description: "Deprecated. Use memory.thread instead. Thread identifier for conversation continuity.",
+    },
+    {
+      name: "toolChoice",
+      type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
+      isOptional: true,
+      description: "Controls how tools are selected during generation.",
+      properties: [
+        {
+          parameters: [{
+            name: "'auto'",
+            type: "string",
+            isOptional: false,
+            description: "Let the model decide when to use tools (default)."
+          }]
+        },
+        {
+          parameters: [{
+            name: "'none'",
+            type: "string",
+            isOptional: false,
+            description: "Disable tool usage entirely."
+          }]
+        },
+        {
+          parameters: [{
+            name: "'required'",
+            type: "string",
+            isOptional: false,
+            description: "Force the model to use at least one tool."
+          }]
+        },
+        {
+          parameters: [{
+            name: "{ type: 'tool'; toolName: string }",
+            type: "object",
+            isOptional: false,
+            description: "Force the model to use a specific tool."
+          }]
+        }
+      ]
+    },
+    {
+      name: "toolsets",
+      type: "ToolsetsInput",
+      isOptional: true,
+      description: "Additional tool sets that can be used for this execution.",
+    },
+    {
+      name: "clientTools",
+      type: "ToolsInput",
+      isOptional: true,
+      description: "Client-side tools available during execution.",
+    },
+    {
+      name: "savePerStep",
+      type: "boolean",
+      isOptional: true,
+      description: "Save messages incrementally after each generation step completes (default: false).",
+    },
+    {
+      name: "providerOptions",
+      type: "Record<string, Record<string, JSONValue>>",
+      isOptional: true,
+      description: "Provider-specific options passed to the language model.",
+      properties: [
+        {
+          parameters: [{
+            name: "openai",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "OpenAI-specific options like reasoningEffort, responseFormat, etc."
+          }]
+        },
+        {
+          parameters: [{
+            name: "anthropic",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Anthropic-specific options like maxTokens, etc."
+          }]
+        },
+        {
+          parameters: [{
+            name: "google",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Google-specific options."
+          }]
+        },
+        {
+          parameters: [{
+            name: "[providerName]",
+            type: "Record<string, JSONValue>",
+            isOptional: true,
+            description: "Any provider-specific options."
+          }]
+        }
+      ]
+    },
+    {
+      name: "runId",
+      type: "string",
+      isOptional: true,
+      description: "Unique identifier for this execution run.",
+    },
+    {
+      name: "runtimeContext",
+      type: "RuntimeContext",
+      isOptional: true,
+      description: "Runtime context containing dynamic configuration and state.",
+    },
+    {
+      name: "stopWhen",
+      type: "StopCondition | StopCondition[]",
+      isOptional: true,
+      description: "Conditions for stopping execution (e.g., step count, token limit).",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>> | Awaited<ReturnType<AISDKV5OutputStream<Output>['getFullOutput']>>",
+      description: "Returns the full output of the generation process. When format is 'mastra' (default), returns MastraModelOutput result. When format is 'aisdk', returns AISDKV5OutputStream result for AI SDK v5 compatibility.",
+    },
+  ]}
+/>
+

package/.docs/raw/reference/agents/streamVNext.mdx

@@ -142,6 +142,12 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       isOptional: true,
       description: "Array of active tool names that can be used during execution."
     },
+    {
+      name: "prepareStep",
+      type: "PrepareStepFunction<any>",
+      isOptional: true,
+      description: "Callback function called before each step of multi-step execution.",
+    },
     {
       name: "context",
       type: "ModelMessage[]",
@@ -208,13 +214,6 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       isOptional: true,
       description: "Overrides the input processors set on the agent. Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
     },
-    {
-      name: "experimental_output",
-      type: "Zod schema | JsonSchema7",
-      isOptional: true,
-      description:
-        "Note, the preferred route is to use the `structuredOutput` property. Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
-    },
     {
       name: "instructions",
       type: "string",
@@ -261,13 +260,6 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
         }
       ]
     },
-    {
-      name: "memoryOptions",
-      type: "MemoryConfig",
-      isOptional: true,
-      description:
-        "**Deprecated.** Use `memory.options` instead. Configuration options for memory management.",
-    },
     {
       name: "onFinish",
       type: "StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>",
@@ -517,12 +509,6 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       isOptional: true,
       description: "Condition(s) that determine when to stop the agent's execution. Can be a single condition or array of conditions.",
     },
-    {
-      name: "headers",
-      type: "Record<string, string | undefined>",
-      isOptional: true,
-      description: "Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.",
-    }
   ]}
 />
 

package/.docs/raw/reference/auth/clerk.mdx

@@ -0,0 +1,71 @@
+---
+title: "MastraAuthClerk Class"
+description: "API reference for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication."
+---
+
+# MastraAuthClerk Class
+
+The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthClerk } from '@mastra/clerk-auth';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthClerk({
+      jwksUri: process.env.CLERK_JWKS_URI,
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+    }),
+  },
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "publishableKey",
+      type: "string",
+      description: "Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys.",
+      isOptional: true,
+      defaultValue: "process.env.CLERK_PUBLISHABLE_KEY"
+    },
+    {
+      name: "secretKey",
+      type: "string",
+      description: "Your Clerk secret key. Used for server-side authentication and token verification.",
+      isOptional: true,
+      defaultValue: "process.env.CLERK_SECRET_KEY"
+    },
+    {
+      name: "jwksUri",
+      type: "string",
+      description: "The JWKS URI from your Clerk application. Used to verify JWT signatures.",
+      isOptional: true,
+      defaultValue: "process.env.CLERK_JWKS_URI"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: User, request: HonoRequest) => Promise<boolean> | boolean",
+      description: "Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Related
+
+[MastraAuthClerk Class](/docs/auth/clerk.mdx)
+