@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/storage/overview.mdx

@@ -0,0 +1,378 @@
+---
+title: Storage in Mastra | Mastra Docs
+description: Overview of Mastra's storage system and data persistence capabilities.
+---
+
+import { Tabs } from "nextra/components";
+
+import { PropertiesTable } from "@/components/properties-table";
+import { SchemaTable } from "@/components/schema-table";
+import { StorageOverviewImage } from "@/components/storage-overview-image";
+
+# MastraStorage
+
+`MastraStorage` provides a unified interface for managing:
+
+- **Suspended Workflows**: the serialized state of suspended workflows (so they can be resumed later)
+- **Memory**: threads and messages per `resourceId` in your application
+- **Traces**: OpenTelemetry traces from all components of Mastra
+- **Eval Datasets**: scores and scoring reasons from eval runs
+
+<br />
+
+<br />
+
+<StorageOverviewImage />
+
+Mastra provides different storage providers, but you can treat them as interchangeable. Eg, you could use libsql in development but postgres in production, and your code will work the same both ways.
+
+## Configuration
+
+Mastra can be configured with a default storage option:
+
+```typescript copy
+import { Mastra } from "@mastra/core/mastra";
+import { DefaultStorage } from "@mastra/core/storage/libsql";
+
+const mastra = new Mastra({
+  storage: new DefaultStorage({
+    config: {
+      url: "file:.mastra/mastra.db",
+    },
+  }),
+});
+```
+
+## Data Schema
+
+<Tabs items={['Messages', 'Threads', 'Workflows', 'Eval Datasets', 'Traces']}>
+  <Tabs.Tab>
+Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "id",
+      type: "uuidv4",
+      description: "Unique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)",
+      constraints: [
+        { type: "primaryKey" },
+        { type: "nullable", value: false }
+      ]
+    },
+    {
+      name: "thread_id",
+      type: "uuidv4",
+      description: "Parent thread reference",
+      constraints: [
+        { type: "foreignKey", value: "threads.id" },
+        { type: "nullable", value: false }
+      ]
+    },
+    {
+      name: "content",
+      type: "text",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "role",
+      type: "text",
+      description: "Enum of `system | user | assistant | tool`",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "type",
+      type: "text",
+      description: "Enum of `text | tool-call | tool-result`",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      description: "Used for thread message ordering",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+  </Tabs.Tab>
+  <Tabs.Tab>
+Groups related messages together and associates them with a resource. Contains metadata about the conversation.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "id",
+      type: "uuidv4",
+      description: "Unique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)",
+      constraints: [
+        { type: "primaryKey" },
+        { type: "nullable", value: false }
+      ]
+    },
+    {
+      name: "resourceId",
+      type: "text",
+      description: "Primary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "title",
+      type: "text",
+      description: "Title of the conversation thread",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "metadata",
+      type: "text",
+      description: "Custom thread metadata as stringified JSON. Example:",
+      example: {
+        category: "support",
+        priority: 1
+      }
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "updatedAt",
+      type: "timestamp",
+      description: "Used for thread ordering history",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+  </Tabs.Tab>
+  <Tabs.Tab>
+When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "workflow_name",
+      type: "text",
+      description: "Name of the workflow",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "run_id",
+      type: "uuidv4",
+      description: "Unique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "snapshot",
+      type: "text",
+      description: "Serialized workflow state as JSON. Example:",
+      example: {
+        value: { currentState: 'running' },
+        context: {
+          stepResults: {},
+          attempts: {},
+          triggerData: {}
+        },
+        activePaths: [],
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+        timestamp: 1648176000000
+      },
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "updatedAt",
+      type: "timestamp",
+      description: "Last modification time, used to track state changes during workflow execution",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+  </Tabs.Tab>
+  <Tabs.Tab>
+Stores eval results from running metrics against agent outputs.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "input",
+      type: "text",
+      description: "Input provided to the agent",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "output",
+      type: "text",
+      description: "Output generated by the agent",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "result",
+      type: "jsonb",
+      description: "Eval result data that includes score and details. Example:",
+      example: {
+        score: 0.95,
+        details: {
+          reason: "Response accurately reflects source material",
+          citations: ["page 1", "page 3"]
+        }
+      },
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "agent_name",
+      type: "text",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "metric_name",
+      type: "text",
+      description: "e.g Faithfulness, Hallucination, etc.",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "instructions",
+      type: "text",
+      description: "System prompt or instructions for the agent",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "test_info",
+      type: "jsonb",
+      description: "Additional test metadata and configuration",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "global_run_id",
+      type: "uuidv4",
+      description: "Groups related evaluation runs (e.g. all unit tests in a CI run)",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "run_id",
+      type: "uuidv4",
+      description: "Unique identifier for the run being evaluated (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "created_at",
+      type: "timestamp",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+  </Tabs.Tab>
+  <Tabs.Tab>
+Captures OpenTelemetry traces for monitoring and debugging.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "id",
+      type: "text",
+      description: "Unique trace identifier",
+      constraints: [
+        { type: "nullable", value: false },
+        { type: "primaryKey" }
+      ]
+    },
+    {
+      name: "parentSpanId",
+      type: "text",
+      description: "ID of the parent span. Null if span is top level",
+    },
+    {
+      name: "name",
+      type: "text",
+      description: "Hierarchical operation name (e.g. `workflow.myWorkflow.execute`, `http.request`, `database.query`)",
+      constraints: [{ type: "nullable", value: false }],
+    },
+    {
+      name: "traceId",
+      type: "text",
+      description: "Root trace identifier that groups related spans",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "scope",
+      type: "text",
+      description: "Library/package/service that created the span (e.g. `@mastra/core`, `express`, `pg`)",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "kind",
+      type: "integer",
+      description: "`INTERNAL` (0, within process), `CLIENT` (1, outgoing calls), `SERVER` (2, incoming calls), `PRODUCER` (3, async job creation), `CONSUMER` (4, async job processing)",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "attributes",
+      type: "jsonb",
+      description: "User defined key-value pairs that contain span metadata",
+    },
+    {
+      name: "status",
+      type: "jsonb",
+      description: "JSON object with `code` (UNSET=0, ERROR=1, OK=2) and optional `message`. Example:",
+      example: {
+        code: 1,
+        message: "HTTP request failed with status 500"
+      }
+    },
+    {
+      name: "events",
+      type: "jsonb",
+      description: "Time-stamped events that occurred during the span",
+    },
+    {
+      name: "links",
+      type: "jsonb",
+      description: "Links to other related spans",
+      },
+    {
+      name: "other",
+      type: "text",
+      description: "Additional OpenTelemetry span fields as stringified JSON. Example:",
+      example: {
+        droppedAttributesCount: 2,
+        droppedEventsCount: 1,
+        instrumentationLibrary: "@opentelemetry/instrumentation-http"
+      }
+    },
+    {
+      name: "startTime",
+      type: "bigint",
+      description: "Nanoseconds since Unix epoch when span started",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "endTime",
+      type: "bigint",
+      description: "Nanoseconds since Unix epoch when span ended",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+  </Tabs.Tab>
+</Tabs>
+
+## Storage Providers
+
+Mastra supports the following providers:
+
+- For local development, check out [LibSQL Storage](../../reference/storage/libsql.mdx)
+- For production, check out [PostgreSQL Storage](../../reference/storage/postgresql.mdx)
+- For serverless deployments, check out [Upstash Storage](../../reference/storage/upstash.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/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 input = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
+
+// Initialize PlayAI voice for TTS
+const output = new PlayAIVoice({
+  speechModel: {
+    name: "playai-voice",
+    apiKey: process.env.PLAYAI_API_KEY,
+  },
+});
+
+// Combine the providers using CompositeVoice
+const voice = new CompositeVoice({
+  input,
+  output,
+});
+
+// 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/text-to-speech.mdx)

package/.docs/raw/voice/speech-to-text.mdx

@@ -0,0 +1,45 @@
+---
+title: Speech-to-Text (STT) in Mastra | Mastra Docs
+description: Overview of Speech-to-Text capabilities in Mastra, including configuration, usage, and integration with voice providers.
+---
+
+# Speech-to-Text (STT)
+
+Speech-to-Text (STT) in Mastra provides a standardized interface for converting audio input into text across multiple service providers. This section covers STT configuration and usage. Check out the [Adding Voice to Agents](../agents/adding-voice.mdx) documentation to learn how to use STT in an agent.
+
+## Speech Configuration
+
+To use STT in Mastra, you need to provide a `listeningModel` configuration when initializing the voice provider. This configuration includes parameters such as:
+
+- **`name`**: The specific STT model to use.
+- **`apiKey`**: Your API key for authentication.
+- **Provider-specific options**: Additional options that may be required or supported by the specific voice provider.
+
+**Note**: All of these parameters are optional. You can use the default settings provided by the voice provider, which will depend on the specific provider you are using.
+
+### Example Configuration
+
+```typescript
+const voice = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
+
+// If using default settings the configuration can be simplified to:
+const voice = new OpenAIVoice();
+```
+
+## Using the Listen Method
+
+The primary method for STT is the `listen()` method, which converts spoken audio into text. Here's how to use it:
+
+```typescript
+const audioStream = getMicrophoneStream(); // Assume this function gets audio input
+const transcript = await voice.listen(audioStream, {
+  filetype: "m4a", // Optional: specify the audio file type
+});
+```
+
+**Note**: If you are using a voice-to-voice provider, such as `OpenAIRealtimeVoice`, the `listen()` method will emit a "writing" event instead of returning a transcript directly.

package/.docs/raw/voice/text-to-speech.mdx

@@ -0,0 +1,52 @@
+---
+title: Text-to-Speech (TTS) in Mastra | Mastra Docs
+description: Overview of Text-to-Speech capabilities in Mastra, including configuration, usage, and integration with voice providers.
+---
+
+# Text-to-Speech (TTS)
+
+Text-to-Speech (TTS) in Mastra offers a unified API for synthesizing spoken audio from text using various provider services. This section explains TTS configuration options and implementation methods. For integrating TTS capabilities with agents, refer to the [Adding Voice to Agents](../agents/adding-voice.mdx) documentation.
+
+## Speech Configuration
+
+To use TTS in Mastra, you need to provide a `speechModel` configuration when initializing the voice provider. This configuration includes parameters such as:
+
+- **`name`**: The specific TTS model to use.
+- **`apiKey`**: Your API key for authentication.
+- **Provider-specific options**: Additional options that may be required or supported by the specific voice provider.
+
+The **`speaker`** option is specified separately and allows you to select different voices for speech synthesis.
+
+**Note**: All of these parameters are optional. You can use the default settings provided by the voice provider, which will depend on the specific provider you are using.
+
+### Example Configuration
+
+```typescript
+const voice = new OpenAIVoice({
+  speechModel: {
+    name: "tts-1-hd",
+    apiKey: process.env.OPENAI_API_KEY
+  },
+  speaker: "alloy",
+});
+
+// If using default settings the configuration can be simplified to:
+const voice = new OpenAIVoice();
+```
+
+## Using the Speak Method
+
+The primary method for TTS is the `speak()` method, which converts text to speech. This method can accept options that allows you to specify the speaker and other provider-specific options. Here's how to use it:
+
+```typescript
+const readableStream = await voice.speak("Hello, world!", {
+  speaker: "default", // Optional: specify a speaker
+  properties: {
+    speed: 1.0, // Optional: adjust speech speed
+    pitch: "default", // Optional: specify pitch if supported
+  },
+});
+```
+
+**Note**: If you are using a voice-to-voice provider, such as `OpenAIRealtimeVoice`, the `speak()` method will emit a "speaking" event instead of returning an Readable Stream.
+