@mastra/mcp-docs-server 1.0.0-beta.2 → 1.0.0-beta.3

package/.docs/raw/workflows/suspend-and-resume.mdx

@@ -1,289 +1,132 @@
 ---
-title: "Suspend & Resume | Workflows | Mastra Docs"
+title: "Suspend & Resume | Workflows"
 description: "Suspend and resume in Mastra workflows allows you to pause execution while waiting for external input or resources."
 ---
 
 # Suspend & Resume
 
-Workflows can be paused at any step, with their current state persisted as a [snapshot](./snapshots) in storage. Execution can then be resumed from this saved snapshot when ready. Persisting the snapshot ensures the workflow state is maintained across sessions, deployments, and server restarts, essential for workflows that may remain suspended while awaiting external input or resources.
+Workflows can be paused at any step to collect additional data, wait for API callbacks, throttle costly operations, or request [human-in-the-loop](/docs/v1/workflows/human-in-the-loop) input. When a workflow is suspended, its current execution state is saved as a snapshot. You can later resume the workflow from a [specific step ID](/docs/v1/workflows/snapshots#retrieving-snapshots), restoring the exact state captured in that snapshot. [Snapshots](/docs/v1/workflows/snapshots) are stored in your configured storage provider and across deployments and application restarts.
+## Pausing a workflow with `suspend()`
 
-Common scenarios for suspending workflows include:
+Use `suspend()` to pause workflow execution at a specific step. You can define a suspend condition in the step’s `execute` block using values from `resumeData`.
 
-- Waiting for human approval or input
-- Pausing until external API resources become available
-- Collecting additional data needed for later steps
-- Rate limiting or throttling expensive operations
-- Handling event-driven processes with external triggers
+- If the condition isn’t met, the workflow pauses and returns `suspend()`.
+- If the condition is met, the workflow continues with the remaining logic in the step.
 
-> **New to suspend and resume?** Watch these official video tutorials:
->
-> - **[Mastering Human-in-the-Loop with Suspend & Resume](https://youtu.be/aORuNG8Tq_k)** - Learn how to suspend workflows and accept user inputs
-> - **[Building Multi-Turn Chat Interfaces with React](https://youtu.be/UMVm8YZwlxc)** - Implement multi-turn human-involved interactions with a React chat interface
+![Pausing a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
 
-## Workflow status types
-
-When running a workflow, its `status` can be one of the following:
-
-- `running` - The workflow is currently running
-- `suspended` - The workflow is suspended
-- `success` - The workflow has completed
-- `failed` - The workflow has failed
-
-## Suspending a workflow with `suspend()`
-
-To pause execution at a specific step until user input is received, use the `⁠suspend` function to temporarily halt the workflow, allowing it to resume only when the necessary data is provided.
-
-![Suspending a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
-
-```typescript {16} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {9-11,16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
   id: "step-1",
   inputSchema: z.object({
-    input: z.string(),
+    userEmail: z.string()
   }),
   outputSchema: z.object({
-    output: z.string(),
+    output: z.string()
   }),
   resumeSchema: z.object({
-    city: z.string(),
+    approved: z.boolean()
   }),
-  execute: async ({ resumeData, suspend }) => {
-    const { city } = resumeData ?? {};
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { userEmail } = inputData;
+    const { approved } = resumeData ?? {};
 
-    if (!city) {
+    if (!approved) {
       return await suspend({});
     }
 
-    return { output: "" };
-  },
+    return {
+      output: `Email sent to ${userEmail}`
+    };
+  }
 });
 
 export const testWorkflow = createWorkflow({
-  // ...
+  id: "test-workflow",
+  inputSchema: z.object({
+    userEmail: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  })
 })
   .then(step1)
   .commit();
 ```
 
-> For more details, check out the [Suspend & Resume documentation](/docs/v1/workflows/suspend-and-resume).
+## Restarting a workflow with `resume()`
 
-### Identifying suspended steps
+Use `resume()` to restart a suspended workflow from the step where it paused. To satisfy the step’s suspend condition, pass a value using `resumeData` that matches the step's `resumeSchema`, allowing execution to continue from the suspended step.
 
-To resume a suspended workflow, inspect the `suspended` array in the result to determine which step needs input:
+![Restarting a workflow with resume()](/img/workflows/workflows-suspend-resume-resume.jpg)
 
-```typescript {15} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+```typescript {13} showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRunAsync();
 
-const run = await mastra.getWorkflow("testWorkflow").createRun();
-
-const result = await run.start({
+await run.start({
   inputData: {
-    city: "London",
-  },
+    userEmail: "alex@example.com"
+  }
 });
 
-console.log(JSON.stringify(result, null, 2));
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: result.suspended[0],
-    resumeData: {
-      city: "Berlin",
-    },
+const handleResume = async () => {
+  const result = await run.resume({
+    step: 'step-1',
+    resumeData: { approved: true }
   });
-}
-```
-
-In this case, the logic resumes the first step listed in the `suspended` array. A `step` can also be defined using it's `id`, for example: 'step-1'.
-
-```json
-{
-  "status": "suspended",
-  "steps": {
-    // ...
-    "step-1": {
-      // ...
-      "status": "suspended"
-    }
-  },
-  "suspended": [["step-1"]]
-}
+};
 ```
 
-> See [Workflow Output](./overview#workflow-output) for more details.
-
-## Providing user feedback with suspend
-
-When a workflow is suspended, feedback can be surfaced to the user through the `suspendSchema`. Include a reason in the `suspend` payload to explain why the workflow paused.
-
-```typescript {13,23} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({
-    value: z.string(),
-  }),
-  resumeSchema: z.object({
-    confirm: z.boolean(),
-  }),
-  suspendSchema: z.object({
-    reason: z.string(),
-  }),
-  outputSchema: z.object({
-    value: z.string(),
-  }),
-  execute: async ({ resumeData, suspend }) => {
-    const { confirm } = resumeData ?? {};
-
-    if (!confirm) {
-      return await suspend({
-        reason: "Confirm to continue",
-      });
-    }
-
-    return { value: "" };
-  },
-});
-
-export const testWorkflow = createWorkflow({
-  // ...
-})
-  .then(step1)
-  .commit();
-```
+You can resume a suspended workflow using different triggers, including [human input](/docs/v1/workflows/human-in-the-loop), external events from your application, or time-based conditions.
 
-In this case, the reason provided explains that the user must confirm to continue.
+```typescript {10} showLineNumbers copy
+const handleResume = async () => {
+  const result = await run.resume({
+    step: 'step-1',
+    resumeData: { approved: true }
+  });
+};
 
-```json
-{
-  "step-1": {
-    // ...
-    "status": "suspended",
-    "suspendPayload": {
-      "reason": "Confirm to continue"
-    }
-  }
-}
+const midnight = new Date();
+midnight.setUTCHours(24, 0, 0, 0);
+setTimeout(handleResume, midnight.getTime() - Date.now());
 ```
 
-> See [Workflow Output](./overview#workflow-output) for more details.
-
-## Resuming a workflow with `resume()`
+## Identifying suspended executions
 
-A workflow can be resumed by calling `resume` and providing the required `resumeData`. You can either explicitly specify which step to resume from, or when exactly one step is suspended, omit the `step` parameter and the workflow will automatically resume that step.
+When a workflow is suspended, it restarts from the step where it paused. You can check the workflow's `status` to confirm it's suspended, and use `suspended` to identify the paused step or [nested workflow](/docs/v1/workflows/overview#workflows-as-steps).
 
-```typescript {16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRun();
+```typescript {11} showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRunAsync();
 
 const result = await run.start({
   inputData: {
-    city: "London",
-  },
+    userEmail: "alex@example.com"
+  }
 });
 
-console.log(JSON.stringify(result, null, 2));
-
 if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: "step-1",
-    resumeData: {
-      city: "Berlin",
-    },
+  console.log(result.suspended[0]);
+  await run.resume({
+    step: result.suspended[0],
+    resumeData: { approved: true }
   });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
 }
 ```
 
-You can also omit the `step` parameter when exactly one step is suspended:
-
-```typescript {5} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const resumedResult = await run.resume({
-  resumeData: {
-    city: "Berlin",
-  },
-  // step parameter omitted - automatically resumes the single suspended step
-});
-```
-
-You can pass `requestContext` as an argument to both the `start` and `resume` commands.
-
-```typescript title="src/mastra/workflows/test-workflow.ts"
-import { RequestContext } from "@mastra/core/request-context";
-
-const requestContext = new RequestContext();
-
-const result = await run.start({
-  step: "step-1",
-  inputData: {
-    city: "London",
-  },
-  requestContext,
-});
-
-const resumedResult = await run.resume({
-  step: "step-1",
-  resumeData: {
-    city: "New York",
-  },
-  requestContext,
-});
-```
-
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
-
-### Resuming nested workflows
+**Example output**
 
-To resume a suspended nested workflow pass the workflow instance to the `step` parameter of the `resume` function.
+The `suspended` array contains the IDs of any suspended workflows and steps from the run. These can be passed to the `step` parameter when calling `resume()` to target and resume the suspended execution path.
 
-```typescript {33-34} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const dowhileWorkflow = createWorkflow({
-  id: "dowhile-workflow",
-  inputSchema: z.object({ value: z.number() }),
-  outputSchema: z.object({ value: z.number() }),
-})
-  .dountil(
-    createWorkflow({
-      id: "simple-resume-workflow",
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      steps: [incrementStep, resumeStep],
-    })
-      .then(incrementStep)
-      .then(resumeStep)
-      .commit(),
-    async ({ inputData }) => inputData.value >= 10,
-  )
-  .then(
-    createStep({
-      id: "final",
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      execute: async ({ inputData }) => ({ value: inputData.value }),
-    }),
-  )
-  .commit();
-
-const run = await dowhileWorkflow.createRun();
-const result = await run.start({ inputData: { value: 0 } });
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    resumeData: { value: 2 },
-    step: ["simple-resume-workflow", "resume"],
-  });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
-}
+```typescript
+[ 'nested-workflow', 'step-1' ]
 ```
 
 ## Sleep & Events
 
