@mastra/mcp-docs-server 0.0.3 → 0.0.4-alpha.1

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

@@ -0,0 +1,134 @@
+---
+title: ".resumeWithEvent() Method | Mastra Docs"
+description: "Reference for the resumeWithEvent method that resumes suspended workflows using event data."
+---
+
+# resumeWithEvent()
+
+The `resumeWithEvent()` method resumes workflow execution by providing data for a specific event that the workflow is waiting for.
+
+## Syntax
+
+```typescript
+const run = workflow.createRun();
+
+// After the workflow has started and suspended at an event step
+await run.resumeWithEvent(eventName: string, data: any): Promise<WorkflowRunResult>
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| eventName | string | The name of the event to trigger. Must match an event defined in the workflow's `events` configuration. |
+| data | any | The event data to provide. Must conform to the schema defined for that event. |
+
+## Return Value
+
+Returns a Promise that resolves to a `WorkflowRunResult` object, containing:
+
+- `results`: The result status and output of each step in the workflow
+- `activePaths`: A map of active workflow paths and their states
+- `value`: The current state value of the workflow
+- Other workflow execution metadata
+
+## Description
+
+The `resumeWithEvent()` method is used to resume a workflow that has been suspended at an event step created by the `afterEvent()` method. When called, this method:
+
+1. Validates the provided event data against the schema defined for that event
+2. Loads the workflow snapshot from storage
+3. Updates the context with the event data in the `resumedEvent` field
+4. Resumes execution from the event step
+5. Continues workflow execution with the subsequent steps
+
+This method is part of Mastra's event-driven workflow capabilities, allowing you to create workflows that can respond to external events or user interactions.
+
+## Usage Notes
+
+- The workflow must be in a suspended state, specifically at the event step created by `afterEvent(eventName)`
+- The event data must conform to the schema defined for that event in the workflow configuration
+- The workflow will continue execution from the point it was suspended
+- If the workflow is not suspended or is suspended at a different step, this method may throw an error
+- The event data is made available to subsequent steps via `context.inputData.resumedEvent`
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Define and start a workflow
+const workflow = mastra.getWorkflow('approval-workflow');
+const run = workflow.createRun();
+
+// Start the workflow
+await run.start({ triggerData: { requestId: 'req-123' } });
+
+// Later, when the approval event occurs:
+const result = await run.resumeWithEvent('approval', {
+  approved: true,
+  approverName: 'John Doe',
+  comment: 'Looks good to me!'
+});
+
+console.log(result.results);
+```
+
+### With Error Handling
+
+```typescript
+try {
+  const result = await run.resumeWithEvent('paymentReceived', {
+    amount: 100.50,
+    transactionId: 'tx-456',
+    paymentMethod: 'credit-card',
+  });
+
+  console.log('Workflow resumed successfully:', result.results);
+} catch (error) {
+  console.error('Failed to resume workflow with event:', error);
+  // Handle error - could be invalid event data, workflow not suspended, etc.
+}
+```
+
+### Monitoring and Auto-Resuming
+
+```typescript
+// Start a workflow
+const { start, watch, resumeWithEvent } = workflow.createRun();
+
+// Watch for suspended event steps
+watch(async ({ context, activePaths }) => {
+  // Check if suspended at the approval event step
+  if (activePaths.some(path =>
+    path.stepId === '__approval_event' &&
+    path.status === 'suspended'
+  )) {
+    console.log('Workflow waiting for approval');
+
+    // In a real scenario, you would wait for the actual event
+    // Here we're simulating with a timeout
+    setTimeout(async () => {
+      try {
+        await resumeWithEvent('approval', {
+          approved: true,
+          approverName: 'Auto Approver',
+        });
+      } catch (error) {
+        console.error('Failed to auto-resume workflow:', error);
+      }
+    }, 5000); // Wait 5 seconds before auto-approving
+  }
+});
+
+// Start the workflow
+await start({ triggerData: { requestId: 'auto-123' } });
+```
+
+## Related
+
+- [Event-Driven Workflows](./events.mdx)
+- [afterEvent()](./afterEvent.mdx)
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [resume()](./resume.mdx)
+- [watch()](./watch.mdx)

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

