@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/workflows/workflow-methods/map.md

@@ -0,0 +1,93 @@
+# Workflow\.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage example
+
+```typescript
+workflow.map(async ({ inputData }) => `${inputData.value} - map`)
+```
+
+## Parameters
+
+**mappingFunction:** (`(params: { inputData: any }) => any`): Function that transforms input data and returns the mapped result
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Using `inputData`
+
+Use `inputData` to access the full output of the previous step.
+
+```typescript
+.then(step1)
+  .map(({ inputData }) => {
+    console.log(inputData);
+  })
+```
+
+## Using `getStepResult()`
+
+Use `getStepResult()` to access the full output of a specific step by referencing the step's instance.
+
+```typescript
+.then(step1)
+  .map(async ({ getStepResult }) => {
+    console.log(getStepResult(step1));
+  })
+```
+
+## Using `getInitData()`
+
+Use `getInitData<typeof workflow>()` to access the initial input data provided to the workflow.
+
+```typescript
+.then(step1)
+  .map(async ({ getInitData }) => {
+    console.log(getInitData<any>());
+  })
+```
+
+## Using `mapVariable()`
+
+The object form of `.map()` provides an alternative declarative syntax for mapping fields. Instead of writing a function, you define an object where each key is a new field name and each value uses `mapVariable()` to extract data from previous steps or workflow input. Import `mapVariable()` from the workflows module:
+
+```typescript
+import { mapVariable } from '@mastra/core/workflows'
+```
+
+### Extracting fields from step outputs
+
+Use `mapVariable()` with `step` to extract a specific field from a step's output and map it to a new field name. The `path` parameter specifies which field to extract. In this example, the `value` field from `step1`'s output is extracted and mapped to a new field called `details`:
+
+```typescript
+.then(step1)
+  .map({
+    details: mapVariable({
+      step: step1,
+      path: "value"
+    })
+  })
+```
+
+### Extracting fields from workflow input
+
+Use `mapVariable()` with `initData` to extract a specific field from the workflow's initial input data. This is useful when you need to pass the original workflow input to a later step. In this example, the `value` field from the workflow's input is extracted and mapped to a field called `details`:
+
+```typescript
+export const testWorkflow = createWorkflow({...});
+
+testWorkflow
+  .then(step1)
+  .map({
+    details: mapVariable({
+      initData: testWorkflow,
+      path: "value"
+    })
+  })
+```
+
+## Related
+
+- [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow)

package/.docs/reference/workflows/workflow-methods/parallel.md