-Workflows can also pause execution for timed delays or external events. These methods set the workflow status to `waiting` rather than `suspended`, and are useful for polling, delayed retries, or event-driven processes.
+Sleep and event methods can be used to pause execution at the workflow level, which sets the status to `waiting`. By comparison, `suspend()` pauses execution within a specific step and sets the status to `suspended`.
 
 **Available methods:**
 
@@ -291,3 +134,8 @@ Workflows can also pause execution for timed delays or external events. These me
 - [`.sleepUntil()`](/reference/v1/workflows/workflow-methods/sleepUntil) : Pause until a specific date
 - [`.waitForEvent()`](/reference/v1/workflows/workflow-methods/waitForEvent): Pause until an external event is received
 - [`.sendEvent()`](/reference/v1/workflows/workflow-methods/sendEvent) : Send an event to resume a waiting workflow
+
+## Related
+
+- [Control Flow](/docs/v1/workflows/control-flow)
+- [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/mcp-docs-server
 
+## 1.0.0-beta.3
+
+### Patch Changes
+
+- Templates now don't dynamically create a branch for every provider, each template should be agnostic and just use a env var to set the models until the user wants to set it otherwise. ([#10036](https://github.com/mastra-ai/mastra/pull/10036))
+  MCP docs server will install the beta version of the docs server if they create a project with the beta tag.
+  Updates to the templates now will get pushed to the beta branch, when beta goes stable we will merge the beta branch into the main branch for all templates and update the github script to push to main.
+  Templates have been cleaned up
+  small docs updates based off of how the template migrations went
+
+- Remove unused dependencies ([#10019](https://github.com/mastra-ai/mastra/pull/10019))
+
+- Updated dependencies [[`2319326`](https://github.com/mastra-ai/mastra/commit/2319326f8c64e503a09bbcf14be2dd65405445e0), [`e314bb8`](https://github.com/mastra-ai/mastra/commit/e314bb89e7b57127ffecaf22687b5475f2aa2a63), [`d629361`](https://github.com/mastra-ai/mastra/commit/d629361a60f6565b5bfb11976fdaf7308af858e2), [`08c31c1`](https://github.com/mastra-ai/mastra/commit/08c31c188ebccd598acaf55e888b6397d01f7eae), [`fd3d338`](https://github.com/mastra-ai/mastra/commit/fd3d338a2c362174ed5b383f1f011ad9fb0302aa), [`c30400a`](https://github.com/mastra-ai/mastra/commit/c30400a49b994b1b97256fe785eb6c906fc2b232), [`69e0a87`](https://github.com/mastra-ai/mastra/commit/69e0a878896a2da9494945d86e056a5f8f05b851), [`01f8878`](https://github.com/mastra-ai/mastra/commit/01f88783de25e4de048c1c8aace43e26373c6ea5), [`4c77209`](https://github.com/mastra-ai/mastra/commit/4c77209e6c11678808b365d545845918c40045c8), [`d827d08`](https://github.com/mastra-ai/mastra/commit/d827d0808ffe1f3553a84e975806cc989b9735dd), [`23c10a1`](https://github.com/mastra-ai/mastra/commit/23c10a1efdd9a693c405511ab2dc8a1236603162), [`676ccc7`](https://github.com/mastra-ai/mastra/commit/676ccc7fe92468d2d45d39c31a87825c89fd1ea0), [`c10398d`](https://github.com/mastra-ai/mastra/commit/c10398d5b88f1d4af556f4267ff06f1d11e89179), [`00c2387`](https://github.com/mastra-ai/mastra/commit/00c2387f5f04a365316f851e58666ac43f8c4edf), [`ad6250d`](https://github.com/mastra-ai/mastra/commit/ad6250dbdaad927e29f74a27b83f6c468b50a705), [`3a73998`](https://github.com/mastra-ai/mastra/commit/3a73998fa4ebeb7f3dc9301afe78095fc63e7999), [`e16d553`](https://github.com/mastra-ai/mastra/commit/e16d55338403c7553531cc568125c63d53653dff), [`4d59f58`](https://github.com/mastra-ai/mastra/commit/4d59f58de2d90d6e2810a19d4518e38ddddb9038), [`e1bb9c9`](https://github.com/mastra-ai/mastra/commit/e1bb9c94b4eb68b019ae275981be3feb769b5365), [`351a11f`](https://github.com/mastra-ai/mastra/commit/351a11fcaf2ed1008977fa9b9a489fc422e51cd4)]:
+  - @mastra/core@1.0.0-beta.3
+  - @mastra/mcp@1.0.0-beta.2
+
 ## 1.0.0-beta.2
 
 ### Patch Changes

package/dist/stdio.js

@@ -148,13 +148,14 @@ function getUpgradeToV1Messages(area) {
           type: "text",
           text: `I need help migrating my Mastra ${area} code from v0.x to v1.0. Use the mastraMigration tool to:
 
-1. First, try to get the specific migration guide for "${area}" using path: "upgrade-to-v1/${area}"
-2. If that doesn't exist, try the alternate form (singular/plural):
+1. If packages aren't already at the 'beta' tag, upgrade packages to the 'beta' tag and do an install of the new packages.
+2. First, try to get the specific migration guide for "${area}" using path: "upgrade-to-v1/${area}"
+3. If that doesn't exist, try the alternate form (singular/plural):
    - If "${area}" ends with 's', try without the 's' (e.g., "agents" \u2192 "agent")
    - If "${area}" doesn't end with 's', try adding 's' (e.g., "agent" \u2192 "agents")
-3. If the guide exists, walk me through the changes step by step
-4. If neither form exists, list available migration guides in "upgrade-to-v1/" and suggest which ones might be relevant to "${area}"
-5. After you find the guide, collect all the codemod calls to run to codemods. These callouts are marked with ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta <codemod-name> <path>" to automate all those changes. Afterwards, help me with any remaining manual changes needed.`
+4. If the guide exists, walk me through the changes step by step
+5. If neither form exists, list available migration guides in "upgrade-to-v1/" and suggest which ones might be relevant to "${area}"
+6. After you find the guide, collect all the codemod calls to run to codemods. These callouts are marked with ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta <codemod-name> <path>" to automate all those changes. Afterwards, help me with any remaining manual changes needed.`
         }
       }
     ];
@@ -166,12 +167,13 @@ function getUpgradeToV1Messages(area) {
         type: "text",
         text: `I need to migrate my Mastra project from v0.x to v1.0. Use the mastraMigration tool to:
 
-1. First, list all available migration guides with path: "upgrade-to-v1/"
+1. If packages aren't already at the 'beta' tag, upgrade packages to the 'beta' tag and do an install of the new packages.
+2. First, list all available migration guides with path: "upgrade-to-v1/"
 2. Give me a high-level overview of what changed in each area
-3. Ask me which areas I'm using in my project so we can focus on relevant changes
-4. After I decided on the areas, check the migration guides for callouts to codemods. These callouts are marked with ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta v1" to automate all those changes. Afterwards, help me with any remaining manual changes needed.
+3. Find relevant migration areas to focus on based on my project's codebase and confirm the list with me
+4. After the areas are confirmed, check the migration guides for callouts to codemods. These callouts are marked with ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta v1" to automate all those changes. Afterwards, help me with any remaining manual changes needed.
 
-After I tell you which areas I use, we'll go through each one systematically.`
+After the areas are confirmed, we'll go through each one systematically.`
       }
     }
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,31 +26,27 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.5",
-    "date-fns": "^4.1.0",
-    "exit-hook": "^4.0.0",
     "jsdom": "^26.1.0",
-    "turndown": "^7.2.1",
-    "uuid": "^11.1.0",
     "zod": "^3.25.76",
-    "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "1.0.0-beta.2",
-    "@mastra/mcp": "^1.0.0-beta.1"
+    "@mastra/mcp": "^1.0.0-beta.2",
+    "@mastra/core": "1.0.0-beta.3"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.6",
     "@types/jsdom": "^21.1.7",
-    "@types/node": "^20.19.0",
-    "@types/turndown": "^5.0.5",
-    "@wong2/mcp-cli": "^1.10.0",
+    "@types/node": "22.13.17",
+    "@vitest/coverage-v8": "4.0.8",
+    "@vitest/ui": "4.0.8",
+    "@wong2/mcp-cli": "^1.13.0",
     "cross-env": "^10.1.0",
     "eslint": "^9.37.0",
-    "hono": "^4.9.7",
+    "hono": "^4.10.5",
     "tsup": "^8.5.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4",
+    "vitest": "^4.0.8",
     "@internal/lint": "0.0.53",
-    "@mastra/core": "1.0.0-beta.2"
+    "@mastra/core": "1.0.0-beta.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/raw/deployment/serverless-platforms/index.mdx

@@ -1,58 +0,0 @@
----
-title: "Serverless Deployment | Deployment | Mastra Docs"
-description: "Build and deploy Mastra applications using platform-specific deployers or standard HTTP servers"
----
-
-# Serverless Deployment
-
-Standalone Mastra applications can be deployed to popular serverless platforms using one of our deployer packages:
-
-- [Cloudflare](/docs/v1/deployment/serverless-platforms/cloudflare-deployer)
-- [Netlify](/docs/v1/deployment/serverless-platforms/netlify-deployer)
-- [Vercel](/docs/v1/deployment/serverless-platforms/vercel-deployer)
-
-Deployers **aren't** required when integrating Mastra with a framework. See [Web Framework Integration](/docs/v1/deployment/web-framework) for more information.
-
-For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/v1/deployment/server-deployment) guide.
-
-## Prerequisites
-
-Before you begin, ensure you have:
-
-- Node.js `v22.13.0` or later
-- If using a platform-specific deployer:
-  - An account with your chosen platform
-  - Required API keys or credentials
-
-## LibSQLStore
-
-`LibSQLStore` writes to the local filesystem, which is not supported in serverless environments due to their ephemeral nature. If you're deploying to a platform like Vercel, Netlify or Cloudflare, you **must remove** all usage of `LibSQLStore`.
-
-Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
-
-```typescript title="src/mastra/index.ts" showLineNumbers
-export const mastra = new Mastra({
-  // ...
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    // [!code --]
-    // stores telemetry, scorer results, ... into memory storage, if it needs to persist, change to file:../mastra.db // [!code --]
-    url: ":memory:", // [!code --]
-  }), //[!code --]
-});
-```
-
-```typescript title="src/mastra/agents/weather-agent.ts" showLineNumbers
-export const weatherAgent = new Agent({
-  id: "weather-agent",
-  // ..
-  memory: new Memory({
-    // [!code --]
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      // [!code --]
-      url: "file:../mastra.db", // path is relative to the .mastra/output directory // [!code --]
-    }), // [!code --]
-  }), //  [!code --]
-});
-```