@@ -0,0 +1,204 @@
+---
+title: "Reference: Snapshots | Workflow State Persistence | Mastra Docs"
+description: "Technical reference on snapshots in Mastra - the serialized workflow state that enables suspend and resume functionality"
+---
+
+# Snapshots
+
+In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
+
+- The current state of each step in the workflow
+- The outputs of completed steps
+- The execution path taken through the workflow
+- Any suspended steps and their metadata
+- The remaining retry attempts for each step
+- Additional contextual data needed to resume execution
+
+Snapshots are automatically created and managed by Mastra whenever a workflow is suspended, and are persisted to the configured storage system.
+
+## The Role of Snapshots in Suspend and Resume
+
+Snapshots are the key mechanism enabling Mastra's suspend and resume capabilities. When a workflow step calls `await suspend()`:
+
+1. The workflow execution is paused at that exact point
+2. The current state of the workflow is captured as a snapshot
+3. The snapshot is persisted to storage
+4. The workflow step is marked as "suspended" with a status of `'suspended'`
+5. Later, when `resume()` is called on the suspended step, the snapshot is retrieved
+6. The workflow execution resumes from exactly where it left off
+
+This mechanism provides a powerful way to implement human-in-the-loop workflows, handle rate limiting, wait for external resources, and implement complex branching workflows that may need to pause for extended periods.
+
+## Snapshot Anatomy
+
+A Mastra workflow snapshot consists of several key components:
+
+```typescript
+export interface WorkflowRunState {
+  // Core state info
+  value: Record<string, string>;      // Current state machine value
+  context: {                          // Workflow context
+    steps: Record<string, {           // Step execution results
+      status: 'success' | 'failed' | 'suspended' | 'waiting' | 'skipped';
+      payload?: any;                  // Step-specific data
+      error?: string;                 // Error info if failed
+    }>;
+    triggerData: Record<string, any>; // Initial trigger data
+    attempts: Record<string, number>; // Remaining retry attempts
+    inputData: Record<string, any>; 	// Initial input data
+  };
+
+  activePaths: Array<{               // Currently active execution paths
+    stepPath: string[];
+    stepId: string;
+    status: string;
+  }>;
+
+  // Metadata
+  runId: string;                     // Unique run identifier
+  timestamp: number;                 // Time snapshot was created
+
+  // For nested workflows and suspended steps
+  childStates?: Record<string, WorkflowRunState>;  // Child workflow states
+  suspendedSteps?: Record<string, string>;         // Mapping of suspended steps
+}
+```
+
+## How Snapshots Are Saved and Retrieved
+
+Mastra persists snapshots to the configured storage system. By default, snapshots are saved to a LibSQL database, but can be configured to use other storage providers like Upstash.
+The snapshots are stored in the `workflow_snapshots` table and identified uniquely by the `run_id` for the associated run when using libsql.
+Utilizing a persistence layer allows for the snapshots to be persisted across workflow runs, allowing for advanced human-in-the-loop functionality.
+
+Read more about [libsql storage](../storage/libsql.mdx) and [upstash storage](../storage/upstash.mdx) here.
+
+### Saving Snapshots
+
+When a workflow is suspended, Mastra automatically persists the workflow snapshot with these steps:
+
+1. The `suspend()` function in a step execution triggers the snapshot process
+2. The `WorkflowInstance.suspend()` method records the suspended machine
+3. `persistWorkflowSnapshot()` is called to save the current state
+4. The snapshot is serialized and stored in the configured database in the `workflow_snapshots` table
+5. The storage record includes the workflow name, run ID, and the serialized snapshot
+
+
+### Retrieving Snapshots
+
+When a workflow is resumed, Mastra retrieves the persisted snapshot with these steps:
+
+1. The `resume()` method is called with a specific step ID
+2. The snapshot is loaded from storage using `loadWorkflowSnapshot()`
+3. The snapshot is parsed and prepared for resumption
+4. The workflow execution is recreated with the snapshot state
+5. The suspended step is resumed, and execution continues
+
+## Storage Options for Snapshots
+
+Mastra provides multiple storage options for persisting snapshots.
+
+A `storage` instance is configured on the `Mastra` class, and is used to setup a snapshot persistence layer for all workflows registered on the `Mastra` instance.
+This means that storage is shared across all workflows registered with the same `Mastra` instance.
+
+### LibSQL (Default)
+
+The default storage option is LibSQL, a SQLite-compatible database:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { DefaultStorage } from '@mastra/core/storage/libsql';
+
+const mastra = new Mastra({
+  storage: new DefaultStorage({
+    config: {
+      url: "file:storage.db", // Local file-based database
+      // For production:
+      // url: process.env.DATABASE_URL,
+      // authToken: process.env.DATABASE_AUTH_TOKEN,
+    }
+  }),
+  workflows: {
+    weatherWorkflow,
+    travelWorkflow,
+  }
+});
+```
+
+### Upstash (Redis-Compatible)
+
+For serverless environments:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { UpstashStore } from "@mastra/upstash";
+
+const mastra = new Mastra({
+  storage: new UpstashStore({
+    url: process.env.UPSTASH_URL,
+    token: process.env.UPSTASH_TOKEN,
+  }),
+  workflows: {
+    weatherWorkflow,
+    travelWorkflow,
+  }
+});
+```
+
+## Best Practices for Working with Snapshots
+
+1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
+
+2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
+
+3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
+
+4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
+
+5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
+
+## Advanced Snapshot Patterns
+
+### Custom Snapshot Metadata
+
+When suspending a workflow, you can include custom metadata that can help when resuming:
+
+```typescript
+await suspend({
+  reason: "Waiting for customer approval",
+  requiredApprovers: ["manager", "finance"],
+  requestedBy: currentUser,
+  urgency: "high",
+  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
+});
+```
+
+This metadata is stored with the snapshot and available when resuming.
+
+### Conditional Resumption
+
+You can implement conditional logic based on the suspend payload when resuming:
+
+```typescript
+run.watch(async ({ context, activePaths }) => {
+  for (const path of activePaths) {
+    const approvalStep = context.steps?.approval;
+    if (approvalStep?.status === 'suspended') {
+      const payload = approvalStep.suspendPayload;
+
+      if (payload.urgency === "high" && currentUser.role === "manager") {
+        await resume({
+          stepId: 'approval',
+          context: { approved: true, approver: currentUser.id },
+        });
+      }
+    }
+  }
+});
+```
+
+## Related
+
+- [Suspend Function Reference](./suspend.mdx)
+- [Resume Function Reference](./resume.mdx)
+- [Watch Function Reference](./watch.mdx)
+- [Suspend and Resume Guide](../../workflows/suspend-and-resume.mdx)

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