@@ -0,0 +1,21 @@
+# Workflow\.parallel()
+
+The `.parallel()` method executes multiple steps in parallel.
+
+## Usage example
+
+```typescript
+workflow.parallel([step1, step2])
+```
+
+## Parameters
+
+**steps:** (`Step[]`): The step instances to execute in parallel
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Related
+
+- [Simultaneous steps with parallel](https://mastra.ai/docs/workflows/control-flow)

package/.docs/reference/workflows/workflow-methods/sleep.md

@@ -0,0 +1,35 @@
+# Workflow\.sleep()
+
+The `.sleep()` method pauses execution for a specified number of milliseconds. It accepts either a static number or a callback function for dynamic delays.
+
+## Usage example
+
+```typescript
+workflow.sleep(5000)
+```
+
+## Parameters
+
+**milliseconds:** (`number | ((context: { inputData: any }) => number | Promise<number>)`): The number of milliseconds to pause execution, or a callback that returns the delay
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Extended usage example
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleep(async ({ inputData }) => {
+    const { delayInMs } = inputData;
+    return delayInMs;
+  })
+  .then(step2)
+  .commit();
+```

package/.docs/reference/workflows/workflow-methods/sleepUntil.md

@@ -0,0 +1,35 @@
+# Workflow\.sleepUntil()
+
+The `.sleepUntil()` method pauses execution until a specified date.
+
+## Usage example
+
+```typescript
+workflow.sleepUntil(new Date(Date.now() + 5000))
+```
+
+## Parameters
+
+**dateOrCallback:** (`Date | ((params: ExecuteFunctionParams) => Promise<Date>)`): Either a Date object or a callback function that returns a Date. The callback receives execution context and can compute the target time dynamically based on input data.
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Extended usage example
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleepUntil(async ({ inputData }) => {
+    const { delayInMs } = inputData;
+    return new Date(Date.now() + delayInMs);
+  })
+  .then(step2)
+  .commit();
+```

package/.docs/reference/workflows/workflow-methods/then.md

@@ -0,0 +1,21 @@
+# Workflow\.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage example
+
+```typescript
+workflow.then(step1).then(step2)
+```
+
+## Parameters
+
+**step:** (`Step`): The step instance that should execute after the previous step completes
+
+## Returns
+
+**workflow:** (`NewWorkflow`): The workflow instance for method chaining
+
+## Related
+
+- [Control flow](https://mastra.ai/docs/workflows/control-flow)

package/.docs/reference/workflows/workflow.md

@@ -0,0 +1,157 @@
+# Workflow Class
+
+The `Workflow` class enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+
+## Usage example
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+export const workflow = createWorkflow({
+  id: 'test-workflow',
+  inputSchema: z.object({
+    value: z.string(),
+  }),
+  outputSchema: z.object({
+    value: z.string(),
+  }),
+})
+```
+
+## Constructor parameters
+
+**id:** (`string`): Unique identifier for the workflow
+
+**inputSchema:** (`z.ZodType<any>`): Zod schema defining the input structure for the workflow
+
+**outputSchema:** (`z.ZodType<any>`): Zod schema defining the output structure for the workflow
+
+**stateSchema?:** (`z.ZodObject<any>`): Optional Zod schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.
+
+**requestContextSchema?:** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of run.start(), throwing an error if validation fails.
+
+**options?:** (`WorkflowOptions`): Optional options for the workflow
+
+### WorkflowOptions
+
+**tracingPolicy?:** (`TracingPolicy`): Optional tracing policy for the workflow
+
+**validateInputs?:** (`boolean`): Optional flag to determine whether to validate the workflow inputs. This also applies default values from zodSchemas on the workflow/step input/resume data. If input/resume data validation fails on start/resume, the workflow will not start/resume, it throws an error instead. If input data validation fails on a step execution, the step fails, causing the workflow to fail and the error is returned. (Default: `true`)
+
+**shouldPersistSnapshot?:** (`(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean`): Optional flag to determine whether to persist the workflow snapshot (Default: `() => true`)
+
+**onFinish?:** (`(result: WorkflowFinishCallbackResult) => void | Promise<void>`): Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.
+
+**onError?:** (`(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>`): Callback invoked only when workflow fails (failed or tripwire status). Receives error details and step results. Errors thrown in this callback are caught and logged, not propagated.
+
+### WorkflowFinishCallbackResult
+
+The result object passed to `onFinish` callbacks.
+
+**status:** (`WorkflowRunStatus`): The workflow status: 'success', 'failed', 'suspended', or 'tripwire'
+
+**result?:** (`any`): The workflow output (when status is 'success')
+
+**error?:** (`SerializedError`): Error details (when status is 'failed')
+
+**steps:** (`Record<string, StepResult>`): Individual step results with their status and output
+
+**tripwire?:** (`StepTripwireInfo`): Tripwire information (when status is 'tripwire')
+
+**runId:** (`string`): The unique identifier for this workflow run
+
+**workflowId:** (`string`): The workflow's identifier
+
+**resourceId?:** (`string`): Optional resource identifier (if provided when creating the run)
+
+**getInitData:** (`() => any`): Function that returns the initial input data passed to the workflow
+
+**mastra?:** (`Mastra`): The Mastra instance (if workflow is registered with Mastra)
+
+**requestContext:** (`RequestContext`): Request-scoped context data
+
+**logger:** (`IMastraLogger`): The workflow's logger instance
+
+**state:** (`Record<string, any>`): The workflow's current state object
+
+### WorkflowErrorCallbackInfo
+
+The error info object passed to `onError` callbacks.
+
+**status:** (`'failed' | 'tripwire'`): The workflow status (either 'failed' or 'tripwire')
+
+**error?:** (`SerializedError`): Error details
+
+**steps:** (`Record<string, StepResult>`): Individual step results with their status and output
+
+**tripwire?:** (`StepTripwireInfo`): Tripwire information (when status is 'tripwire')
+
+**runId:** (`string`): The unique identifier for this workflow run
+
+**workflowId:** (`string`): The workflow's identifier
+
+**resourceId?:** (`string`): Optional resource identifier (if provided when creating the run)
+
+**getInitData:** (`() => any`): Function that returns the initial input data passed to the workflow
+
+**mastra?:** (`Mastra`): The Mastra instance (if workflow is registered with Mastra)
+
+**requestContext:** (`RequestContext`): Request-scoped context data
+
+**logger:** (`IMastraLogger`): The workflow's logger instance
+
+**state:** (`Record<string, any>`): The workflow's current state object
+
+## Running with initial state
+
+When starting a workflow run, you can pass `initialState` to set the starting values for the workflow's state:
+
+```typescript
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: { value: 'hello' },
+  initialState: {
+    counter: 0,
+    items: [],
+  },
+})
+```
+
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for more details.
+
+## Workflow status
+
+A workflow's `status` indicates its current execution state. The possible values are:
+
+**success:** (`string`): All steps finished executing successfully, with a valid result output
+
+**failed:** (`string`): Workflow encountered an error during execution, with error details available
+
+**suspended:** (`string`): Workflow execution is paused waiting for resume, with suspended step information
+
+**tripwire:** (`string`): Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.
+
+### Handling tripwire status
+
+When a workflow contains an agent step that triggers a tripwire, the workflow returns with `status: 'tripwire'` and includes tripwire details:
+
+```typescript
+const run = await workflow.createRun()
+const result = await run.start({ inputData: { message: 'Hello' } })
+
+if (result.status === 'tripwire') {
+  console.log('Workflow terminated by tripwire:', result.tripwire?.reason)
+  console.log('Processor ID:', result.tripwire?.processorId)
+  console.log('Retry requested:', result.tripwire?.retry)
+}
+```
+
+This is distinct from `status: 'failed'` which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).
+
+## Related
+
+- [Step Class](https://mastra.ai/reference/workflows/step)
+- [Workflow State](https://mastra.ai/docs/workflows/workflow-state)
+- [Control flow](https://mastra.ai/docs/workflows/control-flow)

package/.docs/reference/workspace/e2b-sandbox.md

@@ -0,0 +1,289 @@
+# E2BSandbox
+
+Executes commands in isolated [E2B](https://e2b.dev) cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+```bash
+npm install @mastra/e2b
+```
+
+## Usage
+
+Add an `E2BSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    timeout: 60_000, // 60 second timeout (default: 5 minutes)
+  }),
+})
+
+const agent = new Agent({
+  name: 'dev-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+})
+```
+
+## Constructor parameters
+
+**apiKey?:** (`string`): E2B API key. Falls back to E2B\_API\_KEY environment variable.
+
+**timeout?:** (`number`): Execution timeout in milliseconds (Default: `300000 (5 minutes)`)
+
+**template?:** (`string | TemplateBuilder | function`): Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.
+
+**env?:** (`Record<string, string>`): Environment variables to set in the sandbox
+
+**id?:** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
+
+**domain?:** (`string`): Domain for self-hosted E2B. Falls back to E2B\_DOMAIN env var.
+
+**apiUrl?:** (`string`): API URL for self-hosted E2B. Falls back to E2B\_API\_URL env var.
+
+**accessToken?:** (`string`): Access token for authentication. Falls back to E2B\_ACCESS\_TOKEN env var.
+
+## Properties
+
+**id:** (`string`): Sandbox instance identifier
+
+**name:** (`string`): Provider name ('E2BSandbox')
+
+**provider:** (`string`): Provider identifier ('e2b')
+
+**status:** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'error'
+
+**supportsMounting:** (`boolean`): Always true - E2B sandboxes support mounting cloud filesystems
+
+## Methods
+
+### `start()`
+
+Initialize and start the sandbox. Creates the E2B sandbox instance and mounts any configured filesystems.
+
+```typescript
+await sandbox.start()
+```
+
+Called automatically on first command execution or by `workspace.init()`.
+
+### `stop()`
+
+Stop the sandbox and release resources.
+
+```typescript
+await sandbox.stop()
+```
+
+### `destroy()`
+
+Clean up sandbox resources completely.
+
+```typescript
+await sandbox.destroy()
+```
+
+### `executeCommand(command, args?, options?)`
+
+Execute a shell command in the sandbox.
+
+```typescript
+const result = await sandbox.executeCommand('ls', ['-la'])
+const npmResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
+  timeout: 60000,
+  cwd: '/app',
+})
+```
+
+**Parameters:**
+
+**command:** (`string`): Command to execute
+
+**args?:** (`string[]`): Command arguments
+
+**options.timeout?:** (`number`): Execution timeout in milliseconds
+
+**options.cwd?:** (`string`): Working directory for the command
+
+**options.env?:** (`Record<string, string>`): Additional environment variables
+
+**options.onStdout?:** (`(data: string) => void`): Callback for stdout streaming
+
+**options.onStderr?:** (`(data: string) => void`): Callback for stderr streaming
+
+### `canMount(filesystem)`
+
+Check if a filesystem can be mounted into this sandbox.
+
+```typescript
+const canMount = sandbox.canMount(s3Filesystem)
+// true for S3Filesystem and GCSFilesystem
+```
+
+### `mount(filesystem, mountPath)`
+
+Mount a filesystem into the sandbox at the specified path.
+
+```typescript
+await sandbox.mount(s3Filesystem, '/mnt/data')
+```
+
+### `unmount(mountPath)`
+
+Unmount a previously mounted filesystem.
+
+```typescript
+await sandbox.unmount('/mnt/data')
+```
+
+### `getInfo()`
+
+Get sandbox status and resource information.
+
+```typescript
+const info = await sandbox.getInfo()
+// { id: '...', name: 'E2BSandbox', provider: 'e2b', status: 'ready', supportsMounting: true }
+```
+
+## Mounting Cloud Storage
+
+E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:
+
+- Processing large datasets stored in cloud buckets
+- Writing output files directly to cloud storage
+- Sharing data between sandbox sessions
+
+### Using the mounts config
+
+The simplest way to mount filesystems is through the workspace `mounts` config:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+import { GCSFilesystem } from '@mastra/gcs'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  mounts: {
+    '/s3-data': new S3Filesystem({
+      bucket: 'my-s3-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+    '/gcs-data': new GCSFilesystem({
+      bucket: 'my-gcs-bucket',
+      projectId: 'my-project',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+When the sandbox starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at `/s3-data` and `/gcs-data` as if they were local directories.
+
+### How mounting works
+
+E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
+
+- **S3/R2**: Mounted via [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
+- **GCS**: Mounted via [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)
+
+The E2B sandbox automatically installs the required FUSE tools when mounting is used. For best performance, pre-build a custom template with the tools installed.
+
+## Custom Templates
+
+By default, when no template is specified, E2BSandbox automatically builds a template with `s3fs` installed for S3 mounting support. This template is cached and reused across sandbox instances.
+
+For GCS mounting, `gcsfuse` is automatically installed at mount time if not already present. For additional tools or faster cold starts, use custom templates.
+
+### Using an existing template
+
+If you have a pre-built template, pass its ID:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    template: 'my-custom-template',
+  }),
+})
+```
+
+### Customizing the default template
+
+Pass a function to customize the default mountable template. The function receives a `TemplateBuilder` and should return the modified template:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    template: base =>
+      base
+        .aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
+        .pipInstall(['pandas', 'numpy'])
+        .npmInstall(['sharp']),
+  }),
+})
+```
+
+The template builder supports method chaining with operations like:
+
+- `aptInstall(packages)` - Install system packages
+- `pipInstall(packages)` - Install Python packages
+- `npmInstall(packages)` - Install Node.js packages
+- `runCmd(command)` - Run shell commands
+- `setEnvs(vars)` - Set environment variables
+- `copy(src, dest)` - Copy files into the template
+
+See [E2B's template documentation](https://e2b.dev/docs/template/defining-template) for the full list of available methods.
+
+### Pre-building templates
+
+The default template is built on first use and cached. For faster cold starts or to include GCS support, you can pre-build a template:
+
+```typescript
+import { createDefaultMountableTemplate } from '@mastra/e2b'
+import { Template } from 'e2b'
+
+// Get the default mountable template (includes s3fs)
+const { template, id } = createDefaultMountableTemplate()
+
+// Build and save to E2B
+const result = await Template.build(template, id)
+console.log('Template ID:', result.templateId)
+
+// Use this ID in your E2BSandbox config for instant startup
+const sandbox = new E2BSandbox({
+  template: result.templateId,
+})
+```
+
+For faster GCS cold starts, pre-install `gcsfuse` in a custom template:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    template: base => base.aptInstall(['gcsfuse']),
+  }),
+})
+```
+
+This is optional—`gcsfuse` is installed automatically at mount time if not present.
+
+## Related
+
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)