@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/reference/workflows/workflow.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Workflow Class | Workflows"
 description: Documentation for the `Workflow` class in Mastra, which enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+packages:
+  - "@mastra/core"
 ---
 
 # Workflow Class
@@ -9,7 +11,7 @@ The `Workflow` class enables you to create state machines for complex sequences
 
 ## Usage example
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -85,6 +87,172 @@ export const workflow = createWorkflow({
       isOptional: true,
       defaultValue: "() => true",
     },
+    {
+      name: "onFinish",
+      type: "(result: WorkflowFinishCallbackResult) => void | Promise<void>",
+      description:
+        "Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.",
+      isOptional: true,
+    },
+    {
+      name: "onError",
+      type: "(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>",
+      description:
+        "Callback invoked only when workflow fails (failed or tripwire status). Receives error details and step results. Errors thrown in this callback are caught and logged, not propagated.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### WorkflowFinishCallbackResult
+
+The result object passed to `onFinish` callbacks.
+
+<PropertiesTable
+  content={[
+    {
+      name: "status",
+      type: "WorkflowRunStatus",
+      description: "The workflow status: 'success', 'failed', 'suspended', or 'tripwire'",
+    },
+    {
+      name: "result",
+      type: "any",
+      description: "The workflow output (when status is 'success')",
+      isOptional: true,
+    },
+    {
+      name: "error",
+      type: "SerializedError",
+      description: "Error details (when status is 'failed')",
+      isOptional: true,
+    },
+    {
+      name: "steps",
+      type: "Record<string, StepResult>",
+      description: "Individual step results with their status and output",
+    },
+    {
+      name: "tripwire",
+      type: "StepTripwireInfo",
+      description: "Tripwire information (when status is 'tripwire')",
+      isOptional: true,
+    },
+    {
+      name: "runId",
+      type: "string",
+      description: "The unique identifier for this workflow run",
+    },
+    {
+      name: "workflowId",
+      type: "string",
+      description: "The workflow's identifier",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Optional resource identifier (if provided when creating the run)",
+      isOptional: true,
+    },
+    {
+      name: "getInitData",
+      type: "() => any",
+      description: "Function that returns the initial input data passed to the workflow",
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "The Mastra instance (if workflow is registered with Mastra)",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request-scoped context data",
+    },
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "The workflow's logger instance",
+    },
+    {
+      name: "state",
+      type: "Record<string, any>",
+      description: "The workflow's current state object",
+    },
+  ]}
+/>
+
+### WorkflowErrorCallbackInfo
+
+The error info object passed to `onError` callbacks.
+
+<PropertiesTable
+  content={[
+    {
+      name: "status",
+      type: "'failed' | 'tripwire'",
+      description: "The workflow status (either 'failed' or 'tripwire')",
+    },
+    {
+      name: "error",
+      type: "SerializedError",
+      description: "Error details",
+      isOptional: true,
+    },
+    {
+      name: "steps",
+      type: "Record<string, StepResult>",
+      description: "Individual step results with their status and output",
+    },
+    {
+      name: "tripwire",
+      type: "StepTripwireInfo",
+      description: "Tripwire information (when status is 'tripwire')",
+      isOptional: true,
+    },
+    {
+      name: "runId",
+      type: "string",
+      description: "The unique identifier for this workflow run",
+    },
+    {
+      name: "workflowId",
+      type: "string",
+      description: "The workflow's identifier",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Optional resource identifier (if provided when creating the run)",
+      isOptional: true,
+    },
+    {
+      name: "getInitData",
+      type: "() => any",
+      description: "Function that returns the initial input data passed to the workflow",
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "The Mastra instance (if workflow is registered with Mastra)",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request-scoped context data",
+    },
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "The workflow's logger instance",
+    },
+    {
+      name: "state",
+      type: "Record<string, any>",
+      description: "The workflow's current state object",
+    },
   ]}
 />
 
@@ -92,7 +260,7 @@ export const workflow = createWorkflow({
 
 When starting a workflow run, you can pass `initialState` to set the starting values for the workflow's state:
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.start({
@@ -130,9 +298,32 @@ A workflow's `status` indicates its current execution state. The possible values
       description:
         "Workflow execution is paused waiting for resume, with suspended step information",
     },
+    {
+      name: "tripwire",
+      type: "string",
+      description:
+        "Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.",
+    },
   ]}
 />
 
+### Handling tripwire status
+
+When a workflow contains an agent step that triggers a tripwire, the workflow returns with `status: 'tripwire'` and includes tripwire details:
+
+```typescript
+const run = await workflow.createRun();
+const result = await run.start({ inputData: { message: "Hello" } });
+
+if (result.status === "tripwire") {
+  console.log("Workflow terminated by tripwire:", result.tripwire?.reason);
+  console.log("Processor ID:", result.tripwire?.processorId);
+  console.log("Retry requested:", result.tripwire?.retry);
+}
+```
+
+This is distinct from `status: 'failed'` which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).
+
 ## Related
 
 - [Step Class](./step)

