@mastra/mcp-docs-server 0.13.7-alpha.5 → 0.13.8-alpha.0

package/.docs/raw/reference/observability/logger.mdx

@@ -1,86 +1,98 @@
 ---
-title: "Reference: Logger Instance | Mastra Observability Docs"
-description: Documentation for Logger instances, which provide methods to record events at various severity levels.
+title: "Reference: PinoLogger | Mastra Observability Docs"
+description: Documentation for PinoLogger, which provides methods to record events at various severity levels.
 ---
 
-# Logger Instance
+# PinoLogger
 
-A Logger instance is created by `new PinoLogger()` and provides methods to record events at various severity levels. Depending on the logger type, messages may be written to the console, file, or an external service.
+A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-## Example
+When deploying to Mastra Cloud, logs are displayed on the [Logs](../../docs/mastra-cloud/dashboard.mdx#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-```typescript showLineNumbers copy
-// Using a console logger
-const logger = new PinoLogger({ name: "Mastra", level: "info" });
+## Usage example
 
-logger.debug("Debug message"); // Won't be logged because level is INFO
-logger.info({
-  message: "User action occurred",
-  destinationPath: "user-actions",
-  type: "AGENT",
-}); // Logged
-logger.error("An error occurred"); // Logged as ERROR
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
+
+export const mastra = new Mastra({
+  // ...
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+});
 ```
 
-## Methods
+## Parameters
 
 <PropertiesTable
   content={[
     {
-      name: "debug",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write a DEBUG-level log. Only recorded if level ≤ DEBUG.",
+      name: "name",
+      type: "string",
+      description: "A label used to group and identify logs from this logger.",
     },
-    {
-      name: "info",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write an INFO-level log. Only recorded if level ≤ INFO.",
+     {
+      name: "level",
+      type: `"debug" | "info" | "warn" | "error"`,
+      description: "Sets the minimum log level. Messages below this level are ignored.",
     },
     {
-      name: "warn",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write a WARN-level log. Only recorded if level ≤ WARN.",
+      name: "transports",
+      type: "Record<string, LoggerTransport>",
+      description: "A map of transport instances used to persist logs.",
     },
     {
-      name: "error",
-      type: "(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>",
-      description: "Write an ERROR-level log. Only recorded if level ≤ ERROR.",
+      name: "overrideDefaultTransports",
+      type: "boolean",
+      isOptional: true,
+      description: "If true, disables the default console transport.",
     },
     {
-      name: "cleanup",
-      type: "() => Promise<void>",
+      name: "formatters",
+      type: "pino.LoggerOptions['formatters']",
       isOptional: true,
-      description:
-        "Cleanup resources held by the logger (e.g., network connections for Upstash). Not all loggers implement this.",
+      description: "Custom Pino formatters for log serialization.",
     },
   ]}
 />
 
-**Note:** Some loggers require a `BaseLogMessage` object (with `message`, `destinationPath`, `type` fields). For instance, the `File` and `Upstash` loggers need structured messages.
 
-## File Transport (Structured Logs)
+## File transport (structured logs)
 
-```typescript showLineNumbers copy
+Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.
+
+
+```typescript filename="src/mastra/loggers/file-transport.ts" showLineNumbers copy
 import { FileTransport } from "@mastra/loggers/file";
+import { PinoLogger } from "@mastra/loggers/pino";
 
-const fileLogger = new PinoLogger({
+export const fileLogger = new PinoLogger({
   name: "Mastra",
   transports: { file: new FileTransport({ path: "test-dir/test.log" }) },
   level: "warn",
 });
+```
+
+### File transport usage
 
+```typescript showLineNumbers copy
 fileLogger.warn("Low disk space", {
   destinationPath: "system",
   type: "WORKFLOW",
 });
 ```
 
-## Upstash Logger (Remote Log Drain)
+## Upstash transport (remote log drain)
 
-```typescript showLineNumbers copy
+Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
+
+```typescript filename="src/mastra/loggers/upstash-transport.ts" showLineNumbers copy
 import { UpstashTransport } from "@mastra/loggers/upstash";
+import { PinoLogger } from "@mastra/loggers/pino";
 
-const logger = new PinoLogger({
+export const upstashLogger = new PinoLogger({
   name: "Mastra",
   transports: {
     upstash: new UpstashTransport({
@@ -91,28 +103,35 @@ const logger = new PinoLogger({
   },
   level: "info",
 });
+```
 
-logger.info({
-  message: "User signed in",
+
+### Upstash transport usage
+
+```typescript showLineNumbers copy
+upstashLogger.info("User signed in", {
   destinationPath: "auth",
   type: "AGENT",
   runId: "run_123",
 });
 ```
 
-## Custom Transport
+## Custom transport
 
 You can create custom transports using the `createCustomTransport` utility to integrate with any logging service or stream.
 
-### Example: Sentry Integration
+### Sentry transport example
 
-```typescript showLineNumbers copy
+Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
+
+```typescript filename="src/mastra/loggers/sentry-transport.ts" showLineNumbers copy
 import { createCustomTransport } from "@mastra/core/loggers";
-import pinoSentry from 'pino-sentry-transport';
+import { PinoLogger } from "@mastra/loggers/pino";
+import pinoSentry from "pino-sentry-transport";
 
 const sentryStream = await pinoSentry({
   sentry: {
-    dsn: 'YOUR_SENTRY_DSN',
+    dsn: "YOUR_SENTRY_DSN",
     _experiments: {
       enableLogs: true,
     },
@@ -121,9 +140,9 @@ const sentryStream = await pinoSentry({
 
 const customTransport = createCustomTransport(sentryStream);
 
-const logger = new PinoLogger({
+export const sentryLogger = new PinoLogger({
   name: "Mastra",
-  transports: { sentry: customTransport },
   level: "info",
+  transports: { sentry: customTransport },
 });
-```
+```

package/.docs/raw/reference/observability/providers/langfuse.mdx

@@ -11,36 +11,69 @@ Langfuse is an open-source observability platform designed specifically for LLM
 
 ## Configuration
 
-To use Langfuse with Mastra, you'll need to configure the following environment variables:
+To use Langfuse with Mastra, you can configure it using either environment variables or directly in your Mastra configuration.
+
+### Using Environment Variables
+
+Set the following environment variables:
 
 ```env
-LANGFUSE_PUBLIC_KEY=your_public_key
-LANGFUSE_SECRET_KEY=your_secret_key
-LANGFUSE_BASEURL=https://cloud.langfuse.com  # Optional - defaults to cloud.langfuse.com
+OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel/v1/traces" # 🇪🇺 EU data region
+# OTEL_EXPORTER_OTLP_ENDPOINT="https://us.cloud.langfuse.com/api/public/otel/v1/traces" # 🇺🇸 US data region
+
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING}"
+```
+
+Where `AUTH_STRING` is the base64-encoded combination of your public and secret keys (see below).
+
+### Generating AUTH_STRING
+
+The authorization uses basic auth with your Langfuse API keys. You can generate the base64-encoded auth string using:
+
+```bash
+echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64
 ```
 
-**Important**: When configuring the telemetry export settings, the `traceName` parameter must be set to `"ai"` for the Langfuse integration to work properly.
+For long API keys on GNU systems, you may need to add `-w 0` to prevent auto-wrapping:
+
+```bash
+echo -n "pk-lf-1234567890:sk-lf-1234567890" | base64 -w 0
+```
 
 ## Implementation
 
-Here's how to configure Mastra to use Langfuse:
+Here's how to configure Mastra to use Langfuse with OpenTelemetry:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    enabled: true,
+    export: {
+      type: 'otlp',
+      endpoint: 'https://cloud.langfuse.com/api/public/otel/v1/traces', // or your preferred endpoint
+      headers: {
+        Authorization: `Basic ${AUTH_STRING}`, // Your base64-encoded auth string
+      },
+    },
+  },
+});
+```
+
+Alternatively, if you're using environment variables, you can simplify the configuration:
 
 ```typescript
 import { Mastra } from "@mastra/core";
-import { LangfuseExporter } from "langfuse-vercel";
 
 export const mastra = new Mastra({
   // ... other config
   telemetry: {
-    serviceName: "ai", // this must be set to "ai" so that the LangfuseExporter thinks it's an AI SDK trace
     enabled: true,
     export: {
-      type: "custom",
-      exporter: new LangfuseExporter({
-        publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-        secretKey: process.env.LANGFUSE_SECRET_KEY,
-        baseUrl: process.env.LANGFUSE_BASEURL,
-      }),
+      type: 'otlp',
+      // endpoint and headers will be read from OTEL_EXPORTER_OTLP_* env vars
     },
   },
 });

package/.docs/raw/reference/workflows/dountil.mdx

@@ -47,5 +47,4 @@ workflow.dountil(stepOne, async ({ inputData }) => true);
 
 ## Related
 
-- [Loops](../../docs/workflows/control-flow.mdx#loops)
-- [Loops example](../../examples/workflows/control-flow.mdx)
+- [Control flow](../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/dowhile.mdx

@@ -47,5 +47,4 @@ workflow.dowhile(stepOne, async ({ inputData }) => true);
 
 ## Related
 
-- [Loops](../../docs/workflows/flow-control.mdx#loops)
-- [Loops example](../../examples/workflows/control-flow.mdx)
+- [Control flow](../../docs/workflows/control-flow.mdx)

package/.docs/raw/reference/workflows/resume.mdx

@@ -15,12 +15,22 @@ const result = await run.start({ inputData: { startValue: 0 } });
 
 if (result.status === "suspended") {
   const resumedResults = await run.resume({
-    step: result.suspended[0],
     resumeData: { newValue: 0 },
   });
 }
 ```
 
+
+For more advanced scenarios where you need to specify the exact step to resume:
+
+```typescript
+await run.resume({
+  step: result.suspended[0], // Explicitly choose which step to resume
+  resumeData: { newValue: 0 },
+});
+```
+> **Note**: When exactly one step is suspended, you can omit the `step` parameter and the workflow will automatically resume that step. For workflows with multiple suspended steps, you must explicitly specify which step to resume.
+
 ## Parameters
 
 <PropertiesTable
@@ -40,8 +50,8 @@ if (result.status === "suspended") {
         {
           name: "step",
           type: "Step | Step[] | string | string[]",
-          description: "The step(s) to resume execution from",
-          isOptional: false,
+          description: "The step(s) to resume execution from. When omitted, the workflow will automatically resume the suspended step if exactly one step is suspended. Throws an error if multiple steps are suspended and no step is specified.",
+          isOptional: true,
         },
         {
           name: "runtimeContext",

package/.docs/raw/reference/workflows/step.mdx

@@ -156,5 +156,4 @@ const processOrder = createStep({
 
 - [Control flow](../../docs/workflows/control-flow.mdx)
 - [Using agents and tools](../../docs/workflows/using-with-agents-and-tools.mdx)
-- [Tool and agent as step example](../../examples/workflows/agent-and-tool-interop.mdx)
 - [Input data mapping](../../docs/workflows/input-data-mapping.mdx)

package/.docs/raw/reference/workflows/streamVNext.mdx

@@ -0,0 +1,215 @@
+---
+title: "Reference: Workflow.streamVNext() | Streaming | Workflows | Mastra Docs"
+description: Documentation for the `.streamVNext()` method in Mastra workflows, which enables real-time streaming of responses.
+---
+
+# `streamVNext()`
+
+The `streamVNext()` method enables real-time streaming of responses from a workflow.
+
+## Usage
+
+```typescript
+const run = await myWorkflow.createRunAsync();
+
+// Add a stream to monitor execution
+const stream = run.streamVNext({ inputData: {...} });
+
+
+for (const chunk of stream) {
+  // do something with the chunk
+}
+
+```
+
+## Protocol
+
+<PropertiesTable
+  content={[
+    {
+      name: "start",
+      type: "object",
+      description: "The workflow starts",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'start', runId: '1', from: 'WORKFLOW', payload: { runId: '1' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "step-start",
+      type: "object",
+      description: "The start of a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'step-start', runId: '1', from: 'WORKFLOW', payload: { id: 'fetch-weather' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "step-output",
+      type: "object",
+      description: "Custom output from a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'step-output', runId: '1', from: 'WORKFLOW', payload: { stepName: 'my step', args: { ... }, stepCallId: 'uuid', startedAt: 1717000000000, status: 'running' } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "step-result",
+      type: "object",
+      description: "The result of a step",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'step-result', runId: '1', from: 'WORKFLOW', payload: { stepName: 'my step', result: { ... }, stepCallId: 'uuid', endedAt: 1717000000000, status: 'success', output: [Object] } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "finish",
+      type: "object",
+      description: "The end of the workflow",
+      isOptional: false,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "example",
+              type: "{ type: 'finish', runId: '1', from: 'WORKFLOW', payload: { totalUsage: { promptTokens: 100, completionTokens: 100, totalTokens: 200 } } }",
+              description: "Example message structure",
+              isOptional: false,
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+### PropertiesTable for Return Values
+
+<PropertiesTable
+  content={[
+    {
+      name: "usage",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "Total usage of the workflow, including sub agents/workflows as a step.",
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "promptTokens",
+              type: "number",
+              isOptional: true,
+              description: "The number of prompt tokens used by the agent.",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "completionTokens",
+              type: "number",
+              isOptional: true,
+              description: "The number of completion tokens used by the agent.",
+            },
+          ],
+        },
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "totalTokens",
+              type: "number", 
+              isOptional: true,
+              description: "The total number of tokens used by the agent.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "status",
+      type: "Promise<string>",
+      isOptional: true,
+      description:
+        "The status of the workflow run.",
+    },
+    {
+      name: "result",
+      type: "Promise<object>",
+      isOptional: true,
+      description:
+        "The result of the workflow run.",
+    },
+  ]}
+/>
+
+## Examples
+
+### Basic Streaming
+
+```typescript
+const run = await myWorkflow.createRunAsync();
+const stream = run.streamVNext({ inputData: {...} });
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Structured Output Streaming
+
+```typescript
+const run = await myWorkflow.createRunAsync();
+const stream = run.streamVNext({ inputData: {...} });
+
+
+const result = await stream.result;
+console.log("Final structured result:", result);
+```
+

package/.docs/raw/workflows/streaming.mdx

@@ -0,0 +1,115 @@
+---
+title: "Using Workflow Streaming | Workflows | Mastra Docs"
+description: Documentation on how to stream workflows
+---
+
+# Workflow Streaming
+
+Workflows in Mastra have access to a powerful streaming protocol! With seamless integration into tools or agents as a step, you can stream responses directly back to your clients, creating a more interactive and engaging experience.
+
+## Usage
+
+To use the new protocol, you can use the `streamVNext` method on an workflow. This method will return a custom MatraWorkflowStream. This stream extends a ReadableStream, so all basic stream methods are available.
+
+```typescript
+const run = await myWorkflow.createRunAsync();
+const stream = await run.streamVNext({ inputData: { city: 'New York' } });
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+Each chunk is a JSON object with the following properties:
+
+```json
+{
+  type: string;
+  runId: string;
+  from: string;
+  payload: Record<string, any>;
+}
+```
+
+We have a couple of utility functions on the stream to help you with the streaming process.
+
+- `stream.status` - The status of the workflow run.
+- `stream.result` - The result of the workflow run.
+- `stream.usage` - The total token usage of the workflow run.
+
+### How to use the stream in a tool
+
+Each tool gets a `writer` argument, which is a writable stream with a custom write function. This write function is used to write the tool's response to the stream.
+
+```typescript filename="src/mastra/workflows/weather.ts" showLineNumbers copy
+import { createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+export const weatherInfo = createStep({
+  id: "weather-info",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    conditions: z.string(),
+    temperature: z.number(),
+  }),
+  description: `Fetches the current weather information for a given city`,
+  execute: async ({ inputData: { city }, writer }) => {
+    writer.write({
+      type: "weather-data",
+      args: {
+        city
+      },
+      status: "pending"
+    })
+    // Tool logic here (e.g., API call)
+    console.log("Using tool to fetch weather information for", city);
+
+    writer.write({
+      type: "weather-data",
+      args: {
+        city
+      },
+      status: "success",
+      result: {
+        temperature: 20,
+        conditions: "Sunny"
+      }
+    })
+
+    return { temperature: 20, conditions: "Sunny" }; // Example return
+  },
+});
+```
+
+If you want to use the stream in an agent, you can use the `streamVNext` method on the agent and pipe it to the agent's input stream.
+
+```typescript filename="src/mastra/workflows/weather.ts" showLineNumbers copy
+import { createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+export const weatherInfo = createStep({
+  id: "weather-info",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+  description: `Fetches the current weather information for a given city`,
+  execute: async ({ inputData: { city }, writer, mastra }) => {
+    const agent = mastra.getAgent('weatherAgent')
+    const stream = await agent.streamVNext(`What is the weather in ${city}?`);
+
+    await stream.pipeTo(writer);
+
+    return {
+      text: await stream.text,
+    }
+  },
+});
+```
+
+Piping the stream to the agent's input stream will allow us to automatically sum up the usage of the agent so the total usage count can be calculated.
+