@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/reference/ai-sdk/to-ai-sdk-v4-messages.md

@@ -0,0 +1,79 @@
+# toAISdkV4Messages()
+
+Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+import { useChat } from 'ai/react' // AI SDK V4
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: '1', role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
+  { id: '2', role: 'assistant', parts: [{ type: 'text', text: 'Hi there!' }] },
+]
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV4Messages(storedMessages),
+  })
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Parameters
+
+**messages:** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
+
+## Returns
+
+Returns an array of AI SDK V4 `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**content:** (`string`): Text content of the message.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool-invocation, file, reasoning, source, and step markers.
+
+**createdAt:** (`Date`): Message creation timestamp.
+
+**toolInvocations?:** (`ToolInvocation[]`): Array of tool invocations for assistant messages.
+
+**experimental\_attachments?:** (`Attachment[]`): File attachments on the message.
+
+**metadata?:** (`Record<string, unknown>`): Custom metadata attached to the message.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+
+const messages = toAISdkV4Messages(['Hello', 'How can I help you today?'])
+// Returns array of UIMessage objects with user role and content string
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+
+const client = new MastraClient()
+
+const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
+const uiMessages = toAISdkV4Messages(messages)
+```

package/.docs/reference/ai-sdk/to-ai-sdk-v5-messages.md

@@ -0,0 +1,76 @@
+# toAISdkV5Messages()
+
+Converts messages from various input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+import { useChat } from 'ai/react'
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: '1', role: 'user', content: 'Hello', parts: [{ type: 'text', text: 'Hello' }] },
+  {
+    id: '2',
+    role: 'assistant',
+    content: 'Hi there!',
+    parts: [{ type: 'text', text: 'Hi there!' }],
+  },
+]
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV5Messages(storedMessages),
+  })
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role}: {message.parts.map(part => (part.type === 'text' ? part.text : null))}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Parameters
+
+**messages:** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
+
+## Returns
+
+Returns an array of AI SDK V5+ `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool results, files, reasoning, sources, and step markers.
+
+**metadata?:** (`Record<string, unknown>`): Optional metadata including createdAt, threadId, resourceId, and custom fields.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+
+const messages = toAISdkV5Messages(['Hello', 'How can I help you today?'])
+// Returns array of UIMessage objects with user role
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+
+const client = new MastraClient()
+
+const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
+const uiMessages = toAISdkV5Messages(messages)
+```

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

@@ -0,0 +1,59 @@
+# withMastra()
+
+Wraps an AI SDK model with Mastra processors and/or memory.
+
+## Usage example
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+import { withMastra } from '@mastra/ai-sdk'
+import type { Processor } from '@mastra/core/processors'
+
+const loggingProcessor: Processor<'logger'> = {
+  id: 'logger',
+  async processInput({ messages }) {
+    console.log('Input:', messages.length, 'messages')
+    return messages
+  },
+}
+
+const model = withMastra(openai('gpt-4o'), {
+  inputProcessors: [loggingProcessor],
+})
+
+const { text } = await generateText({
+  model,
+  prompt: 'What is 2 + 2?',
+})
+```
+
+## Parameters
+
+**model:** (`LanguageModelV2`): Any AI SDK language model (e.g., \`openai('gpt-4o')\`, \`anthropic('claude-3-opus')\`).
+
+**options?:** (`WithMastraOptions`): Configuration object for processors and memory.
+
+**options.inputProcessors?:** (`InputProcessor[]`): Input processors to run before the LLM call.
+
+**options.outputProcessors?:** (`OutputProcessor[]`): Output processors to run on the LLM response.
+
+**options.memory?:** (`WithMastraMemoryOptions`): Memory configuration - enables automatic message history persistence.
+
+**options.memory.storage:** (`MemoryStorage`): Memory storage domain for message persistence. Get it from a composite store using \`await storage.getStore('memory')\`.
+
+**options.memory.threadId:** (`string`): Thread ID for conversation persistence.
+
+**options.memory.resourceId?:** (`string`): Resource ID (user/session identifier).
+
+**options.memory.lastMessages?:** (`number | false`): Number of recent messages to retrieve, or false to disable.
+
+**options.memory.semanticRecall?:** (`WithMastraSemanticRecallOptions`): Semantic recall configuration (RAG-based memory retrieval).
+
+**options.memory.workingMemory?:** (`MemoryConfig['workingMemory']`): Working memory configuration (persistent user data).
+
+**options.memory.readOnly?:** (`boolean`): Read-only mode - prevents saving new messages.
+
+## Returns
+
+A wrapped model compatible with `generateText`, `streamText`, `generateObject`, and `streamObject`.

package/.docs/reference/ai-sdk/workflow-route.md

@@ -0,0 +1,79 @@
+# workflowRoute()
+
+Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
+
+Use [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.
+
+> **Agent streaming in workflows:** When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
+>
+> See [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming) for more details.
+
+## Usage example
+
+This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workflowRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: '/workflow',
+        workflow: 'weatherWorkflow',
+      }),
+    ],
+  },
+})
+```
+
+You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workflowRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: '/workflow/:workflowId',
+      }),
+    ],
+  },
+})
+```
+
+## Parameters
+
+**path?:** (`string`): The route path (e.g., \`/workflow\` or \`/workflow/:workflowId\`). Include \`:workflowId\` for dynamic workflow routing. (Default: `'/api/workflows/:workflowId/stream'`)
+
+**workflow?:** (`string`): Fixed workflow ID when not using dynamic routing. (Default: `undefined`)
+
+**includeTextStreamParts?:** (`boolean`): Whether to include text stream parts in the output. (Default: `true`)
+
+## Additional configuration
+
+You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the workflow route, for example to pass additional configuration to the workflow:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } = useChat({
+  transport: new DefaultChatTransport({
+    api: 'http://localhost:4111/workflow',
+    prepareSendMessagesRequest({ messages }) {
+      return {
+        body: {
+          inputData: {
+            city: messages[messages.length - 1].parts[0].text,
+          },
+          // Or resumeData for resuming a suspended workflow
+          resumeData: {
+            confirmation: messages[messages.length - 1].parts[0].text,
+          },
+        },
+      }
+    },
+  }),
+})
+```

package/.docs/reference/auth/auth0.md

@@ -0,0 +1,73 @@
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+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,
+      audience: process.env.AUTH0_AUDIENCE,
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, simply use `new MastraAuthAuth0()` without any arguments.
+
+## Constructor parameters
+
+**domain?:** (`string`): Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant. (Default: `process.env.AUTH0_DOMAIN`)
+
+**audience?:** (`string`): Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API. (Default: `process.env.AUTH0_AUDIENCE`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"auth0"`)
+
+**authorizeUser?:** (`(user: Auth0User) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**AUTH0\_DOMAIN?:** (`string`): Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.
+
+**AUTH0\_AUDIENCE?:** (`string`): Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.
+
+## Default Authorization Behavior
+
+By default, `MastraAuthAuth0` validates Auth0 JWT tokens and allows access to all authenticated users:
+
+1. **Token Verification**: The JWT token is verified using Auth0's public keys (JWKS)
+2. **Signature Validation**: Ensures the token was signed by your Auth0 tenant
+3. **Expiration Check**: Verifies the token has not expired
+4. **Audience Validation**: Confirms the token was issued for your specific API (audience)
+5. **Issuer Validation**: Ensures the token was issued by your Auth0 domain
+
+If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom `authorizeUser` function.
+
+## Auth0 User Type
+
+The `Auth0User` type used in the `authorizeUser` function corresponds to the decoded JWT token payload, which typically includes:
+
+- `sub`: The user's unique identifier (subject)
+- `email`: The user's email address (if included in token)
+- `email_verified`: Whether the email is verified
+- `name`: The user's display name (if available)
+- `picture`: URL to the user's profile picture (if available)
+- `iss`: Token issuer (your Auth0 domain)
+- `aud`: Token audience (your API identifier)
+- `iat`: Token issued at timestamp
+- `exp`: Token expiration timestamp
+- `scope`: Granted scopes for the token
+- Custom claims and app metadata configured in your Auth0 tenant
+
+The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.
+
+## Related
+
+[MastraAuthAuth0 Class](https://mastra.ai/docs/server/auth/auth0)

package/.docs/reference/auth/better-auth.md

@@ -0,0 +1,71 @@
+# MastraAuthBetterAuth Class
+
+The `MastraAuthBetterAuth` class provides authentication for Mastra applications using Better Auth. It verifies incoming requests with Better Auth sessions and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
+import { betterAuth } from 'better-auth'
+
+// Create your Better Auth instance
+const auth = betterAuth({
+  database: {
+    provider: 'postgresql',
+    url: process.env.DATABASE_URL,
+  },
+  emailAndPassword: {
+    enabled: true,
+  },
+  baseURL: process.env.BETTER_AUTH_URL,
+  secret: process.env.BETTER_AUTH_SECRET,
+})
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthBetterAuth({
+      auth,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**auth:** (`Auth`): Your Better Auth instance created via betterAuth({ ... }). This is required and must be properly configured with a supported database provider.
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `'better-auth'`)
+
+**authorizeUser?:** (`(user: BetterAuthUser, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after session verification. By default, allows all authenticated users with valid sessions.
+
+**public?:** (`Array<string | RegExp | [string, Methods | Methods[]]>`): Public routes that do not require authentication. Supports exact paths, wildcards, and path params.
+
+**protected?:** (`Array<string | RegExp | [string, Methods | Methods[]]>`): Protected routes that require authentication. Supports exact paths, wildcards, and path params.
+
+## BetterAuthUser Type
+
+The `BetterAuthUser` type contains the session and user information returned by Better Auth:
+
+```typescript
+interface BetterAuthUser {
+  session: Session
+  user: User
+}
+```
+
+- `session`: The Better Auth session object containing session metadata
+- `user`: The authenticated user object with user details
+
+The `Session` and `User` types are exported by the Better Auth package.
+
+## Matching rules
+
+- `public` and `protected` accept exact paths, wildcard patterns (like `/api/*`), and path params (like `/users/:id`).
+- For method-specific rules, use tuples like `["/api/agents", ["GET", "POST"]]`.
+- If a route matches both `public` and `protected`, `public` wins and no auth is required.
+- If neither matches, routes are treated as protected by default (unless a route is explicitly marked `requiresAuth: false`).
+
+## Related
+
+[MastraAuthBetterAuth Class](https://mastra.ai/docs/server/auth/better-auth)

package/.docs/reference/auth/clerk.md

@@ -0,0 +1,36 @@
+# 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 `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthClerk } from '@mastra/auth-clerk'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthClerk({
+      jwksUri: process.env.CLERK_JWKS_URI,
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**publishableKey?:** (`string`): Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys. (Default: `process.env.CLERK_PUBLISHABLE_KEY`)
+
+**secretKey?:** (`string`): Your Clerk secret key. Used for server-side authentication and token verification. (Default: `process.env.CLERK_SECRET_KEY`)
+
+**jwksUri?:** (`string`): The JWKS URI from your Clerk application. Used to verify JWT signatures. (Default: `process.env.CLERK_JWKS_URI`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users.
+
+## Related
+
+[MastraAuthClerk Class](https://mastra.ai/docs/server/auth/clerk)

package/.docs/reference/auth/firebase.md

@@ -0,0 +1,80 @@
+# MastraAuthFirebase Class
+
+The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase({
+      serviceAccount: '/path/to/service-account-key.json',
+      databaseId: 'your-database-id',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**serviceAccount?:** (`string`): Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side. (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)
+
+**databaseId?:** (`string`): The Firestore database ID to use. Typically '(default)' for the default database. (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"firebase"`)
+
+**authorizeUser?:** (`(user: FirebaseUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks for the presence of a document in the 'user\_access' collection keyed by the user's UID.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**FIREBASE\_SERVICE\_ACCOUNT?:** (`string`): Path to Firebase service account JSON file. Used if serviceAccount option is not provided.
+
+**FIRESTORE\_DATABASE\_ID?:** (`string`): Firestore database ID. Primary environment variable for database configuration.
+
+**FIREBASE\_DATABASE\_ID?:** (`string`): Alternative environment variable for Firestore database ID. Used if FIRESTORE\_DATABASE\_ID is not set.
+
+## Default Authorization Behavior
+
+By default, `MastraAuthFirebase` uses Firestore to manage user access:
+
+1. After successfully verifying a Firebase ID token, the `authorizeUser` method is called
+2. It checks for the existence of a document in the `user_access` collection with the user's UID as the document ID
+3. If the document exists, the user is authorized; otherwise, access is denied
+4. The Firestore database used is determined by the `databaseId` parameter or environment variables
+
+## Firebase User Type
+
+The `FirebaseUser` type used in the `authorizeUser` function corresponds to Firebase's `DecodedIdToken` interface, which includes:
+
+- `uid`: The user's unique identifier
+- `email`: The user's email address (if available)
+- `email_verified`: Whether the email is verified
+- `name`: The user's display name (if available)
+- `picture`: URL to the user's profile picture (if available)
+- `auth_time`: When the user authenticated
+- And other standard JWT claims
+
+## Related
+
+[MastraAuthFirebase Class](https://mastra.ai/docs/server/auth/firebase)

package/.docs/reference/auth/jwt.md

@@ -0,0 +1,26 @@
+# MastraJwtAuth Class
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: '<your-secret>',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**secret:** (`string`): A unique string used to sign and verify JSON Web Tokens (JWTs) for authenticating incoming requests.
+
+## Related
+
+[MastraJwtAuth](https://mastra.ai/docs/server/auth/jwt)

package/.docs/reference/auth/supabase.md

@@ -0,0 +1,33 @@
+# MastraAuthSupabase Class
+
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthSupabase } from '@mastra/auth-supabase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthSupabase({
+      url: process.env.SUPABASE_URL,
+      anonKey: process.env.SUPABASE_ANON_KEY,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**url?:** (`string`): The URL of your Supabase project. Can be found in your Supabase project settings. (Default: `process.env.SUPABASE_URL`)
+
+**anonKey?:** (`string`): The anonymous/public key for your Supabase project. Used for client-side authentication. (Default: `process.env.SUPABASE_ANON_KEY`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HoneRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks the 'isAdmin' column in the 'users' table.
+
+## Related
+
+[MastraAuthSupabase](https://mastra.ai/docs/server/auth/supabase)