package/.docs/raw/{auth → server/auth}/auth0.mdx

@@ -1,6 +1,10 @@
 ---
 title: "MastraAuthAuth0 Class | Auth"
 description: "Documentation for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
+packages:
+  - "@mastra/auth-auth0"
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -19,20 +23,24 @@ This example uses Auth0 authentication. Make sure to:
 3. Configure an API in your Auth0 Dashboard with an identifier (audience)
 4. Configure your application's allowed callback URLs, web origins, and logout URLs
 
-```env title=".env" copy
+```env title=".env"
 AUTH0_DOMAIN=your-tenant.auth0.com
 AUTH0_AUDIENCE=your-api-identifier
 ```
 
-> **Note:** You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
+:::note
 
-> For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
+You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
+
+For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
+
+:::
 
 ## Installation
 
 Before you can use the `MastraAuthAuth0` class you have to install the `@mastra/auth-auth0` package.
 
-```bash copy
+```bash
 npm install @mastra/auth-auth0@beta
 ```
 
@@ -40,12 +48,11 @@ npm install @mastra/auth-auth0@beta
 
 ### Basic usage with environment variables
 
-```typescript {2,7} title="src/mastra/index.ts" showLineNumbers copy
+```typescript {2,6} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthAuth0 } from "@mastra/auth-auth0";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthAuth0(),
   },
@@ -54,12 +61,11 @@ export const mastra = new Mastra({
 
 ### Custom configuration
 
-```typescript {2,7-10} title="src/mastra/index.ts" showLineNumbers copy
+```typescript {2,6-9} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthAuth0 } from "@mastra/auth-auth0";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthAuth0({
       domain: process.env.AUTH0_DOMAIN,
@@ -82,7 +88,7 @@ By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth
 
 To customize user authorization, provide a custom `authorizeUser` function:
 
-```typescript title="src/mastra/auth.ts" showLineNumbers copy
+```typescript title="src/mastra/auth.ts"
 import { MastraAuthAuth0 } from "@mastra/auth-auth0";
 
 const auth0Provider = new MastraAuthAuth0({
@@ -93,7 +99,11 @@ const auth0Provider = new MastraAuthAuth0({
 });
 ```
 
-> See the [MastraAuthAuth0](/reference/v1/auth/auth0) API reference for all available configuration options.
+:::info
+
+Visit [MastraAuthAuth0](/reference/v1/auth/auth0) for all available configuration options.
+
+:::
 
 ## Client-side setup
 
@@ -103,11 +113,11 @@ When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate u
 
 First, install and configure the Auth0 React SDK in your application:
 
-```bash copy
+```bash
 npm install @auth0/auth0-react
 ```
 
-```typescript title="src/auth0-provider.tsx" showLineNumbers copy
+```typescript title="src/auth0-provider.tsx"
 import React from 'react';
 import { Auth0Provider } from '@auth0/auth0-react';
 
@@ -134,7 +144,7 @@ export default Auth0ProviderWithHistory;
 
 Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
 
-```typescript title="lib/auth.ts" showLineNumbers copy
+```typescript title="lib/auth.ts"
 import { useAuth0 } from "@auth0/auth0-react";
 
 export const useAuth0Token = () => {
@@ -149,13 +159,17 @@ export const useAuth0Token = () => {
 };
 ```
 
-> Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
+:::note
+
+Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
+
+:::
 
 ## Configuring `MastraClient`
 
 When `auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 access token in the `Authorization` header:
 
-```typescript title="lib/mastra/mastra-client.ts" showLineNumbers copy
+```typescript title="lib/mastra/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const createMastraClient = (accessToken: string) => {
@@ -168,9 +182,13 @@ export const createMastraClient = (accessToken: string) => {
 };
 ```
 
-> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+:::info
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+The access token must be prefixed with `Bearer` in the Authorization header.
+
+Visit [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
+
+:::
 
 ### Making authenticated requests
 
@@ -178,7 +196,8 @@ Once `MastraClient` is configured with the Auth0 access token, you can send auth
 
 <Tabs>
   <TabItem value="react" label="React">
-    ```tsx title="src/components/mastra-api-test.tsx" showLineNumbers copy
+
+    ```tsx title="src/components/mastra-api-test.tsx" copy
     import React, { useState } from 'react';
     import { useAuth0 } from '@auth0/auth0-react';
     import { MastraClient } from '@mastra/client-js';
@@ -198,9 +217,7 @@ Once `MastraClient` is configured with the Auth0 access token, you can send auth
         });
 
         const weatherAgent = mastra.getAgent("weatherAgent");
-        const response = await weatherAgent.generate({
-          messages: "What's the weather like in New York"
-        });
+        const response = await weatherAgent.generate("What's the weather like in New York");
 
         setResult(response.text);
       };
@@ -224,6 +241,7 @@ Once `MastraClient` is configured with the Auth0 access token, you can send auth
 
   </TabItem>
   <TabItem value="curl" label="cURL">
+
     ```bash copy
     curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
       -H "Content-Type: application/json" \
@@ -232,5 +250,6 @@ Once `MastraClient` is configured with the Auth0 access token, you can send auth
         "messages": "Weather in London"
       }'
     ```
+
   </TabItem>
 </Tabs>

package/.docs/raw/{auth → server/auth}/clerk.mdx

@@ -1,6 +1,10 @@
 ---
 title: "MastraAuthClerk Class | Auth"
 description: "Documentation for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication."
+packages:
+  - "@mastra/auth-clerk"
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -14,30 +18,33 @@ The `MastraAuthClerk` class provides authentication for Mastra using Clerk. It v
 
 This example uses Clerk authentication. Make sure to add your Clerk credentials to your `.env` file and ensure your Clerk project is properly configured.
 
-```env title=".env" copy
+```env title=".env"
 CLERK_PUBLISHABLE_KEY=pk_test_...
 CLERK_SECRET_KEY=sk_test_...
 CLERK_JWKS_URI=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.json
 ```
 
-> **Note:** You can find these keys in your Clerk Dashboard under "API Keys".
+:::note
+
+You can find these keys in your Clerk Dashboard under "API Keys".
+
+:::
 
 ## Installation
 
 Before you can use the `MastraAuthClerk` class you have to install the `@mastra/auth-clerk` package.
 
-```bash copy
+```bash
 npm install @mastra/auth-clerk@beta
 ```
 
 ## Usage example
 
-```typescript {2,7-11} title="src/mastra/index.ts" showLineNumbers copy
+```typescript {2,6-10} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthClerk } from "@mastra/auth-clerk";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthClerk({
       publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
@@ -48,9 +55,13 @@ export const mastra = new Mastra({
 });
 ```
 
-> **Note:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+:::info
+
+The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+
+Visit [MastraAuthClerk](/reference/v1/auth/clerk) for all available configuration options.
 
-> See the [MastraAuthClerk](/reference/v1/auth/clerk) API reference for all available configuration options.
+:::
 
 ## Client-side setup
 
@@ -60,7 +71,7 @@ When using Clerk auth, you'll need to retrieve the access token from Clerk on th
 
 Use the Clerk React hooks to authenticate users and retrieve their access token:
 
-```typescript title="lib/auth.ts" showLineNumbers copy
+```typescript title="lib/auth.ts"
 import { useAuth } from "@clerk/nextjs";
 
 export const useClerkAuth = () => {
@@ -75,13 +86,17 @@ export const useClerkAuth = () => {
 };
 ```
 
-> Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
+:::info
+
+Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
+
+:::
 
 ## Configuring `MastraClient`
 
 When `auth` is enabled, all requests made with `MastraClient` must include a valid Clerk access token in the `Authorization` header:
 
-```typescript {6} title="lib/mastra/mastra-client.ts" showLineNumbers copy
+```typescript {6} title="lib/mastra/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({
@@ -92,8 +107,13 @@ export const mastraClient = new MastraClient({
 });
 ```
 
-> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+:::info
+
+The access token must be prefixed with `Bearer` in the Authorization header.
+
+Visit [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
+
+:::
 
 ### Making authenticated requests
 
@@ -101,7 +121,8 @@ Once `MastraClient` is configured with the Clerk access token, you can send auth
 
 <Tabs>
   <TabItem value="react" label="React">
-    ```tsx title="src/components/test-agent.tsx" showLineNumbers copy
+
+    ```tsx title="src/components/test-agent.tsx" copy
     "use client";
 
     import { useAuth } from "@clerk/nextjs";
@@ -119,9 +140,7 @@ Once `MastraClient` is configured with the Clerk access token, you can send auth
         });
 
         const weatherAgent = client.getAgent("weatherAgent");
-        const response = await weatherAgent.generate({
-          messages: "What's the weather like in New York",
-        });
+        const response = await weatherAgent.generate("What's the weather like in New York");
 
         console.log({ response });
       }
@@ -132,6 +151,7 @@ Once `MastraClient` is configured with the Clerk access token, you can send auth
 
   </TabItem>
   <TabItem value="curl" label="cURL">
+
     ```bash copy
     curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
       -H "Content-Type: application/json" \
@@ -140,5 +160,6 @@ Once `MastraClient` is configured with the Clerk access token, you can send auth
         "messages": "Weather in London"
       }'
     ```
+
   </TabItem>
 </Tabs>