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

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

@@ -0,0 +1,128 @@
+---
+title: "MastraAuthFirebase Class"
+description: "API reference for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication."
+---
+
+# 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.
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript 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 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-key.json",
+      databaseId: "your-database-id"
+    }),
+  },
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "serviceAccount",
+      type: "string",
+      description: "Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side.",
+      isOptional: true,
+      defaultValue: "process.env.FIREBASE_SERVICE_ACCOUNT"
+    },
+    {
+      name: "databaseId",
+      type: "string",
+      description: "The Firestore database ID to use. Typically '(default)' for the default database.",
+      isOptional: true,
+      defaultValue: "process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+      defaultValue: '"firebase"'
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: FirebaseUser) => Promise<boolean> | boolean",
+      description: "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.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+<PropertiesTable
+  content={[
+    {
+      name: "FIREBASE_SERVICE_ACCOUNT",
+      type: "string",
+      description: "Path to Firebase service account JSON file. Used if serviceAccount option is not provided.",
+      isOptional: true,
+    },
+    {
+      name: "FIRESTORE_DATABASE_ID",
+      type: "string",
+      description: "Firestore database ID. Primary environment variable for database configuration.",
+      isOptional: true,
+    },
+    {
+      name: "FIREBASE_DATABASE_ID",
+      type: "string",
+      description: "Alternative environment variable for Firestore database ID. Used if FIRESTORE_DATABASE_ID is not set.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## 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](/docs/auth/firebase.mdx)

package/.docs/raw/reference/cli/dev.mdx

@@ -72,6 +72,12 @@ mastra dev [options]
       description: "display help for command",
       isOptional: true,
     },
+    {
+      name: "--https",
+      type: "boolean",
+      description: "Enable local HTTPS",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -161,7 +167,7 @@ Workflows are expected to be exported from `src/mastra/workflows` (or the config
 
 ## Additional Notes
 
-The port defaults to 4111. Both the port and hostname can be configured via the mastra server config. See [Launch Development Server](/docs/server-db/local-dev-playground) for configuration details.
+The port defaults to `4111`. The port, hostname, and HTTPS settings can also be configured via the Mastra server configuration. See [Launch Development Server](/docs/server-db/local-dev-playground) for configuration details.
 
 Make sure you have your environment variables set up in your `.env.development` or `.env` file for any providers you use (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
 

package/.docs/raw/reference/client-js/agents.mdx

@@ -47,7 +47,7 @@ const response = await agent.generate({
     },
   ],
   threadId: "thread-1", // Optional: Thread ID for conversation context
-  resourceid: "resource-1", // Optional: Resource ID
+  resourceId: "resource-1", // Optional: Resource ID
   output: {}, // Optional: Output configuration
 });
 ```
@@ -207,7 +207,7 @@ const response = await agent.generateVNext(
   "Hello, how are you?",
   {
     threadId: "thread-1",
-    resourceid: "resource-1",
+    resourceId: "resource-1",
   }
 );
-```
+```

package/.docs/raw/reference/client-js/memory.mdx

@@ -57,7 +57,7 @@ Update thread properties:
 const updated = await thread.update({
   title: "Updated Title",
   metadata: { status: "resolved" },
-  resourceid: "resource-1",
+  resourceId: "resource-1",
 });
 ```
 

package/.docs/raw/reference/client-js/tools.mdx

@@ -44,6 +44,6 @@ const result = await tool.execute({
     param2: "value2",
   },
   threadId: "thread-1", // Optional: Thread context
-  resourceid: "resource-1", // Optional: Resource identifier
+  resourceId: "resource-1", // Optional: Resource identifier
 });
 ```

package/.docs/raw/reference/core/getWorkflow.mdx

@@ -46,4 +46,3 @@ mastra.getWorkflow("testWorkflow");
 ## Related
 
 - [Workflows overview](../../docs/workflows/overview.mdx)
-- [Dynamic workflows](../../docs/workflows/dynamic-workflows.mdx)

package/.docs/raw/reference/core/getWorkflows.mdx

@@ -41,4 +41,3 @@ mastra.getWorkflows();
 ## Related
 
 - [Workflows overview](../../docs/workflows/overview.mdx)
-- [Dynamic workflows](../../docs/workflows/dynamic-workflows.mdx)

package/.docs/raw/reference/core/setTelemetry.mdx

@@ -31,5 +31,5 @@ This method does not return a value.
 
 ## Related
 
-- [Telemetry overview](../../docs/observability/telemetry.mdx)
-- [Telemetry reference](../../reference/observability/telemetry.mdx)
+- [Logging](../../docs/observability/logging.mdx)
+- [PinoLogger](../../reference/observability/logger.mdx)

package/.docs/raw/reference/workflows/workflow-methods/branch.mdx

@@ -44,5 +44,5 @@ workflow.branch([
 
 ## Related
 
-- [Conditional branching](../../docs/workflows/control-flow.mdx)
-- [Conditional branching example](../../examples/workflows/conditional-branching.mdx)
+- [Conditional Branching Logic](../../../docs/workflows/control-flow#conditional-logic-with-branch)
+- [Conditional Branching Example](../../../examples/workflows/conditional-branching)

package/.docs/raw/reference/workflows/workflow-methods/commit.mdx

@@ -27,4 +27,4 @@ workflow.then(step1).commit();
 
 ## Related
 
-- [Control flow](../../docs/workflows/control-flow.mdx)
+- [Control Flow](../../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx

@@ -10,7 +10,7 @@ import { Callout } from "nextra/components";
 The `.createRunAsync()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data. This is the current API that returns a `Run` instance.
 
 <Callout>
-For the legacy `createRun()` method that returns an object with methods, see the [Legacy Workflows](../legacyWorkflows/createRun.mdx) section.
+For the legacy `createRun()` method that returns an object with methods, see the [Legacy Workflows](../../legacyWorkflows/createRun.mdx) section.
 </Callout>
 
 ## Usage example
@@ -61,5 +61,5 @@ const result = await run.start({
 
 ## Related
 
-- [Run Class](./run.mdx)
-- [Running workflows](../../examples/workflows/running-workflows.mdx)
+- [Run Class](../run.mdx)
+- [Running workflows](../../../examples/workflows/running-workflows.mdx)

package/.docs/raw/reference/workflows/workflow-methods/dountil.mdx

@@ -47,4 +47,4 @@ workflow.dountil(step1, async ({ inputData }) => true);
 
 ## Related
 
-- [Control flow](../../docs/workflows/control-flow.mdx)
+- [Control Flow](../../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/workflow-methods/dowhile.mdx

@@ -47,4 +47,4 @@ workflow.dowhile(step1, async ({ inputData }) => true);
 
 ## Related
 
-- [Control flow](../../docs/workflows/control-flow.mdx)
+- [Control Flow](../../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx

@@ -57,4 +57,4 @@ workflow.foreach(step1, { concurrency: 2 });
 
 ## Related
 
-- [For each](../../docs/workflows/control-flow.mdx)
+- [Repeating with foreach](../../../docs/workflows/control-flow.mdx#repeating-with-foreach)

package/.docs/raw/reference/workflows/workflow-methods/map.mdx

@@ -40,4 +40,4 @@ workflow.map(async ({ inputData }) => `${inputData.value} - map`
 
 ## Related
 
-- [Input data mapping](../../docs/workflows/input-data-mapping.mdx)
+- [Input data mapping](../../../docs/workflows/input-data-mapping.mdx)

package/.docs/raw/reference/workflows/workflow-methods/parallel.mdx

@@ -40,4 +40,4 @@ workflow.parallel([step1, step2]);
 
 ## Related
 
-- [Parallel workflow example](../../examples/workflows/parallel-steps.mdx)
+- [Parallel Workflow Example](../../../examples/workflows/parallel-steps.mdx)

package/.docs/raw/reference/workflows/workflow-methods/sendEvent.mdx

@@ -46,4 +46,4 @@ workflow.sendEvent('event-name', step1);
 
 ## Related
 
-- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)
+- [Sleep & Events](../../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/reference/workflows/workflow-methods/sleep.mdx

@@ -40,4 +40,4 @@ workflow.sleep(5000);
 
 ## Related
 
-- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)
+- [Sleep & Events](../../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/reference/workflows/workflow-methods/sleepUntil.mdx

@@ -48,4 +48,4 @@ workflow.sleepUntil(async ({ inputData }) => {
 
 ## Related
 
-- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)
+- [Sleep & Events](../../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/reference/workflows/workflow-methods/then.mdx

@@ -41,4 +41,4 @@ workflow.then(step1).then(step2);
 
 ## Related
 
-- [Control flow](../../docs/workflows/control-flow.mdx)
+- [Control flow](../../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/workflow-methods/waitForEvent.mdx

@@ -46,4 +46,4 @@ workflow.waitForEvent('event-name', step1);
 
 ## Related
 
-- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)
+- [Sleep & Events](../../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/server-db/local-dev-playground.mdx

@@ -126,11 +126,10 @@ The local development server includes an OpenAPI specification available at: [ht
 
 To include OpenAPI documentation in your production server, enable it in the Mastra instance:
 
-```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+```typescript {6} filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     build: {
       openAPIDocs: true
@@ -145,11 +144,10 @@ The local development server includes an interactive Swagger UI - API explorer a
 
 To include Swagger UI in your production server, enable it in the Mastra instance:
 
-```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
+```typescript {6} filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     build: {
       swaggerUI: true
@@ -170,13 +168,12 @@ This setup lets you start developing immediately with production-like behavior,
 
 ## Configuration
 
-By default, the server runs on port `4111`. You can customize the host and port through the Mastra server configuration.
+By default, the server runs on port `4111`. You can customize the `host` and `port` through the Mastra server configuration.
 
-```typescript {6,7} filename="src/mastra/index.ts" showLineNumbers copy
+```typescript {5,6} filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     port: 8080,
     host: "0.0.0.0",
@@ -184,15 +181,40 @@ export const mastra = new Mastra({
 });
 ```
 
+### Local HTTPS
+
+Mastra provides a way to use a local HTTPS server for `mastra dev` (through [expo/devcert](https://github.com/expo/devcert)). When you use the `--https` flag, a private key and certificate will be created and used for your project. By default, certificates are issued for `localhost` unless you defined another `host` value.
+
+```bash
+mastra dev --https
+```
+
+You can provide your own key and cert file by specifying the `server.https` option in the Mastra server configuration.
+
+```typescript {2,6-9} filename="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core/mastra";
+import fs from 'node:fs'
+
+export const mastra = new Mastra({
+  server: {
+    https: {
+      key: fs.readFileSync('path/to/key.pem'),
+      cert: fs.readFileSync('path/to/cert.pem')
+    }
+  },
+});
+```
+
+When you provide both `--https` and `server.https` the latter will take precedence.
+
 ## Bundler options
 
 Use `transpilePackages` to compile TypeScript packages or libraries. Use `externals` to exclude dependencies resolved at runtime, and `sourcemap` to emit readable stack traces.
 
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
+```typescript filename="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core/mastra";
 
 export const mastra = new Mastra({
-  // ...
   bundler: {
     transpilePackages: ["utils"],
     externals: ["ui"],