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

package/.docs/docs/server/auth/firebase.md

@@ -1,272 +0,0 @@
-# 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.
-
-## Prerequisites
-
-This example uses Firebase Authentication. Make sure to:
-
-1. Create a Firebase project in the [Firebase Console](https://console.firebase.google.com/)
-2. Enable Authentication and configure your preferred sign-in methods (Google, Email/Password, etc.)
-3. Generate a service account key from Project Settings > Service Accounts
-4. Download the service account JSON file
-
-```env
-FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
-FIRESTORE_DATABASE_ID=(default)
-# Alternative environment variable names:
-# FIREBASE_DATABASE_ID=(default)
-```
-
-> **Note:** Store your service account JSON file securely and never commit it to version control.
-
-## Installation
-
-Before you can use the `MastraAuthFirebase` class you have to install the `@mastra/auth-firebase` package.
-
-```bash
-npm install @mastra/auth-firebase@latest
-```
-
-## Usage examples
-
-### Basic usage with environment variables
-
-If you set the required environment variables (`FIREBASE_SERVICE_ACCOUNT` and `FIRESTORE_DATABASE_ID`), you can initialize `MastraAuthFirebase` without any constructor arguments. The class will automatically read these environment variables as configuration:
-
-```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.json",
-      databaseId: "your-database-id",
-    }),
-  },
-});
-```
-
-## Configuration
-
-The `MastraAuthFirebase` class can be configured through constructor options or environment variables.
-
-### Environment Variables
-
-- `FIREBASE_SERVICE_ACCOUNT`: Path to Firebase service account JSON file
-- `FIRESTORE_DATABASE_ID` or `FIREBASE_DATABASE_ID`: Firestore database ID
-
-> **Note:** When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.
-
-### User Authorization
-
-By default, `MastraAuthFirebase` uses Firestore to manage user access. It expects a collection named `user_access` with documents keyed by user UIDs. The presence of a document in this collection determines whether a user is authorized.
-
-```typescript
-user_access/
-  {user_uid_1}/     // Document exists = user authorized
-  {user_uid_2}/     // Document exists = user authorized
-```
-
-To customize user authorization, provide a custom `authorizeUser` function:
-
-```typescript
-import { MastraAuthFirebase } from "@mastra/auth-firebase";
-
-const firebaseAuth = new MastraAuthFirebase({
-  authorizeUser: async (user) => {
-    // Custom authorization logic
-    return user.email?.endsWith("@yourcompany.com") || false;
-  },
-});
-```
-
-> **Info:** Visit [MastraAuthFirebase](https://mastra.ai/reference/auth/firebase) for all available configuration options.
-
-## Client-side setup
-
-When using Firebase auth, you'll need to initialize Firebase on the client side, authenticate users, and retrieve their ID tokens to pass to your Mastra requests.
-
-### Setting up Firebase on the client
-
-First, initialize Firebase in your client application:
-
-```typescript
-import { initializeApp } from "firebase/app";
-import { getAuth, GoogleAuthProvider } from "firebase/auth";
-
-const firebaseConfig = {
-  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
-  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
-  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
-};
-
-const app = initializeApp(firebaseConfig);
-export const auth = getAuth(app);
-export const googleProvider = new GoogleAuthProvider();
-```
-
-### Authenticating users and retrieving tokens
-
-Use Firebase authentication to sign in users and retrieve their ID tokens:
-
-```typescript
-import { signInWithPopup, signOut, User } from "firebase/auth";
-import { auth, googleProvider } from "./firebase";
-
-export const signInWithGoogle = async () => {
-  try {
-    const result = await signInWithPopup(auth, googleProvider);
-    return result.user;
-  } catch (error) {
-    console.error("Error signing in:", error);
-    throw error;
-  }
-};
-
-export const getIdToken = async (user: User) => {
-  try {
-    const idToken = await user.getIdToken();
-    return idToken;
-  } catch (error) {
-    console.error("Error getting ID token:", error);
-    throw error;
-  }
-};
-
-export const signOutUser = async () => {
-  try {
-    await signOut(auth);
-  } catch (error) {
-    console.error("Error signing out:", error);
-    throw error;
-  }
-};
-```
-
-> **Note:** Refer to the [Firebase documentation](https://firebase.google.com/docs/auth) for other authentication methods like email/password, phone authentication, and more.
-
-## Configuring `MastraClient`
-
-When `auth` is enabled, all requests made with `MastraClient` must include a valid Firebase ID token in the `Authorization` header:
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const createMastraClient = (idToken: string) => {
-  return new MastraClient({
-    baseUrl: "https://<mastra-api-url>",
-    headers: {
-      Authorization: `Bearer ${idToken}`,
-    },
-  });
-};
-```
-
-> **Info:** The ID 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 Firebase ID token, you can send authenticated requests:
-
-**React**:
-
-```tsx
-"use client";
-
-import { useAuthState } from 'react-firebase-hooks/auth';
-import { MastraClient } from "@mastra/client-js";
-import { auth } from '../lib/firebase';
-import { getIdToken } from '../lib/auth';
-
-export const TestAgent = () => {
-  const [user] = useAuthState(auth);
-
-  async function handleClick() {
-    if (!user) return;
-
-    const token = await getIdToken(user);
-    const client = createMastraClient(token);
-
-    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} disabled={!user}>
-      Test Agent
-    </button>
-  );
-};
-```
-
-**Node.js**:
-
-```typescript
-const express = require('express');
-const admin = require('firebase-admin');
-const { MastraClient } = require('@mastra/client-js');
-
-// Initialize Firebase Admin
-admin.initializeApp({
-  credential: admin.credential.cert({
-    // Your service account credentials
-  })
-});
-
-const app = express();
-app.use(express.json());
-
-app.post('/generate', async (req, res) => {
-  try {
-    const { idToken } = req.body;
-
-    // Verify the token
-    await admin.auth().verifyIdToken(idToken);
-
-    const mastra = new MastraClient({
-      baseUrl: "http://localhost:4111",
-      headers: {
-        Authorization: `Bearer ${idToken}`
-      }
-    });
-
-    const weatherAgent = mastra.getAgent("weatherAgent");
-    const response = await weatherAgent.generate("What's the weather like in Nairobi");
-
-    res.json({ response: response.text });
-  } catch (error) {
-    res.status(401).json({ error: 'Unauthorized' });
-  }
-});
-```
-
-**cURL**:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-firebase-id-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```

package/.docs/docs/server/auth/jwt.md

@@ -1,110 +0,0 @@
-# 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.
-
-## Installation
-
-Before you can use the `MastraJwtAuth` class you have to install the `@mastra/auth` package.
-
-**npm**:
-
-```bash
-npm install @mastra/auth@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/auth@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/auth@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/auth@latest
-```
-
-## Usage example
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraJwtAuth } from "@mastra/auth";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraJwtAuth({
-      secret: process.env.MASTRA_JWT_SECRET,
-    }),
-  },
-});
-```
-
-> **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
-
-## Configuring `MastraClient`
-
-When `auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: "https://<mastra-api-url>",
-  headers: {
-    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
-  },
-});
-```
-
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
-
-### Making authenticated requests
-
-Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:
-
-**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-jwt>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```
-
-## Creating a JWT
-
-To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.
-
-The easiest way to generate one is using [jwt.io](https://www.jwt.io/):
-
-1. Select **JWT Encoder**.
-2. Scroll down to the **Sign JWT: Secret** section.
-3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
-4. Click **Generate example** to create a valid JWT.
-5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

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

@@ -1,178 +0,0 @@
-# SimpleAuth Class
-
-The `SimpleAuth` class provides token-based authentication using a simple token-to-user mapping. It's included in `@mastra/core/server` and is useful for development, testing, and simple API key authentication scenarios.
-
-## Use Cases
-
-- Local development and testing
-- Simple API key authentication
-- Prototyping before integrating a full identity provider
-- Internal services with static tokens
-
-## Installation
-
-SimpleAuth is included in `@mastra/core`, no additional packages required.
-
-```typescript
-import { SimpleAuth } from '@mastra/core/server';
-```
-
-## Usage Example
-
-```typescript
-import { Mastra } from '@mastra/core';
-import { SimpleAuth } from '@mastra/core/server';
-
-// Define your user type
-type User = {
-  id: string;
-  name: string;
-  role: 'admin' | 'user';
-};
-
-export const mastra = new Mastra({
-  server: {
-    auth: new SimpleAuth<User>({
-      tokens: {
-        'sk-admin-token-123': {
-          id: 'user-1',
-          name: 'Admin User',
-          role: 'admin',
-        },
-        'sk-user-token-456': {
-          id: 'user-2',
-          name: 'Regular User',
-          role: 'user',
-        },
-      },
-    }),
-  },
-});
-```
-
-## Configuration Options
-
-| Option          | Type                         | Required | Description                            |
-| --------------- | ---------------------------- | -------- | -------------------------------------- |
-| `tokens`        | `Record<string, TUser>`      | Yes      | Map of tokens to user objects          |
-| `headers`       | `string \| string[]`         | No       | Additional headers to check for tokens |
-| `name`          | `string`                     | No       | Provider name for logging              |
-| `authorizeUser` | `(user, request) => boolean` | No       | Custom authorization function          |
-| `protected`     | `(RegExp \| string)[]`       | No       | Paths that require authentication      |
-| `public`        | `(RegExp \| string)[]`       | No       | Paths that bypass authentication       |
-
-### Default Headers
-
-SimpleAuth checks these headers by default:
-
-- `Authorization` (with or without `Bearer` prefix)
-- `X-Playground-Access`
-
-Add custom headers using the `headers` option:
-
-```typescript
-new SimpleAuth({
-  tokens: { /* ... */ },
-  headers: ['X-API-Key', 'X-Custom-Auth'],
-});
-```
-
-## Making Authenticated Requests
-
-Include your token in the `Authorization` header:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/myAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer sk-admin-token-123" \
-  -d '{"messages": "Hello"}'
-```
-
-Or without the `Bearer` prefix:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/myAgent/generate \
-  -H "Content-Type: application/json" \
-  -H "Authorization: sk-admin-token-123" \
-  -d '{"messages": "Hello"}'
-```
-
-## Custom Authorization
-
-Add role-based or custom authorization logic:
-
-```typescript
-new SimpleAuth<User>({
-  tokens: {
-    'sk-admin-token': { id: '1', name: 'Admin', role: 'admin' },
-    'sk-user-token': { id: '2', name: 'User', role: 'user' },
-  },
-  authorizeUser: (user, request) => {
-    // Only admins can access /admin routes
-    if (request.url.includes('/admin')) {
-      return user.role === 'admin';
-    }
-    return true;
-  },
-});
-```
-
-## Environment Variables
-
-For production-like setups, load tokens from environment variables:
-
-```typescript
-const tokens: Record<string, User> = {};
-
-// Load from environment
-const adminToken = process.env.ADMIN_API_KEY;
-if (adminToken) {
-  tokens[adminToken] = { id: 'admin', name: 'Admin', role: 'admin' };
-}
-
-const userToken = process.env.USER_API_KEY;
-if (userToken) {
-  tokens[userToken] = { id: 'user', name: 'User', role: 'user' };
-}
-
-export const mastra = new Mastra({
-  server: {
-    auth: new SimpleAuth({ tokens }),
-  },
-});
-```
-
-## With MastraClient
-
-Configure the client with your token:
-
-```typescript
-import { MastraClient } from '@mastra/client-js';
-
-const client = new MastraClient({
-  baseUrl: 'http://localhost:4111',
-  headers: {
-    Authorization: 'Bearer sk-admin-token-123',
-  },
-});
-
-const agent = client.getAgent('myAgent');
-const response = await agent.generate('Hello');
-```
-
-## Limitations
-
-SimpleAuth is designed for simplicity, not production security:
-
-- Tokens are stored in memory
-- No token expiration or refresh
-- No cryptographic verification
-- All tokens must be known at startup
-
-For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/docs/server/auth/clerk), [Auth0](https://mastra.ai/docs/server/auth/auth0), or another identity provider.
-
-## Related
-
-- [Auth Overview](https://mastra.ai/docs/server/auth) - Authentication concepts
-- [JWT Auth](https://mastra.ai/docs/server/auth/jwt) - JSON Web Token authentication
-- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider

package/.docs/docs/server/auth/supabase.md

@@ -1,117 +0,0 @@
-# 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.
-
-## Prerequisites
-
-This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
-
-```env
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_ANON_KEY=your-anon-key
-```
-
-> **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
-
-## Installation
-
-Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
-
-```bash
-npm install @mastra/auth-supabase@latest
-```
-
-## 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,
-    }),
-  },
-});
-```
-
-> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
->
-> Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
-
-## Client-side setup
-
-When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
-
-### Retrieving the access token
-
-Use the Supabase client to authenticate users and retrieve their access token:
-
-```typescript
-import { createClient } from "@supabase/supabase-js";
-
-const supabase = createClient("<supabase-url>", "<supabase-key>");
-
-const authTokenResponse = await supabase.auth.signInWithPassword({
-  email: "<user's email>",
-  password: "<user's password>",
-});
-
-const accessToken = authTokenResponse.data?.session?.access_token;
-```
-
-> **Note:** Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
-
-## Configuring `MastraClient`
-
-When `auth` is enabled, all requests made with `MastraClient` must include a valid Supabase 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 Supabase access token, you can send 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("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-supabase-access-token>" \
-  -d '{
-    "messages": "Weather in London"
-  }'
-```