@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/reference/auth/clerk.md

@@ -0,0 +1,36 @@
+# MastraAuthClerk Class
+
+The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthClerk } from '@mastra/auth-clerk'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthClerk({
+      jwksUri: process.env.CLERK_JWKS_URI,
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**publishableKey?:** (`string`): Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys. (Default: `process.env.CLERK_PUBLISHABLE_KEY`)
+
+**secretKey?:** (`string`): Your Clerk secret key. Used for server-side authentication and token verification. (Default: `process.env.CLERK_SECRET_KEY`)
+
+**jwksUri?:** (`string`): The JWKS URI from your Clerk application. Used to verify JWT signatures. (Default: `process.env.CLERK_JWKS_URI`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users.
+
+## Related
+
+[MastraAuthClerk Class](https://mastra.ai/docs/server/auth/clerk)

package/.docs/reference/auth/firebase.md

@@ -0,0 +1,80 @@
+# 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.
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```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-key.json',
+      databaseId: 'your-database-id',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**serviceAccount?:** (`string`): Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side. (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)
+
+**databaseId?:** (`string`): The Firestore database ID to use. Typically '(default)' for the default database. (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"firebase"`)
+
+**authorizeUser?:** (`(user: FirebaseUser) => Promise<boolean> | boolean`): 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.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**FIREBASE\_SERVICE\_ACCOUNT?:** (`string`): Path to Firebase service account JSON file. Used if serviceAccount option is not provided.
+
+**FIRESTORE\_DATABASE\_ID?:** (`string`): Firestore database ID. Primary environment variable for database configuration.
+
+**FIREBASE\_DATABASE\_ID?:** (`string`): Alternative environment variable for Firestore database ID. Used if FIRESTORE\_DATABASE\_ID is not set.
+
+## 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](https://mastra.ai/docs/server/auth/firebase)

package/.docs/reference/auth/jwt.md

@@ -0,0 +1,26 @@
+# 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.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: '<your-secret>',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**secret:** (`string`): A unique string used to sign and verify JSON Web Tokens (JWTs) for authenticating incoming requests.
+
+## Related
+
+[MastraJwtAuth](https://mastra.ai/docs/server/auth/jwt)

package/.docs/reference/auth/supabase.md

@@ -0,0 +1,33 @@
+# 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.
+
+## 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,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**url?:** (`string`): The URL of your Supabase project. Can be found in your Supabase project settings. (Default: `process.env.SUPABASE_URL`)
+
+**anonKey?:** (`string`): The anonymous/public key for your Supabase project. Used for client-side authentication. (Default: `process.env.SUPABASE_ANON_KEY`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HoneRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks the 'isAdmin' column in the 'users' table.
+
+## Related
+
+[MastraAuthSupabase](https://mastra.ai/docs/server/auth/supabase)

package/.docs/reference/auth/workos.md

@@ -0,0 +1,84 @@
+# 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 `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID,
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) set. In that case, simply use `new MastraAuthWorkos()` without any arguments.
+
+## Constructor parameters
+
+**apiKey?:** (`string`): Your WorkOS API key. This is used to authenticate with the WorkOS API for user verification and organization management. (Default: `process.env.WORKOS_API_KEY`)
+
+**clientId?:** (`string`): Your WorkOS Client ID. This identifies your application when exchanging authorization codes for access tokens. (Default: `process.env.WORKOS_CLIENT_ID`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"workos"`)
+
+**authorizeUser?:** (`(user: WorkosUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks if the user has an 'admin' role in any organization membership.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**WORKOS\_API\_KEY?:** (`string`): Your WorkOS API key. Can be found in your WorkOS Dashboard under API Keys.
+
+**WORKOS\_CLIENT\_ID?:** (`string`): Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.
+
+## Default Authorization Behavior
+
+By default, `MastraAuthWorkos` implements role-based authorization that checks for admin access:
+
+1. **Token Verification**: The access token is verified with WorkOS to ensure it's valid and not expired
+2. **User Retrieval**: User information is extracted from the verified token
+3. **Organization Membership Check**: The system queries WorkOS for all organization memberships associated with the user's ID
+4. **Role Extraction**: All roles from the user's organization memberships are collected
+5. **Admin Check**: The system checks if any role has the slug 'admin'
+6. **Authorization Decision**: Access is granted only if the user has an admin role in at least one organization
+
+This means that by default, only users with admin privileges in at least one organization will be authorized to access your Mastra endpoints.
+
+To implement custom authorization logic (e.g., allow all authenticated users, check for specific roles, or implement custom business logic), provide a custom `authorizeUser` function.
+
+## WorkOS User Type
+
+The `WorkosUser` type used in the `authorizeUser` function corresponds to the JWT token payload returned by WorkOS. WorkOS allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. Here's an example of what the user object might look like:
+
+```javascript
+{
+  'urn:myapp:full_name': 'John Doe',
+  'urn:myapp:email': 'john.doe@example.com',
+  'urn:myapp:organization_tier': 'bronze',
+  'urn:myapp:user_language': 'en',
+  'urn:myapp:organization_domain': 'example.com',
+  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
+  sub: 'user_01XYZ789ABC123DEF456GHI012',
+  sid: 'session_01PQR456STU789VWX012YZA345',
+  jti: '01MNO678PQR901STU234VWX567',
+  org_id: 'org_01DEF234GHI567JKL890MNO123',
+  role: 'member',
+  roles: [ 'member' ],
+  permissions: [],
+  exp: 1758290589,
+  iat: 1758290289
+}
+```
+
+The properties with `urn:myapp:` prefixes are custom claims configured in your WorkOS JWT template. Standard JWT claims include `sub` (user ID), `iss` (issuer), `exp` (expiration), and WorkOS-specific claims like `org_id`, `role`, and `roles`.
+
+## Related
+
+[MastraAuthWorkos Class](https://mastra.ai/docs/server/auth/workos)

package/.docs/reference/cli/create-mastra.md

@@ -0,0 +1,137 @@
+# create-mastra
+
+The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory. You can run it with additional flags to customize the setup process.
+
+## Usage
+
+**npm**:
+
+```bash
+npx create-mastra@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest
+```
+
+**Yarn**:
+
+```bash
+yarn dlx create-mastra@latest
+```
+
+**Bun**:
+
+```bash
+bun x create-mastra@latest
+```
+
+`create-mastra` automatically runs in _interactive_ mode, but you can also specify your project name and template with command line arguments.
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-mastra-project -- --template coding-agent
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-mastra-project -- --template coding-agent
+```
+
+**Yarn**:
+
+```bash
+yarn dlx create-mastra@latest my-mastra-project -- --template coding-agent
+```
+
+**Bun**:
+
+```bash
+bun x create-mastra@latest my-mastra-project -- --template coding-agent
+```
+
+Check out the [full list](https://mastra.ai/api/templates.json) of templates and use the `slug` as input to the `--template` CLI flag.
+
+You can also use any GitHub repo as a template (it has to be a valid Mastra project):
+
+```bash
+npx create-mastra@latest my-mastra-project -- --template mastra-ai/template-coding-agent
+```
+
+You can install Mastra skills for specific agents during project creation:
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-project -- --default --skills claude-code,cursor
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+```
+
+**Yarn**:
+
+```bash
+yarn dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+```
+
+**Bun**:
+
+```bash
+bun x create-mastra@latest my-project -- --default --skills claude-code,cursor
+```
+
+## CLI flags
+
+Instead of an interactive prompt you can also define these CLI flags.
+
+**--version?:** (`boolean`): Output the version number
+
+**--project-name?:** (`string`): Project name that will be used in package.json and as the project directory name
+
+**--default?:** (`boolean`): Quick start with defaults (src, OpenAI, no examples)
+
+**--components?:** (`string`): Comma-separated list of components (agents, tools, workflows, scorers)
+
+**--llm?:** (`string`): Default model provider (openai, anthropic, groq, google, or cerebras)
+
+**--llm-api-key?:** (`string`): API key for the model provider
+
+**--example?:** (`boolean`): Include example code
+
+**--no-example?:** (`boolean`): Do not include example code
+
+**--template?:** (`string`): Create project from a template (use template name, public GitHub URL, or leave blank to select from list)
+
+**--timeout?:** (`number`): Configurable timeout for package installation, defaults to 60000 ms
+
+**--dir?:** (`string`): Target directory for Mastra source code (default: src/)
+
+**--mcp?:** (`string`): MCP Server for code editor (cursor, cursor-global, windsurf, vscode)
+
+**--skills?:** (`string`): Comma-separated list of agents to install Mastra skills for (e.g., claude-code,cursor,windsurf)
+
+**--help?:** (`boolean`): Display help for command
+
+## Telemetry
+
+By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
+
+You can opt out of the CLI analytics by setting an environment variable:
+
+```bash
+MASTRA_TELEMETRY_DISABLED=1
+```
+
+You can also set this while using other `mastra` commands:
+
+```bash
+MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest
+```