@@ -0,0 +1,203 @@
+---
+title: "Step Retries | Error Handling | Mastra Docs"
+description: "Automatically retry failed steps in Mastra workflows with configurable retry policies."
+---
+
+# Step Retries
+
+Mastra provides built-in retry mechanisms to handle transient failures in workflow steps. This allows workflows to recover gracefully from temporary issues without requiring manual intervention.
+
+## Overview
+
+When a step in a workflow fails (throws an exception), Mastra can automatically retry the step execution based on a configurable retry policy. This is useful for handling:
+
+- Network connectivity issues
+- Service unavailability
+- Rate limiting
+- Temporary resource constraints
+- Other transient failures
+
+## Default Behavior
+
+By default, steps do not retry when they fail. This means:
+
+- A step will execute once
+- If it fails, it will immediately mark the step as failed
+- The workflow will continue to execute any subsequent steps that don't depend on the failed step
+
+## Configuration Options
+
+Retries can be configured at two levels:
+
+### 1. Workflow-level Configuration
+
+You can set a default retry configuration for all steps in a workflow:
+
+```typescript
+const workflow = new Workflow({
+  name: 'my-workflow',
+  retryConfig: {
+    attempts: 3,    // Number of retries (in addition to the initial attempt)
+    delay: 1000,    // Delay between retries in milliseconds
+  },
+});
+```
+
+### 2. Step-level Configuration
+
+You can also configure retries on individual steps, which will override the workflow-level configuration for that specific step:
+
+```typescript
+const fetchDataStep = new Step({
+  id: 'fetchData',
+  execute: async () => {
+    // Fetch data from external API
+  },
+  retryConfig: {
+    attempts: 5,    // This step will retry up to 5 times
+    delay: 2000,    // With a 2-second delay between retries
+  },
+});
+```
+
+## Retry Parameters
+
+The `retryConfig` object supports the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `attempts` | number | 0 | The number of retry attempts (in addition to the initial attempt) |
+| `delay` | number | 1000 | Time in milliseconds to wait between retries |
+
+## How Retries Work
+
+When a step fails, Mastra's retry mechanism:
+
+1. Checks if the step has retry attempts remaining
+2. If attempts remain:
+   - Decrements the attempt counter
+   - Transitions the step to a "waiting" state
+   - Waits for the configured delay period
+   - Retries the step execution
+3. If no attempts remain or all attempts have been exhausted:
+   - Marks the step as "failed"
+   - Continues workflow execution (for steps that don't depend on the failed step)
+
+During retry attempts, the workflow execution remains active but paused for the specific step that is being retried.
+
+## Examples
+
+### Basic Retry Example
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+
+// Define a step that might fail
+const unreliableApiStep = new Step({
+  id: 'callUnreliableApi',
+  execute: async () => {
+    // Simulate an API call that might fail
+    const random = Math.random();
+    if (random < 0.7) {
+      throw new Error('API call failed');
+    }
+    return { data: 'API response data' };
+  },
+  retryConfig: {
+    attempts: 3,  // Retry up to 3 times
+    delay: 2000,  // Wait 2 seconds between attempts
+  },
+});
+
+// Create a workflow with the unreliable step
+const workflow = new Workflow({
+  name: 'retry-demo-workflow',
+});
+
+workflow
+  .step(unreliableApiStep)
+  .then(processResultStep)
+  .commit();
+```
+
+### Workflow-level Retries with Step Override
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+
+// Create a workflow with default retry configuration
+const workflow = new Workflow({
+  name: 'multi-retry-workflow',
+  retryConfig: {
+    attempts: 2,  // All steps will retry twice by default
+    delay: 1000,  // With a 1-second delay
+  },
+});
+
+// This step uses the workflow's default retry configuration
+const standardStep = new Step({
+  id: 'standardStep',
+  execute: async () => {
+    // Some operation that might fail
+  },
+});
+
+// This step overrides the workflow's retry configuration
+const criticalStep = new Step({
+  id: 'criticalStep',
+  execute: async () => {
+    // Critical operation that needs more retry attempts
+  },
+  retryConfig: {
+    attempts: 5,  // Override with 5 retry attempts
+    delay: 5000,  // And a longer 5-second delay
+  },
+});
+
+// This step disables retries
+const noRetryStep = new Step({
+  id: 'noRetryStep',
+  execute: async () => {
+    // Operation that should not retry
+  },
+  retryConfig: {
+    attempts: 0,  // Explicitly disable retries
+  },
+});
+
+workflow
+  .step(standardStep)
+  .then(criticalStep)
+  .then(noRetryStep)
+  .commit();
+```
+
+## Monitoring Retries
+
+You can monitor retry attempts in your logs. Mastra logs retry-related events at the `debug` level:
+
+```
+[DEBUG] Step fetchData failed (runId: abc-123)
+[DEBUG] Attempt count for step fetchData: 2 remaining attempts (runId: abc-123)
+[DEBUG] Step fetchData waiting (runId: abc-123)
+[DEBUG] Step fetchData finished waiting (runId: abc-123)
+[DEBUG] Step fetchData pending (runId: abc-123)
+```
+
+## Best Practices
+
+1. **Use Retries for Transient Failures**: Only configure retries for operations that might experience transient failures. For deterministic errors (like validation failures), retries won't help.
+
+2. **Set Appropriate Delays**: Consider using longer delays for external API calls to allow time for services to recover.
+
+3. **Limit Retry Attempts**: Don't set extremely high retry counts as this could cause workflows to run for excessive periods during outages.
+
+4. **Implement Idempotent Operations**: Ensure your step's `execute` function is idempotent (can be called multiple times without side effects) since it may be retried.
+
+5. **Consider Backoff Strategies**: For more advanced scenarios, consider implementing exponential backoff in your step's logic for operations that might be rate-limited.
+
+## Related
+
+- [Step Class Reference](./step-class.mdx)
+- [Workflow Configuration](./workflow.mdx)
+- [Error Handling in Workflows](../../workflows/error-handling.mdx)

package/.docs/raw/voice/overview.mdx

@@ -0,0 +1,135 @@
+---
+title: Voice in Mastra | Mastra Docs
+description: Overview of voice capabilities in Mastra, including text-to-speech, speech-to-text, and real-time voice-to-voice interactions.
+---
+
+# Voice in Mastra
+
+Mastra's Voice system provides a unified interface for voice interactions, enabling text-to-speech (TTS), speech-to-text (STT), and real-time voice-to-voice capabilities in your applications.
+
+## Key Features
+
+- Standardized API across different voice providers
+- Support for multiple voice services
+- Voice-to-voice interactions using events for continuous audio streaming
+- Composable voice providers for mixing TTS and STT services
+
+## Adding Voice to Agents
+
+To learn how to integrate voice capabilities into your agents, check out the [Adding Voice to Agents](../agents/03-adding-voice.mdx) documentation. This section covers how to use both single and multiple voice providers, as well as real-time interactions.
+
+
+## Example of Using a Single Voice Provider
+
+```typescript
+import { OpenAIVoice } from "@mastra/voice-openai";
+
+// Initialize OpenAI voice for TTS
+const voice = new OpenAIVoice({
+  speechModel: {
+    name: "tts-1-hd", // Specify the TTS model
+    apiKey: process.env.OPENAI_API_KEY, // Your OpenAI API key
+  },
+});
+
+// Convert text to speech
+const audioStream = await voice.speak("Hello! How can I assist you today?", {
+  speaker: "default", // Optional: specify a speaker
+});
+
+// Play the audio response
+playAudio(audioStream);
+```
+
+## Example of Using Multiple Voice Providers
+This example demonstrates how to create and use two different voice providers in Mastra: OpenAI for speech-to-text (STT) and PlayAI for text-to-speech (TTS).
+
+Start by creating instances of the voice providers with any necessary configuration.
+
+```typescript
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+import { CompositeVoice } from "@mastra/core/voice";
+
+// Initialize OpenAI voice for STT
+const listeningProvider = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
+
+// Initialize PlayAI voice for TTS
+const speakingProvider = new PlayAIVoice({
+  speechModel: {
+    name: "playai-voice",
+    apiKey: process.env.PLAYAI_API_KEY,
+  },
+});
+
+// Combine the providers using CompositeVoice
+const voice = new CompositeVoice({
+  listeningProvider,
+  speakingProvider,
+});
+
+// Implement voice interactions using the combined voice provider
+const audioStream = getMicrophoneStream(); // Assume this function gets audio input
+const transcript = await voice.listen(audioStream);
+
+// Log the transcribed text
+console.log("Transcribed text:", transcript);
+
+// Convert text to speech
+const responseAudio = await voice.speak(`You said: ${transcript}`, {
+  speaker: "default", // Optional: specify a speaker
+});
+
+// Play the audio response
+playAudio(responseAudio);
+```
+
+## Real-time Capabilities
+
+Many voice providers support real-time speech-to-speech interactions through WebSocket connections, enabling:
+
+- Live voice conversations with AI
+- Streaming transcription
+- Real-time text-to-speech synthesis
+- Tool usage during conversations
+
+
+## Voice Configuration
+
+Voice providers can be configured with different models and options:
+
+```typescript
+const voice = new OpenAIVoice({
+  speechModel: {
+    name: "tts-1-hd",
+    apiKey: process.env.OPENAI_API_KEY
+  },
+  listeningModel: {
+    name: "whisper-1"
+  },
+  speaker: "alloy"
+});
+```
+
+## Available Voice Providers
+
+Mastra supports a variety of voice providers, including:
+
+- OpenAI
+- PlayAI
+- Murf
+- ElevenLabs
+- [More](https://github.com/mastra-ai/mastra/tree/main/voice)
+
+## More Resources
+
+- [CompositeVoice](../reference/voice/composite-voice.mdx)
+- [MastraVoice](../reference/voice/mastra-voice.mdx)
+- [OpenAI Voice](../reference/voice/openai.mdx)
+- [PlayAI Voice](../reference/voice/playai.mdx)
+- [Voice Examples](../../examples/voice/)