@mastra/mcp-docs-server 0.13.20 → 0.13.21-alpha.1

package/.docs/raw/auth/clerk.mdx

@@ -0,0 +1,142 @@
+---
+title: "MastraAuthClerk Class"
+description: "Documentation for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# 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 `experimental_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 filename=".env" copy
+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/clerk-auth` package.
+
+```bash copy
+npm install @mastra/clerk-auth@latest
+```
+
+## Usage example
+
+```typescript {2,7-11} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthClerk } from '@mastra/clerk-auth';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthClerk({
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+      jwksUri: process.env.CLERK_JWKS_URI
+    }),
+  },
+});
+```
+
+> **Note:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+
+> See the [MastraAuthClerk](/reference/auth/clerk.mdx) API reference 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 filename="lib/auth.ts" showLineNumbers copy
+import { useAuth } from "@clerk/nextjs";
+
+export const useClerkAuth = () => {
+  const { getToken } = useAuth();
+  
+  const getAccessToken = async () => {
+    const token = await getToken();
+    return token;
+  };
+  
+  return { getAccessToken };
+};
+```
+
+> Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid Clerk access token in the `Authorization` header:
+
+```typescript {6} filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${accessToken}`
+  }
+});
+```
+
+> **Note:** The access 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 Clerk access token, you can send authenticated requests:
+
+<Tabs items={["MastraClient", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/test-agent.tsx" showLineNumbers copy
+    "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({
+          messages: "What's the weather like in New York",
+        });
+
+        console.log({ response });
+      }
+
+      return <button onClick={handleClick}>Test Agent</button>;
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    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"
+      }'
+    ```
+  </Tab>
+</Tabs>

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

@@ -228,7 +228,9 @@ touch tsconfig.json
 
 Add the following configuration:
 
-```json filename="tsconfig.json" copy
+Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
+
+```json {4-5} filename="tsconfig.json" copy
 {
   "compilerOptions": {
     "target": "ES2022",

package/.docs/raw/getting-started/model-providers.mdx

@@ -3,7 +3,7 @@ title: "Model Providers | Getting Started | Mastra Docs"
 description: "Learn how to configure and use different model providers with Mastra."
 ---
 
-import { Callout } from 'nextra/components'
+import { Callout } from "nextra/components"
 
 # Model Providers
 
@@ -62,18 +62,18 @@ Here's an example using the OpenAI provider:
 
 ```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,4-8,13}
 import { createOpenAI } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent"
+import { Agent } from "@mastra/core/agent";
 
 const openai = createOpenAI({
-    baseUrl: "<your-custom-base-url>",
-    apiKey: "<your-custom-api-key>",
-    ...otherOptions
+  baseUrl: "<your-custom-base-url>",
+  apiKey: "<your-custom-api-key>",
+  ...otherOptions,
 });
 
 const agent = new Agent({
-    name: "WeatherAgent",
-    instructions: "Instructions for the agent...",
-    model: openai("<model-name>"),
+  name: "WeatherAgent",
+  instructions: "Instructions for the agent...",
+  model: openai("<model-name>"),
 });
 ```
 
@@ -88,21 +88,21 @@ import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { Agent } from "@mastra/core/agent";
 
 const openaiCompatible = createOpenAICompatible({
-    name: "<model-name>",
-    baseUrl: "<base-url>",
-    apiKey: "<api-key>",
-    headers: {},
-    queryParams: {},
-    fetch: async (url, options) => {
-        // custom fetch logic
-        return fetch(url, options);
-    }
+  name: "<model-name>",
+  baseUrl: "<base-url>",
+  apiKey: "<api-key>",
+  headers: {},
+  queryParams: {},
+  fetch: async (url, options) => {
+    // custom fetch logic
+    return fetch(url, options);
+  },
 });
 
 const agent = new Agent({
-    name: "WeatherAgent",
-    instructions: "Instructions for the agent...",
-    model: openaiCompatible("<model-name>"),
+  name: "WeatherAgent",
+  instructions: "Instructions for the agent...",
+  model: openaiCompatible("<model-name>"),
 });
 ```
 
@@ -114,36 +114,36 @@ The AI SDK provides a [Language Model Specification](https://github.com/vercel/a
 Following this specification, you can create your own model provider compatible with the AI SDK.
 
 Some community providers have implemented this specification and are compatible with the AI SDK.
-We will look at one such provider, the Ollama provider available in the [`ollama-ai-provider`](https://github.com/sgomez/ollama-ai-provider) package.
+We will look at one such provider, the Ollama provider available in the [`ollama-ai-provider-v2`](https://github.com/nordwestt/ollama-ai-provider-v2) package.
 
 Here's an example:
 
 ```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,7}
-import { ollama } from "ollama-ai-provider";
+import { ollama } from "ollama-ai-provider-v2";
 import { Agent } from "@mastra/core/agent";
 
 const agent = new Agent({
-    name: "WeatherAgent",
-    instructions: "Instructions for the agent...",
-    model: ollama("llama3.2:latest"),
+  name: "WeatherAgent",
+  instructions: "Instructions for the agent...",
+  model: ollama("llama3.2:latest"),
 });
 ```
 
 You can also configure the Ollama provider like so:
 
 ```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts" {1,4-7,12}
-import { createOllama } from "ollama-ai-provider";
+import { createOllama } from "ollama-ai-provider-v2";
 import { Agent } from "@mastra/core/agent";
 
 const ollama = createOllama({
-    baseUrl: "<your-custom-base-url>",
-    ...otherOptions,
+  baseUrl: "<your-custom-base-url>",
+  ...otherOptions,
 });
 
 const agent = new Agent({
-    name: "WeatherAgent",
-    instructions: "Instructions for the agent...",
-    model: ollama("llama3.2:latest"),
+  name: "WeatherAgent",
+  instructions: "Instructions for the agent...",
+  model: ollama("llama3.2:latest"),
 });
 ```
 

package/.docs/raw/observability/ai-tracing.mdx

@@ -51,27 +51,11 @@ For the latest updates, see [GitHub issue #6773](https://github.com/mastra-ai/ma
 
 ## Basic Configuration
 
-Here's a simple example of enabling AI Tracing:
-
 ```ts filename="src/mastra/index.ts" showLineNumbers copy
-import { LangfuseExporter } from '@mastra/langfuse';
-
 export const mastra = new Mastra({
   // ... other config
   observability: {
-    instances: {
-      langfuse: {
-        serviceName: 'my-service',
-        exporters: [
-          new LangfuseExporter({
-            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-            secretKey: process.env.LANGFUSE_SECRET_KEY,
-            baseUrl: process.env.LANGFUSE_BASE_URL, // Optional - defaults to Langfuse cloud
-            realtime: true,
-          }),
-        ],
-      },
-    },
+    default: { enabled: true }, // Enables DefaultExporter and CloudExporter
   },
 });
 ```
@@ -82,11 +66,16 @@ The AI tracing config accepts these properties:
 
 ```ts
 type AITracingConfig = {
+  // Enable default configuration with built-in exporters
+  default?: {
+    enabled?: boolean;
+  };
+
   // Map of tracing instance names to their configurations
-  instances: Record<string, AITracingInstanceConfig | MastraAITracing>;
+  configs?: Record<string, AITracingInstanceConfig | MastraAITracing>;
 
   // Optional function to select which tracing instance to use
-  selector?: TracingSelector;
+  configSelector?: TracingSelector;
 };
 
 type AITracingInstanceConfig = {
@@ -108,6 +97,33 @@ type AITracingInstanceConfig = {
 };
 ```
 
+### Default Configuration
+
+When `default.enabled` is set to `true`, Mastra automatically configures AI tracing with sensible defaults:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true },
+    configs: {
+      // Your custom configs can coexist with the default
+    }
+  }
+});
+```
+
+The default configuration includes:
+- **Service Name**: `"mastra"`
+- **Sampling**: Always sample (100% of traces)
+- **Exporters**: 
+  - `DefaultExporter` - Persists traces to your configured storage
+  - `CloudExporter` - Sends traces to Mastra Cloud (requires `MASTRA_CLOUD_ACCESS_TOKEN`)
+- **Processors**: `SensitiveDataFilter` - Automatically redacts sensitive fields
+
+<Callout type="info">
+  **Note**: You cannot name a custom config `"default"` when the default configuration is enabled. This will throw an error to prevent naming conflicts.
+</Callout>
+
 ### Sampling Configuration
 
 Control which traces are collected and exported:
@@ -115,7 +131,7 @@ Control which traces are collected and exported:
 ```ts filename="src/mastra/index.ts" showLineNumbers copy
 export const mastra = new Mastra({
   observability: {
-    instances: {
+    configs: {
       langfuse: {
         serviceName: 'my-service',
         // Sample all traces (default)
@@ -152,6 +168,66 @@ export const mastra = new Mastra({
 
 ## Exporters
 
+### Built-in Exporters
+
+Mastra includes two built-in exporters that are automatically configured when using the default configuration:
+
+#### DefaultExporter
+
+The `DefaultExporter` persists traces to your configured Mastra storage backend. It handles batching and retry logic automatically.
+
+**Features:**
+- Automatic batching with configurable batch size
+- Retry logic for failed exports
+- Strategy selection based on storage capabilities
+- No external dependencies required
+
+**Configuration:**
+```ts
+import { DefaultExporter } from '@mastra/core';
+
+new DefaultExporter({
+  maxBatchSize: 1000,    // Maximum spans per batch
+  maxBatchWaitMs: 5000,  // Maximum wait time before flushing
+  maxRetries: 4,         // Number of retry attempts
+  strategy: 'auto',      // 'auto' | 'realtime' | 'batch-with-updates' | 'insert-only'
+});
+```
+
+<Callout type="info">
+  If storage is not configured, the DefaultExporter will log a warning and operate as a no-op, allowing your application to continue without errors.
+</Callout>
+
+#### CloudExporter
+
+The `CloudExporter` sends traces to Mastra Cloud for online visualization and analysis.
+
+**Features:**
+- Real-time trace visualization in Mastra Cloud dashboard
+- Automatic batching and compression
+- Secure token-based authentication
+- Graceful fallback when token is not configured
+
+**Configuration:**
+```ts
+import { CloudExporter } from '@mastra/core';
+
+new CloudExporter({
+  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN, // Required (but can be pulled directly from the environment)
+  endpoint: 'https://api.mastra.ai/ai/spans/publish', // Optional custom endpoint
+  maxBatchSize: 1000,    // Maximum spans per batch
+  maxBatchWaitMs: 5000,  // Maximum wait time before flushing
+});
+```
+
+**Environment Variables:**
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Your Mastra Cloud access token
+- `MASTRA_CLOUD_AI_TRACES_ENDPOINT` - Optional custom endpoint URL
+
+<Callout type="warning">
+  If `MASTRA_CLOUD_ACCESS_TOKEN` is not set, the CloudExporter will log a message directing you to sign up at [mastra.ai](https://mastra.ai) and operate as a no-op.
+</Callout>
+
 ### Langfuse Exporter
 
 #### Installation
@@ -188,7 +264,7 @@ import { LangfuseExporter } from '@mastra/langfuse';
 
 export const mastra = new Mastra({
   observability: {
-    instances: {
+    configs: {
       langfuse: {
         serviceName: process.env.SERVICE_NAME || 'mastra-app',
         sampling: { type: 'always' },
@@ -262,7 +338,7 @@ import { BraintrustExporter } from '@mastra/braintrust';
 
 export const mastra = new Mastra({
   observability: {
-    instances: {
+    configs: {
       braintrust: {
         serviceName: 'my-service',
         exporters: [
@@ -284,7 +360,7 @@ You can configure multiple tracing instances and use a selector to choose which
 ```ts filename="mastra.config.ts" showLineNumbers copy
 export const mastra = new Mastra({
   observability: {
-    instances: {
+    configs: {
       production: {
         serviceName: 'prod-service',
         sampling: { type: 'ratio', probability: 0.1 },
@@ -296,7 +372,7 @@ export const mastra = new Mastra({
         exporters: [devLangfuseExporter],
       },
     },
-    selector: (context, availableTracers) => {
+    configSelector: (context, availableTracers) => {
       // Use development tracer for debug sessions
       if (context.runtimeContext?.get('debug') === 'true') {
         return 'development';
@@ -307,6 +383,29 @@ export const mastra = new Mastra({
 });
 ```
 
+You can also combine the default configuration with custom configs:
+
+```ts filename="mastra.config.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true }, // Provides 'default' instance
+    configs: {
+      langfuse: {
+        serviceName: 'langfuse-service',
+        exporters: [langfuseExporter],
+      },
+    },
+    configSelector: (context, availableTracers) => {
+      // Route specific requests to langfuse, others to default
+      if (context.runtimeContext?.get('useExternalTracing')) {
+        return 'langfuse';
+      }
+      return 'default';
+    },
+  },
+});
+```
+
 ## Span Types and Attributes
 
 AI Tracing automatically creates spans for different AI operations. Mastra supports the following span types: