@mastra/mcp-docs-server 1.0.0-beta.14 → 1.0.0-beta.16

package/.docs/raw/guides/deployment/inngest.mdx

@@ -3,17 +3,17 @@ title: "Inngest | Deployment"
 description: "Deploy Mastra workflows with Inngest"
 ---
 
-# Inngest Workflow
+# Inngest workflow
 
 [Inngest](https://www.inngest.com/docs) is a developer platform for building and running background workflows, without managing infrastructure.
 
 For a complete example with advanced flow control features, see the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest).
 
-## How Inngest Works with Mastra
+## How Inngest works with Mastra
 
-Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow` and `createStep` map directly onto this paradigm. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
+Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow()` and `createStep()` map directly onto this paradigm. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
 
-The `serve` function bridges the two systems by registering Mastra workflows as Inngest functions and setting up the necessary event handlers for execution and monitoring.
+The `serve()` function bridges the two systems by registering Mastra workflows as Inngest functions and setting up the necessary event handlers for execution and monitoring.
 
 When an event triggers a workflow, Inngest executes it step by step, memoizing each step's result. This means if a workflow is retried or resumed, completed steps are skipped, ensuring efficient and reliable execution. Control flow primitives in Mastra, such as loops, conditionals, and nested workflows are seamlessly translated into the same Inngest's function/step model, preserving advanced workflow features like composition, branching, and suspension.
 
@@ -21,19 +21,19 @@ Real-time monitoring, suspend/resume, and step-level observability are enabled v
 
 ## Setup
 
-Install the required Inngest package:
+Install the required packages:
 
 ```sh
-npm install @mastra/inngest@beta
+npm install @mastra/inngest@beta inngest @inngest/realtime
 ```
 
-## Building an Inngest Workflow
+## Building an Inngest workflow
 
 This guide walks through creating a workflow with Inngest and Mastra, demonstrating a counter application that increments a value until it reaches 10.
 
-### Inngest Initialization
+### Inngest initialization
 
-Initialize the Inngest integration to obtain Mastra-compatible workflow helpers. The createWorkflow and createStep functions are used to create workflow and step objects that are compatible with Mastra and inngest.
+Initialize the Inngest integration to obtain Mastra-compatible workflow helpers. The `createWorkflow()` and `createStep()` functions are used to create workflow and step objects that are compatible with Mastra and inngest.
 
 In development:
 
@@ -61,7 +61,7 @@ export const inngest = new Inngest({
 });
 ```
 
-### Creating Steps
+### Creating steps
 
 Define the individual steps that will compose your workflow:
 
@@ -88,9 +88,9 @@ const incrementStep = createStep({
 });
 ```
 
-### Creating the Workflow
+### Creating the workflow
 
-Compose the steps into a workflow using the `dountil` loop pattern. The createWorkflow function creates a function on inngest server that is invocable.
+Compose the steps into a workflow using the `dountil` loop pattern. The `createWorkflow()` function creates a function on Inngest server that is invocable.
 
 ```ts title="src/mastra/workflows/index.ts"
 // workflow that is registered as a function on inngest server
@@ -109,95 +109,53 @@ workflow.commit();
 export { workflow as incrementWorkflow };
 ```
 
-### Configuring the Mastra Instance and Executing the Workflow
+### Configuring the Mastra instance
 
 Register the workflow with Mastra and configure the Inngest API endpoint:
 
 ```ts title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
-import { serve as inngestServe } from "@mastra/inngest";
+import { serve } from "@mastra/inngest";
 import { incrementWorkflow } from "./workflows";
 import { inngest } from "./inngest";
 import { PinoLogger } from "@mastra/loggers";
 
-// Configure Mastra with the workflow and Inngest API endpoint
 export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
+  workflows: { incrementWorkflow },
   server: {
-    // The server configuration is required to allow local docker container can connect to the mastra server
     host: "0.0.0.0",
     apiRoutes: [
-      // This API route is used to register the Mastra workflow (inngest function) on the inngest server
       {
         path: "/api/inngest",
         method: "ALL",
-        createHandler: async ({ mastra }) => inngestServe({ mastra, inngest }),
-        // The inngestServe function integrates Mastra workflows with Inngest by:
-        // 1. Creating Inngest functions for each workflow with unique IDs (workflow.${workflowId})
-        // 2. Setting up event handlers that:
-        //    - Generate unique run IDs for each workflow execution
-        //    - Create an InngestExecutionEngine to manage step execution
-        //    - Handle workflow state persistence and real-time updates
-        // 3. Establishing a publish-subscribe system for real-time monitoring
-        //    through the workflow:${workflowId}:${runId} channel
-        //
-        // Optional: You can also pass additional Inngest functions to serve alongside workflows:
-        // createHandler: async ({ mastra }) => inngestServe({
-        //   mastra,
-        //   inngest,
-        //   functions: [customFunction1, customFunction2] // User-defined Inngest functions
-        // }),
+        createHandler: async ({ mastra }) => {
+          return serve({ mastra, inngest });
+        },
       },
     ],
   },
-  logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
-  }),
+  logger: new PinoLogger({ name: "Mastra", level: "info" }),
 });
 ```
 
-### Running the Workflow locally
-
-:::info[Prerequisites]
+## Running workflows
 
-- Docker installed and running
-- Mastra project set up
-- Dependencies installed (`npm install`)
+### Running locally
 
-:::
-
-1. Run `npx mastra dev` to start the Mastra server on local to serve the server on port 4111.
-2. Start the Inngest Dev Server (via Docker)
-   In a new terminal, run:
+1. Run `npx mastra dev` to start the Mastra server locally on port 4111
+2. Start the Inngest Dev Server. In a new terminal, run:
 
     ```sh
-    docker run --rm -p 8288:8288 \
-      inngest/inngest \
-      inngest dev -u http://host.docker.internal:4111/api/inngest
+    npx inngest-cli@latest dev -u http://localhost:4111/api/inngest
     ```
 
     :::note
-
-    The URL after `-u` tells the Inngest dev server where to find your Mastra `/api/inngest` endpoint.
-
+    The URL after `-u` tells the Inngest dev server where to find your Mastra `/api/inngest` endpoint
     :::
 
-3. Open the Inngest Dashboard
+3. Open the Inngest Dashboard at [http://localhost:8288](http://localhost:8288) and go to the **Apps** section in the sidebar to verify your Mastra workflow is registered
 
-    - Visit [http://localhost:8288](http://localhost:8288) in your browser.
-    - Go to the **Apps** section in the sidebar.
-    - You should see your Mastra workflow registered.
-
-    ![Inngest Dashboard](/img/inngest-apps-dashboard.png)
-
-4. Invoke the Workflow
-
-    - Go to the **Functions** section in the sidebar.
-    - Select your Mastra workflow.
-    - Click **Invoke** and use the following input:
+4. Invoke the workflow by going to **Functions**, selecting your workflow, and clicking **Invoke** with the following input:
 
     ```json
     {
@@ -209,26 +167,24 @@ export const mastra = new Mastra({
     }
     ```
 
-    ![Inngest Function](/img/inngest-function-dashboard.png)
-
-5. **Monitor the Workflow Execution**
-
-    - Go to the **Runs** tab in the sidebar.
-    - Click on the latest run to see step-by-step execution progress.
-
-    ![Inngest Function Run](/img/inngest-runs-dashboard.png)
+5. Monitor the workflow execution in the **Runs** tab to see step-by-step execution progress
 
-### Running the Workflow in Production
+### Running in production
 
-:::info[Prerequisites]
+Before you begin, make sure you have:
 
 - Vercel account and Vercel CLI installed (`npm i -g vercel`)
 - Inngest account
-- Vercel token (recommended: set as environment variable)
+- Vercel token
 
-:::
 
-1. Add Vercel Deployer to Mastra instance
+1. Set your Vercel token in your environment:
+
+    ```sh title=".env"
+    export VERCEL_TOKEN=your_vercel_token
+    ```
+
+2. Add `VercelDeployer` to Mastra instance
 
     ```ts title="src/mastra/index.ts"
     import { VercelDeployer } from "@mastra/deployer-vercel";
@@ -239,53 +195,29 @@ export const mastra = new Mastra({
         projectName: "your_project_name",
         // you can get your vercel token from the vercel dashboard by clicking on the user icon in the top right corner
         // and then clicking on "Account Settings" and then clicking on "Tokens" on the left sidebar.
-        token: "your_vercel_token",
+        token: process.env.VERCEL_TOKEN,
       }),
     });
     ```
 
-    :::note
-
-    Set your Vercel token in your environment:
-
-    ```sh
-    export VERCEL_TOKEN=your_vercel_token
-    ```
-
-    :::
 
-2. Build the mastra instance
+3. Build the mastra instance
 
     ```sh
     npx mastra build
     ```
 
-3. Deploy to Vercel
+4. Deploy to Vercel
 
     ```sh
     cd .mastra/output
+    vercel login
     vercel --prod
     ```
 
-    :::tip
-
-    If you haven't already, log in to Vercel CLI with `vercel login`.
-
-    :::
-
-4. Sync with Inngest Dashboard
-
-    - Go to the [Inngest dashboard](https://app.inngest.com/env/production/apps).
-    - Click **Sync new app with Vercel** and follow the instructions.
-    - You should see your Mastra workflow registered as an app.
+5. Sync with the [Inngest dashboard](https://app.inngest.com/env/production/apps) by clicking **Sync new app with Vercel** and following the instructions
 
-    ![Inngest Dashboard](/img/inngest-apps-dashboard-prod.png)
-
-5. Invoke the Workflow
-
-    - In the **Functions** section, select `workflow.increment-workflow`.
-    - Click **All actions** (top right) > **Invoke**.
-    - Provide the following input:
+6. Invoke the workflow by going to **Functions**, selecting `workflow.increment-workflow`, clicking **All actions** > **Invoke**, and providing the following input:
 
     ```json
     {
@@ -297,25 +229,18 @@ export const mastra = new Mastra({
     }
     ```
 
-    ![Inngest Function Run](/img/inngest-function-dashboard-prod.png)
-
-6.  Monitor Execution
+7. Monitor execution in the **Runs** tab to see step-by-step progress
 
-    - Go to the **Runs** tab.
-    - Click the latest run to see step-by-step execution progress.
+## Adding custom Inngest functions
 
-        ![Inngest Function Run](/img/inngest-runs-dashboard-prod.png)
+You can serve additional Inngest functions alongside your Mastra workflows by using the optional `functions` parameter in `serve()`.
 
-## Advanced Usage: Adding Custom Inngest Functions
-
-You can serve additional Inngest functions alongside your Mastra workflows by using the optional `functions` parameter in `inngestServe`.
-
-### Creating Custom Functions
+### Creating custom functions
 
 First, create your custom Inngest functions:
 
 ```ts title="src/inngest/custom-functions.ts"
-import { inngest } from "./inngest";
+import { inngest } from "../inngest";
 
 // Define custom Inngest functions
 export const customEmailFunction = inngest.createFunction(
@@ -339,48 +264,181 @@ export const customWebhookFunction = inngest.createFunction(
 );
 ```
 
-### Serving Custom Functions with Workflows
+### Serving custom functions with workflows
 
-Update your Mastra configuration to include the custom functions:
+Update your Mastra configuration to import and include the custom functions. The highlighted lines show the additions:
 
-```ts title="src/mastra/index.ts"
+```ts title="src/mastra/index.ts" {5-8,23}
 import { Mastra } from "@mastra/core";
-import { serve as inngestServe } from "@mastra/inngest";
+import { serve } from "@mastra/inngest";
 import { incrementWorkflow } from "./workflows";
 import { inngest } from "./inngest";
 import {
   customEmailFunction,
   customWebhookFunction,
 } from "./inngest/custom-functions";
+import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
+  workflows: { incrementWorkflow },
   server: {
     host: "0.0.0.0",
     apiRoutes: [
       {
         path: "/api/inngest",
         method: "ALL",
-        createHandler: async ({ mastra }) =>
-          inngestServe({
+        createHandler: async ({ mastra }) => {
+          return serve({
             mastra,
             inngest,
-            functions: [customEmailFunction, customWebhookFunction], // Add your custom functions
-          }),
+            functions: [customEmailFunction, customWebhookFunction],
+          });
+        },
       },
     ],
   },
+  logger: new PinoLogger({ name: "Mastra", level: "info" }),
 });
 ```
 
-### Function Registration
+### Function registration
 
 When you include custom functions:
 
-1. **Mastra workflows** are automatically converted to Inngest functions with IDs like `workflow.${workflowId}`
-2. **Custom functions** retain their specified IDs (e.g., `send-welcome-email`, `process-webhook`)
-3. **All functions** are served together on the same `/api/inngest` endpoint
+1. Mastra workflows are automatically converted to Inngest functions with IDs like `workflow.${workflowId}`
+2. Custom functions retain their specified IDs (e.g., `send-welcome-email`, `process-webhook`)
+3. All functions are served together on the same `/api/inngest` endpoint
+
+This allows you to combine Mastra's workflow orchestration with your existing Inngest functions.
+
+## Flow control
+
+Inngest workflows support flow control features including concurrency limits, rate limiting, throttling, debouncing, and priority queuing. These options are configured in the `createWorkflow()` call and help manage workflow execution at scale.
+
+### Concurrency
+
+Control how many workflow instances can run simultaneously:
+
+```ts
+const workflow = createWorkflow({
+  id: "user-processing-workflow",
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  steps: [processUserStep],
+  // Limit to 10 concurrent executions, scoped by user ID
+  concurrency: {
+    limit: 10,
+    key: "event.data.userId",
+  },
+});
+```
+
+### Rate limiting
+
+Limit the number of workflow executions within a time period:
+
+```ts
+const workflow = createWorkflow({
+  id: "api-sync-workflow",
+  inputSchema: z.object({ endpoint: z.string() }),
+  outputSchema: z.object({ status: z.string() }),
+  steps: [apiSyncStep],
+  // Maximum 1000 executions per hour
+  rateLimit: {
+    period: "1h",
+    limit: 1000,
+  },
+});
+```
+
+### Throttling
+
+Ensure minimum time between workflow executions:
+
+```ts
+const workflow = createWorkflow({
+  id: "email-notification-workflow",
+  inputSchema: z.object({ organizationId: z.string(), message: z.string() }),
+  outputSchema: z.object({ sent: z.boolean() }),
+  steps: [sendEmailStep],
+  // Only one execution per 10 seconds per organization
+  throttle: {
+    period: "10s",
+    limit: 1,
+    key: "event.data.organizationId",
+  },
+});
+```
+
+### Debouncing
+
+Delay execution until no new events arrive within a time window:
+
+```ts
+const workflow = createWorkflow({
+  id: "search-index-workflow",
+  inputSchema: z.object({ documentId: z.string() }),
+  outputSchema: z.object({ indexed: z.boolean() }),
+  steps: [indexDocumentStep],
+  // Wait 5 seconds of no updates before indexing
+  debounce: {
+    period: "5s",
+    key: "event.data.documentId",
+  },
+});
+```
+
+### Priority
+
+Set execution priority for workflows:
+
+```ts
+const workflow = createWorkflow({
+  id: "order-processing-workflow",
+  inputSchema: z.object({
+    orderId: z.string(),
+    priority: z.number().optional(),
+  }),
+  outputSchema: z.object({ processed: z.boolean() }),
+  steps: [processOrderStep],
+  // Higher priority orders execute first
+  priority: {
+    run: "event.data.priority ?? 50",
+  },
+});
+```
+
+### Combining flow control options
+
+Multiple flow control options can be combined in a single workflow:
+
+```ts
+const workflow = createWorkflow({
+  id: "comprehensive-workflow",
+  inputSchema: z.object({
+    userId: z.string(),
+    organizationId: z.string(),
+    priority: z.number().optional(),
+  }),
+  outputSchema: z.object({ result: z.string() }),
+  steps: [comprehensiveStep],
+  concurrency: {
+    limit: 5,
+    key: "event.data.userId",
+  },
+  rateLimit: {
+    period: "1m",
+    limit: 100,
+  },
+  throttle: {
+    period: "10s",
+    limit: 1,
+    key: "event.data.organizationId",
+  },
+  priority: {
+    run: "event.data.priority ?? 0",
+  },
+});
+```
 
-This allows you to combine Mastra's workflow orchestration with your existing Inngest functions seamlessly.
+All flow control options are optional. If not specified, workflows run with Inngest's default behavior. For more information, see the [Inngest flow control documentation](https://www.inngest.com/docs/guides/flow-control).

package/.docs/raw/guides/migrations/upgrade-to-v1/memory.mdx

@@ -252,18 +252,26 @@ To migrate, use `MastraDBMessage` for storage or AI SDK v5 message formats direc
 
 The `processors` config option in the Memory constructor has been deprecated and now throws an error. Processors should be configured at the Agent level instead. This change provides clearer configuration boundaries and better encapsulation.
 
-To migrate, move processor configuration from Memory to Agent.
+To migrate, move processor configuration from Memory to Agent using `inputProcessors` and/or `outputProcessors`.
 
 ```diff
++ import { TokenLimiter } from '@mastra/core/processors';
++
   const memory = new Memory({
     storage,
     vector,
     embedder,
 -   processors: [/* ... */],
   });
-  
+
   const agent = new Agent({
     memory,
-+   processors: [/* ... */],
++   inputProcessors: [
++     new TokenLimiter({ limit: 4000 }), // Limits historical messages to fit context window
++   ],
   });
 ```
+
+Additionally, the `@mastra/memory/processors` import path has been removed. Import processors from `@mastra/core/processors` instead. See the [processors migration guide](/guides/v1/migrations/upgrade-to-v1/processors#memory-processor-exports-moved-to-core) for details.
+
+For more information on using processors with agents, see the [Processors docs](/docs/v1/agents/processors). For a complete example with memory, see the [TokenLimiter reference](/reference/v1/processors/token-limiter-processor#extended-usage-example).

package/.docs/raw/guides/migrations/upgrade-to-v1/processors.mdx

@@ -60,3 +60,14 @@ If you have used `InputProcessor`, replace it with `Processor` which implements
 - import { InputProcessor, ModerationProcessor } from '@mastra/core/agent/input-processors/processors';
 + import { Processor, ModerationProcessor } from '@mastra/core/processors';
 ```
+
+### Memory processor exports moved to core
+
+The `@mastra/memory/processors` export has been removed. All processors are now exported from `@mastra/core/processors`. This change consolidates all processor exports in a single location.
+
+To migrate, update your import paths from `@mastra/memory/processors` to `@mastra/core/processors`.
+
+```diff
+- import { TokenLimiter, ToolCallFilter } from '@mastra/memory/processors';
++ import { TokenLimiter, ToolCallFilter } from '@mastra/core/processors';
+```

package/.docs/raw/guides/migrations/upgrade-to-v1/storage.mdx

@@ -7,6 +7,33 @@ description: "Learn how to migrate storage-related changes when upgrading to v1.
 
 Storage APIs have been standardized with consistent pagination and naming patterns across all methods.
 
+## Added
+
+### Storage composition in MastraStorage
+
+`MastraStorage` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+
+```typescript
+import { MastraStorage } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+// Compose domains from different stores
+const mastra = new Mastra({
+  storage: new MastraStorage({
+    id: "composite",
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./local.db" }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    },
+  }),
+});
+```
+
+See the [Storage Composition reference](/reference/v1/storage/composite) for more details.
+
 ## Changed
 
 ### Required `id` property for storage instances
@@ -80,6 +107,47 @@ npx @mastra/codemod@beta v1/storage-get-messages-paginated .
 
 :::
 
+### Domain-specific storage access via `getStore()`
+
+Storage operations are now accessed through domain-specific stores instead of directly on the storage instance. 
+
+Domains include:
+- **`memory`** - Threads, messages, and resources
+- **`workflows`** - Workflow snapshots
+- **`scores`** - Evaluation scores
+- **`observability`** - Traces and spans
+- **`agents`** - Stored agent data
+
+To migrate, call `getStore()` with the domain name, then call methods on the returned store.
+
+```diff
+  const storage = mastra.getStorage();
+
+  // Memory operations (threads, messages, resources)
+- const thread = await storage.getThread({ threadId: '123' });
+- await storage.saveThread({ thread });
++ const memoryStore = await storage.getStore('memory');
++ const thread = await memoryStore?.getThreadById({ threadId: '123' });
++ await memoryStore?.saveThread({ thread });
+
+  // Workflow operations (snapshots)
+- const snapshot = await storage.loadWorkflowSnapshot({ runId, workflowName });
+- await storage.persistWorkflowSnapshot({ runId, workflowName, snapshot });
++ const workflowStore = await storage.getStore('workflows');
++ const snapshot = await workflowStore?.loadWorkflowSnapshot({ runId, workflowName });
++ await workflowStore?.persistWorkflowSnapshot({ runId, workflowName, snapshot });
+
+  // Observability operations (traces, spans)
+- const traces = await storage.listTraces({ page: 0, perPage: 20 });
++ const observabilityStore = await storage.getStore('observability');
++ const traces = await observabilityStore?.listTraces({ page: 0, perPage: 20 });
+
+  // Score operations (evaluations)
+- const scores = await storage.listScoresByScorerId({ scorerId: 'helpfulness' });
++ const scoresStore = await storage.getStore('scores');
++ const scores = await scoresStore?.listScoresByScorerId({ scorerId: 'helpfulness' });
+```
+
 ### `getThreadsByResourceId` to `listThreadsByResourceId`
 
 The `getThreadsByResourceId()` method has been renamed to `listThreadsByResourceId()`. This change aligns with the convention that `list*` methods return collections.

package/.docs/raw/mastra-cloud/deployment.mdx

@@ -0,0 +1,39 @@
+---
+title: "Deployment | Mastra Cloud"
+description: Deploy your Mastra application to production
+---
+
+# Deployment
+
+Deploy your Mastra application to production and expose your agents, tools, and workflows as REST API endpoints.
+
+:::info
+Mastra Cloud is currently in beta, but many teams are already using it to deploy their agents. It's the easiest way to run Mastra agents in a managed environment.
+:::
+
+## Enable deployments
+
+After [setting up your project](/docs/v1/mastra-cloud/setup), click **Deployment** in the sidebar and select **Enable Deployments**.
+
+Once enabled, your project automatically builds and deploys. Future pushes to your main branch trigger automatic redeployments.
+
+## Dashboard
+
+The **Overview** page shows your project's domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/img/mastra-cloud/mastra-cloud-project-dashboard.jpg)
+
+Click the **Deployments** menu item to view build logs. Open **Settings** to configure environment variables, branch, storage, and endpoint URLs. 
+
+:::note
+Changes to settings require a new deployment to take effect
+:::
+
+## Using your deployment
+
+After deployment, interact with your agents using the [Mastra Client](/docs/v1/server/mastra-client) or call the REST API endpoints directly.
+
+## Next steps
+
+- [Studio](/docs/v1/mastra-cloud/studio) - Test your agents in the cloud
+- [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs