@mastra/mcp-docs-server 0.13.24-alpha.0 → 0.13.24-alpha.3

package/.docs/raw/auth/auth0.mdx

@@ -0,0 +1,235 @@
+---
+title: "MastraAuthAuth0 Class"
+description: "Documentation for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# 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 `experimental_auth` option.
+
+## Prerequisites
+
+This example uses Auth0 authentication. Make sure to:
+
+1. Create an Auth0 account at [auth0.com](https://auth0.com/)
+2. Set up an Application in your Auth0 Dashboard
+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 filename=".env" copy
+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.
+
+> 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
+npm install @mastra/auth-auth0@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript {2,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0(),
+  },
+});
+```
+
+### Custom configuration
+
+```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE
+    }),
+  },
+});
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
+
+1. The token is properly signed by Auth0
+2. The token is not expired
+3. The token audience matches your configured audience
+4. The token issuer matches your Auth0 domain
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript filename="src/mastra/auth.ts" showLineNumbers copy
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+const auth0Provider = new MastraAuthAuth0({
+  authorizeUser: async (user) => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false;
+  }
+});
+```
+
+> See the [MastraAuthAuth0](/reference/auth/auth0.mdx) API reference for all available configuration options.
+
+## Client-side setup
+
+When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate users, and retrieve their access tokens to pass to your Mastra requests.
+
+### Setting up Auth0 React SDK
+
+First, install and configure the Auth0 React SDK in your application:
+
+```bash copy
+npm install @auth0/auth0-react
+```
+
+```typescript filename="src/auth0-provider.tsx" showLineNumbers copy
+import React from 'react';
+import { Auth0Provider } from '@auth0/auth0-react';
+
+const Auth0ProviderWithHistory = ({ children }) => {
+  return (
+    <Auth0Provider
+      domain={process.env.REACT_APP_AUTH0_DOMAIN}
+      clientId={process.env.REACT_APP_AUTH0_CLIENT_ID}
+      authorizationParams={{
+        redirect_uri: window.location.origin,
+        audience: process.env.REACT_APP_AUTH0_AUDIENCE,
+        scope: "read:current_user update:current_user_metadata"
+      }}
+    >
+      {children}
+    </Auth0Provider>
+  );
+};
+
+export default Auth0ProviderWithHistory;
+```
+
+### Retrieving access tokens
+
+Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
+
+```typescript filename="lib/auth.ts" showLineNumbers copy
+import { useAuth0 } from '@auth0/auth0-react';
+
+export const useAuth0Token = () => {
+  const { getAccessTokenSilently } = useAuth0();
+
+  const getAccessToken = async () => {
+    const token = await getAccessTokenSilently();
+    return token;
+  };
+
+  return { getAccessToken };
+};
+```
+
+> Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 access token in the `Authorization` header:
+
+```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: "https://<mastra-api-url>",
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+};
+```
+
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client.mdx) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the Auth0 access token, you can send authenticated requests:
+
+<Tabs items={["React Component", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/mastra-api-test.tsx" showLineNumbers copy
+    import React, { useState } from 'react';
+    import { useAuth0 } from '@auth0/auth0-react';
+    import { MastraClient } from '@mastra/client-js';
+
+    export const MastraApiTest = () => {
+      const { getAccessTokenSilently } = useAuth0();
+      const [result, setResult] = useState(null);
+
+      const callMastraApi = async () => {
+        const token = await getAccessTokenSilently();
+
+        const mastra = new MastraClient({
+          baseUrl: "http://localhost:4111",
+          headers: {
+            Authorization: `Bearer ${token}`
+          }
+        });
+
+        const weatherAgent = mastra.getAgent("weatherAgent");
+        const response = await weatherAgent.generate({
+          messages: "What's the weather like in New York"
+        });
+
+        setResult(response.text);
+      };
+
+      return (
+        <div>
+          <button onClick={callMastraApi}>
+            Test Mastra API
+          </button>
+
+          {result && (
+            <div className="result">
+              <h6>Result:</h6>
+              <pre>{result}</pre>
+            </div>
+          )}
+        </div>
+      );
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-auth0-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>
+

package/.docs/raw/auth/index.mdx

@@ -15,10 +15,5 @@ You can start with simple shared secret JWT authentication and switch to provide
 - [Clerk](/docs/auth/clerk)
 - [Supabase](/docs/auth/supabase)
 - [Firebase](/docs/auth/firebase)
-
-### Coming soon
-
-The following providers will be available soon:
-
-- Auth0
-- WorkOS
+- [WorkOS](/docs/auth/workos)
+- [Auth0](/docs/auth/auth0)

package/.docs/raw/auth/workos.mdx

@@ -0,0 +1,198 @@
+---
+title: "MastraAuthWorkos Class"
+description: "Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# MastraAuthWorkos Class
+
+The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `experimental_auth` option.
+
+## Prerequisites
+
+This example uses WorkOS authentication. Make sure to:
+
+1. Create a WorkOS account at [workos.com](https://workos.com/)
+2. Set up an Application in your WorkOS Dashboard
+3. Configure your redirect URIs and allowed origins
+4. Set up Organizations and configure user roles as needed
+
+```env filename=".env" copy
+WORKOS_API_KEY=sk_live_...
+WORKOS_CLIENT_ID=client_...
+```
+
+> **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
+
+> For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
+
+## Installation
+
+Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
+
+```bash copy
+npm install @mastra/auth-workos@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript {2,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthWorkos(),
+  },
+});
+```
+
+### Custom configuration
+
+```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID
+    }),
+  },
+});
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
+
+1. Retrieves the user's organization memberships using their user ID
+2. Extracts all roles from their memberships
+3. Checks if any role has the slug 'admin'
+4. Grants access only if the user has admin role in at least one organization
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript filename="src/mastra/auth.ts" showLineNumbers copy
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+const workosAuth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  authorizeUser: async (user) => {
+    return !!user;
+  },
+});
+```
+
+> See the [MastraAuthWorkos](/reference/auth/workos) API reference for all available configuration options.
+
+## Client-side setup
+
+When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
+
+### Installing WorkOS SDK
+
+First, install the WorkOS SDK in your application:
+
+```bash copy
+npm install @workos-inc/node
+```
+
+### Exchanging code for access token
+
+After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
+
+```typescript filename="lib/auth.ts" showLineNumbers copy
+import { WorkOS } from '@workos-inc/node';
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+export const authenticateWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  });
+
+  return authenticationResponse.accessToken;
+};
+```
+
+> Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
+
+```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: "https://<mastra-api-url>",
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+};
+```
+
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
+
+<Tabs items={["JavaScript/Node.js", "curl"]}>
+  <Tab>
+    ```typescript filename="src/api/agents.ts" showLineNumbers copy
+    import { WorkOS } from '@workos-inc/node';
+    import { MastraClient } from '@mastra/client-js';
+
+    const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+    export const callMastraWithWorkos = async (code: string, clientId: string) => {
+      const authenticationResponse = await workos.userManagement.authenticateWithCode({
+        code,
+        clientId,
+      });
+
+      const token = authenticationResponse.accessToken;
+
+      const mastra = new MastraClient({
+        baseUrl: "http://localhost:4111",
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      });
+
+      const weatherAgent = mastra.getAgent("weatherAgent");
+      const response = await weatherAgent.generate({
+        messages: "What's the weather like in Nairobi",
+      });
+
+      return response.text;
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-workos-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>

package/.docs/raw/getting-started/installation.mdx

@@ -8,7 +8,7 @@ import { Tabs, Tab } from "@/components/tabs";
 
 # Install Mastra
 
-To get started with Mastra, you’ll need access to a large language model (LLM). By default, Mastra is set up to work with [OpenAI](https://platform.openai.com/), so you’ll need an API key to begin.
+To get started with Mastra, you'll need access to a large language model (LLM). By default, Mastra is set up to work with [OpenAI](https://platform.openai.com/), so you'll need an API key to begin.
 
 Mastra also supports other LLM providers. For a full list of supported models and setup instructions, see [Model Providers](/docs/getting-started/model-providers).
 

package/.docs/raw/memory/conversation-history.mdx

@@ -0,0 +1,23 @@
+---
+title: "Conversation History | Memory | Mastra Docs"
+description: "Learn how to configure conversation history in Mastra to store recent messages from the current conversation."
+---
+
+# Conversation History
+
+Conversation history is the simplest kind of memory. It is a list of messages from the current conversation.
+
+By default, each request includes the last 10 messages from the current memory thread, giving the agent short-term conversational context. This limit can be increased using the `lastMessages` parameter.
+
+You can increase this limit by passing the `lastMessages` parameter to the `Memory` instance.
+
+```typescript {3-7} showLineNumbers
+export const testAgent = new Agent({
+  // ...
+  memory: new Memory({
+    options: {
+      lastMessages: 100
+    },
+  })
+});
+```