@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

package/.docs/docs/server/auth/auth0.md

@@ -1,222 +0,0 @@
-# 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.
-
-## 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
-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
-npm install @mastra/auth-auth0@latest
-```
-
-## Usage examples
-
-### Basic usage with environment variables
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraAuthAuth0 } from "@mastra/auth-auth0";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraAuthAuth0(),
-  },
-});
-```
-
-### Custom configuration
-
-```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,
-    }),
-  },
-});
-```
-
-## 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
-import { MastraAuthAuth0 } from "@mastra/auth-auth0";
-
-const auth0Provider = new MastraAuthAuth0({
-  authorizeUser: async (user) => {
-    // Custom authorization logic
-    return user.email?.endsWith("@yourcompany.com") || false;
-  },
-});
-```
-
-> **Info:** Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) 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
-npm install @auth0/auth0-react
-```
-
-```typescript
-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
-import { useAuth0 } from "@auth0/auth0-react";
-
-export const useAuth0Token = () => {
-  const { getAccessTokenSilently } = useAuth0();
-
-  const getAccessToken = async () => {
-    const token = await getAccessTokenSilently();
-    return token;
-  };
-
-  return { getAccessToken };
-};
-```
-
-> **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
-import { MastraClient } from "@mastra/client-js";
-
-export const createMastraClient = (accessToken: string) => {
-  return new MastraClient({
-    baseUrl: "https://<mastra-api-url>",
-    headers: {
-      Authorization: `Bearer ${accessToken}`,
-    },
-  });
-};
-```
-
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
->
-> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured with the Auth0 access token, you can send authenticated requests:
-
-**React**:
-
-```tsx
-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("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>
-  );
-};
-```
-
-**cURL**:
-
-```bash
-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"
-  }'
-```

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

@@ -1,203 +0,0 @@
-# MastraAuthBetterAuth Class
-
-The `MastraAuthBetterAuth` class provides authentication for Mastra using Better Auth. It verifies incoming requests using your Better Auth instance and integrates with the Mastra server via the `server.auth` option.
-
-## Prerequisites
-
-This example uses Better Auth. Make sure your Better Auth instance is configured and your environment variables are set.
-
-```env
-# Required by Better Auth
-BETTER_AUTH_SECRET=...   # at least 32 chars
-BETTER_AUTH_URL=http://localhost:3000
-
-# Example DB URL used by the snippet below (adjust for your setup)
-DATABASE_URL=postgres://...
-```
-
-> **Note:** Better Auth recommends setting `baseURL` explicitly (or via `BETTER_AUTH_URL`) for security and stability.
-
-If you haven't mounted Better Auth's handler yet (so your app can sign users in / create sessions), follow the [Better Auth installation guide](https://www.better-auth.com/docs/installation) to mount the `/api/auth/*` route (or your configured base path).
-
-## Installation
-
-Install the `@mastra/auth-better-auth` package:
-
-**npm**:
-
-```bash
-npm install @mastra/auth-better-auth
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/auth-better-auth
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/auth-better-auth
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/auth-better-auth
-```
-
-## Usage example
-
-First, create your Better Auth instance:
-
-```ts
-import { betterAuth } from "better-auth";
-
-export 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,
-});
-```
-
-Then, use it with Mastra:
-
-```ts
-import { Mastra } from "@mastra/core";
-import { MastraAuthBetterAuth } from "@mastra/auth-better-auth";
-import { auth } from "@/lib/auth";
-
-const mastraAuth = new MastraAuthBetterAuth({
-  auth,
-});
-
-export const mastra = new Mastra({
-  server: {
-    auth: mastraAuth,
-  },
-});
-```
-
-> **Info:** Visit [MastraAuthBetterAuth](https://mastra.ai/reference/auth/better-auth) for all available configuration options.
-
-## Custom authorization
-
-```ts
-const mastraAuth = new MastraAuthBetterAuth({
-  auth,
-  async authorizeUser(user) {
-    // Example: only allow verified emails
-    return user?.user?.emailVerified === true;
-  },
-});
-```
-
-## Route configuration
-
-```ts
-const mastraAuth = new MastraAuthBetterAuth({
-  auth,
-  public: ["/health", "/api/status"],
-  protected: ["/api/*", "/admin/*"],
-});
-```
-
-### 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`).
-
-## Client-side setup
-
-When auth is enabled, requests to Mastra's built-in routes require authentication. In practice, that means your client needs to send whatever credential your Better Auth setup uses for authenticated requests.
-
-### Cookie session (recommended)
-
-If your Better Auth setup uses cookies, configure the client to send credentials and ensure your Mastra server CORS allows credentials for cross-origin requests.
-
-```ts
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: "http://localhost:4111",
-  credentials: "include",
-});
-```
-
-If you are calling the API directly, include credentials in `fetch` as well:
-
-```ts
-await fetch("http://localhost:4111/api/agents/weatherAgent/generate", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-  },
-  credentials: "include",
-  body: JSON.stringify({ messages: "Weather in London" }),
-});
-```
-
-### Bearer token
-
-If your Better Auth setup issues bearer tokens, include them in the `Authorization` header:
-
-```ts
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: "http://localhost:4111",
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-  },
-});
-```
-
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-**React**:
-
-```tsx
-import { mastraClient } from "../lib/mastra-client";
-
-export const TestAgent = () => {
-  async function handleClick() {
-    const agent = mastraClient.getAgent("weatherAgent");
-
-    const response = await agent.generate("Weather in London");
-
-    console.log(response);
-  }
-
-  return <button onClick={handleClick}>Test Agent</button>;
-};
-```
-
-**cURL**:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```
-
-## Troubleshooting
-
-- **401/403 on every request**: confirm your Better Auth handler is mounted and your app can create a valid session/token.
-- **Cookies not sent**: set `credentials: "include"` in `MastraClient` and enable CORS credentials on the Mastra server.
-- **Authorization header missing**: ensure the client attaches `Authorization: Bearer <token>` when using bearer tokens.
-- **Base URL issues**: set `baseURL` in `betterAuth({ ... })` or set `BETTER_AUTH_URL`.
-- **DB connection errors**: verify `DATABASE_URL` and database provider configuration.

package/.docs/docs/server/auth/clerk.md

@@ -1,132 +0,0 @@
-# MastraAuthClerk Class
-
-The `MastraAuthClerk` class provides authentication for Mastra using Clerk. It verifies incoming requests using Clerk's authentication system and integrates with the Mastra server using the `auth` option.
-
-## Prerequisites
-
-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
-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".
-
-## Installation
-
-Before you can use the `MastraAuthClerk` class you have to install the `@mastra/auth-clerk` package.
-
-```bash
-npm install @mastra/auth-clerk@latest
-```
-
-## Usage example
-
-```typescript
-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,
-      secretKey: process.env.CLERK_SECRET_KEY,
-      jwksUri: process.env.CLERK_JWKS_URI,
-    }),
-  },
-});
-```
-
-> **Info:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
->
-> Visit [MastraAuthClerk](https://mastra.ai/reference/auth/clerk) for all available configuration options.
-
-## Client-side setup
-
-When using Clerk auth, you'll need to retrieve the access token from Clerk on the client side and pass it to your Mastra requests.
-
-### Retrieving the access token
-
-Use the Clerk React hooks to authenticate users and retrieve their access token:
-
-```typescript
-import { useAuth } from "@clerk/nextjs";
-
-export const useClerkAuth = () => {
-  const { getToken } = useAuth();
-
-  const getAccessToken = async () => {
-    const token = await getToken();
-    return token;
-  };
-
-  return { getAccessToken };
-};
-```
-
-> **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
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: "https://<mastra-api-url>",
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-  },
-});
-```
-
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
->
-> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured with the Clerk access token, you can send authenticated requests:
-
-**React**:
-
-```tsx
-"use client";
-
-import { useAuth } from "@clerk/nextjs";
-import { MastraClient } from "@mastra/client-js";
-
-export const TestAgent = () => {
-  const { getToken } = useAuth();
-
-  async function handleClick() {
-    const token = await getToken();
-
-    const client = new MastraClient({
-      baseUrl: "http://localhost:4111",
-      headers: token ? { Authorization: `Bearer ${token}` } : undefined,
-    });
-
-    const weatherAgent = client.getAgent("weatherAgent");
-    const response = await weatherAgent.generate("What's the weather like in New York");
-
-    console.log({ response });
-  }
-
-  return <button onClick={handleClick}>Test Agent</button>;
-};
-```
-
-**cURL**:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-clerk-access-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```