@mastra/mcp-docs-server 0.13.22-alpha.2 → 0.13.22-alpha.4

package/.docs/raw/auth/firebase.mdx

@@ -0,0 +1,285 @@
+---
+title: "MastraAuthFirebase Class"
+description: "Documentation for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# 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 `experimental_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 filename=".env" copy
+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 copy
+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 {2,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthFirebase } from '@mastra/auth-firebase';
+
+// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthFirebase(),
+  },
+});
+```
+
+### Custom configuration
+
+```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthFirebase } from '@mastra/auth-firebase';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_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 filename="firestore-structure.txt" copy
+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 filename="src/mastra/auth.ts" showLineNumbers copy
+import { MastraAuthFirebase } from '@mastra/auth-firebase';
+
+const firebaseAuth = new MastraAuthFirebase({
+  authorizeUser: async (user) => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false;
+  }
+});
+```
+
+> See the [MastraAuthFirebase](/reference/auth/firebase.mdx) API reference 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 filename="lib/firebase.ts" showLineNumbers copy
+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 filename="lib/auth.ts" showLineNumbers copy
+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;
+  }
+};
+```
+
+> 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 `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid Firebase ID token in the `Authorization` header:
+
+```typescript {6} filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const createMastraClient = (idToken: string) => {
+  return new MastraClient({
+    baseUrl: "https://<mastra-api-url>",
+    headers: {
+      Authorization: `Bearer ${idToken}`
+    }
+  });
+};
+```
+
+> **Note:** The ID 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 Firebase ID token, you can send authenticated requests:
+
+<Tabs items={["React Component", "Node.js Server", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/test-agent.tsx" showLineNumbers copy
+    "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({
+          messages: "What's the weather like in New York",
+        });
+
+        console.log({ response });
+      }
+
+      return (
+        <button onClick={handleClick} disabled={!user}>
+          Test Agent
+        </button>
+      );
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```typescript filename="server.js" showLineNumbers copy
+    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({
+          messages: "What's the weather like in Nairobi"
+        });
+
+        res.json({ response: response.text });
+      } catch (error) {
+        res.status(401).json({ error: 'Unauthorized' });
+      }
+    });
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    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"
+      }'
+    ```
+  </Tab>
+</Tabs>

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

@@ -12,13 +12,13 @@ You can start with simple shared secret JWT authentication and switch to provide
 ## Available providers
 
 - [JSON Web Token (JWT)](/docs/auth/jwt)
+- [Clerk](/docs/auth/clerk)
+- [Supabase](/docs/auth/supabase)
+- [Firebase](/docs/auth/firebase)
 
 ### Coming soon
 
 The following providers will be available soon:
 
-- Supabase Auth
-- Firebase Auth
 - Auth0
-- Clerk
 - WorkOS

package/.docs/raw/course/04-workflows/08-running-workflows-programmatically.md

@@ -22,7 +22,7 @@ async function runContentWorkflow() {
     }
 
     // Create a run instance
-    const run = workflow.createRun();
+    const run = await workflow.createRunAsync();
 
     // Execute with test data
     const result = await run.start({
@@ -63,7 +63,7 @@ npx tsx src/run-workflow.ts
 ## Key Methods
 
 - **`mastra.getWorkflow(id)`**: Gets a registered workflow by ID
-- **`workflow.createRun()`**: Creates a new execution instance
+- **`workflow.createRunAsync()`**: Creates a new execution instance
 - **`run.start(inputData)`**: Executes the workflow with provided data
 
 ## Return Value

package/.docs/raw/deployment/overview.mdx

@@ -9,6 +9,13 @@ Mastra offers multiple deployment options to suit your application's needs, from
 
 ## Deployment Options
 
+### Runtime support
+
+- Node.js `v20.0` or higher
+- Bun
+- Deno
+- [Cloudflare](../deployment/serverless-platforms/cloudflare-deployer.mdx)
+
 ### Mastra Cloud
 
 Mastra Cloud is a deployment platform that connects to your GitHub repository, automatically deploys on code changes, and provides monitoring tools. It includes:
@@ -21,7 +28,6 @@ Mastra Cloud is a deployment platform that connects to your GitHub repository, a
 
 [View Mastra Cloud documentation →](../mastra-cloud/overview.mdx)
 
-
 ### With a Web Framework
 
 Mastra can be integrated with a variety of web frameworks. For example, see one of the following for a detailed guide.

package/.docs/raw/frameworks/agentic-uis/cedar-os.mdx

@@ -0,0 +1,108 @@
+---
+title: 'Cedar-OS Integration'
+description: 'Build AI-native frontends for your Mastra agents with Cedar-OS'
+---
+
+
+import { Tabs, Steps } from "nextra/components";
+
+# Integrate Cedar-OS with Mastra
+
+Cedar-OS is an open-source agentic UI framework designed specifically for building the most ambitious AI-native applications. We built Cedar with Mastra in mind.
+
+## Should you use Cedar?
+
+There are a few pillars we care about strongly that you can read more about [here](https://docs.cedarcopilot.com/introduction/philosophy):
+
+#### 1. Developer experience
+- **Every single component is downloaded shadcn-style** – You own all the code and can style it however you want
+- **Works out of the box** – Just drop in our chat component, and it'll work
+- **Fully extensible** - Built on a [Zustand store architecture](https://docs.cedarcopilot.com/introduction/architecture) that you can customize completely. Every single internal function can be overridden in one line.
+
+#### 2. Enabling truly AI-native applications
+For the first time in history, products can come to life. We want to help you build something with life.
+- **[Spells](https://docs.cedarcopilot.com/spells/spells#what-are-spells)** - Users can trigger AI from keyboard shortcuts, mouse events, text selection, and other components
+- **[State Diff Management](https://docs.cedarcopilot.com/state-diff/using-state-diff)** - Give users control over accepting/rejecting agent outputs 
+- **[Voice Integration](https://docs.cedarcopilot.com/voice/voice-integration)** - Let users control your app with their voice
+
+## Quick Start
+
+<Steps>
+### Set up your project
+
+Run Cedar's CLI command:
+``` bash
+npx cedar-os-cli plant-seed
+```
+
+If starting from scratch, select the **Mastra starter** template for a complete setup with both frontend and backend in a monorepo
+
+If you already have a Mastra backend, use the **blank frontend cedar repo** option instead.
+- This will give you the option to download components and download all dependencies for Cedar. We recommend at least downloading one of the chat components to get started. 
+
+### Wrap your app with CedarCopilot
+
+Wrap your application with the CedarCopilot provider to connect to your Mastra backend:
+
+```tsx
+import { CedarCopilot } from 'cedar-os';
+
+function App() {
+	return (
+		<CedarCopilot
+			llmProvider={{
+				provider: 'mastra',
+				baseURL: 'http://localhost:4111', // default dev port for Mastra
+				apiKey: process.env.NEXT_PUBLIC_MASTRA_API_KEY, // optional — only for backend auth
+			}}>
+			<YourApp />
+		</CedarCopilot>
+	);
+}
+```
+
+### Configure Mastra endpoints
+
+Configure your Mastra backend to work with Cedar by following the [Mastra Configuration Options](https://docs.cedarcopilot.com/agent-backend-connection/agent-backend-connection#mastra-configuration-options).
+
+[Register API routes](https://mastra.ai/en/examples/deployment/custom-api-route) in your Mastra server (or NextJS serverless routes if in a monorepo):
+
+```ts mastra/src/index.ts
+import { registerApiRoute } from '@mastra/core/server';
+
+// POST /chat
+// The chat's non-streaming default endpoint
+registerApiRoute('/chat', {
+	method: 'POST',
+	// …validate input w/ zod
+	handler: async (c) => {
+		/* your agent.generate() logic */
+	},
+});
+
+// POST /chat/stream (SSE)
+// The chat's streaming default endpoint
+registerApiRoute('/chat/stream', {
+	method: 'POST',
+	handler: async (c) => {
+		/* stream agent output in SSE format */
+	},
+});
+```
+
+### Add Cedar components
+
+Drop Cedar components into your frontend – see [Chat Overview](https://docs.cedarcopilot.com/chat/chat-overview).
+
+Your backend and frontend are now linked! You're ready to start building AI-native experiences with your Mastra agents.
+</Steps>
+
+
+## More information
+
+- Check out the [detailed Mastra integration guide](https://docs.cedarcopilot.com/agent-backend-connection/mastra#extending-mastra) for more configuration options (or for manual installation instructions if something goes wrong)
+- Explore Mastra-specific optimizations and features we've built
+  - **Seamless event streaming** - Automatic rendering of [Mastra streamed events](https://docs.cedarcopilot.com/chat/custom-message-rendering#mastra-event-renderer)
+  - **Voice endpoint support** - Built-in [voice backend integration](https://docs.cedarcopilot.com/voice/agentic-backend#endpoint-configuration)
+  - **End-to-End type safety** - [Types](https://docs.cedarcopilot.com/type-safety/typing-agent-requests) for communicating between your app and Mastra backend
+- [Join our Discord!](https://discord.gg/4AWawRjNdZ) We're excited to have you :)

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

@@ -12,7 +12,6 @@ To get started with Mastra, you’ll need access to a large language model (LLM)
 
 Mastra also supports other LLM providers. For a full list of supported models and setup instructions, see [Model Providers](/docs/getting-started/model-providers).
 
-
 ## Prerequisites
 
 - Node.js `v20.0` or higher

package/.docs/raw/memory/overview.mdx

@@ -26,7 +26,7 @@ All memory types are [thread-scoped](./working-memory.mdx#thread-scoped-memory-d
 
 ### Working memory
 
-Stores persistent user-specific details such as names, preferences, goals, and other structured data. Uses [Markdown templates](./working-memory-template.mdx) or [Zod schemas](./working-memory-schema.mdx) to define structure.
+Stores persistent user-specific details such as names, preferences, goals, and other structured data. Uses [Markdown templates](./working-memory.mdx) or [Zod schemas](./working-memory.mdx#structured-working-memory) to define structure.
 
 ### Conversation history