@mastra/mcp-docs-server 0.13.1 → 0.13.2-alpha.1

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

@@ -3,61 +3,69 @@ title: Mastra Cloud
 description: Deployment and monitoring service for Mastra applications
 ---
 
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+import { FileTree } from "nextra/components";
+
 # Mastra Cloud
 
-Mastra Cloud is a deployment service built by the Mastra team that runs,
-manages, and monitors Mastra applications. It works with standard Mastra
-projects and handles deployment, scaling, and operational tasks.
+[Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+
+<MastraCloudCallout />
+
+## Platform features
+
+Deploy and manage your applications with automated builds, organized projects, and no additional configuration.
+
+![Platform features](/image/mastra-cloud/mastra-cloud-platform-features.jpg)
+
+Key features:
+
+Mastra Cloud supports zero-config deployment, continuous integration with GitHub, and atomic deployments that package agents, tools, and workflows together.
 
-> **Beta Notice**
-> Mastra Cloud is currently in **public beta**. Features, APIs, and UIs may
-> change as development continues.
+## Project Dashboard
 
-## Core Functionality
+Monitor and debug your applications with detailed output logs, deployment state, and interactive tools.
 
-- **Atomic Deployments** - Agents and workflows deploy as a single unit
-- **Project Organization** - Group agents and workflows into projects with assigned URLs
-- **Environment Variables** - Store configuration securely by environment
-- **Testing Console** - Send messages to agents through a web interface
-- **Execution Tracing** - Record agent interactions and tool calls
-- **Workflow Visualization** - Display workflow steps and execution paths
-- **Logs** - Standard logging output for debugging
-- **Platform Compatibility** - Uses the same infrastructure as Cloudflare, Vercel, and Netlify deployers
+![Project dashboard](/image/mastra-cloud/mastra-cloud-project-dashboard.jpg)
 
-## Dashboard Components
+Key features:
 
-The Mastra Cloud dashboard contains:
+The Project Dashboard gives you an overview of your application's status and deployments, with access to logs and a built-in playground for testing agents and workflows.
 
-- **Projects List** - All projects in the account
-- **Project Details** - Deployments, environment variables, and access URLs
-- **Deployment History** - Record of deployments with timestamps and status
-- **Agent Inspector** - Agent configuration view showing models, tools, and system prompts
-- **Testing Console** - Interface for sending messages to agents
-- **Trace Explorer** - Records of tool calls, parameters, and responses
-- **Workflow Viewer** - Diagram of workflow steps and connections
+## Project structure
 
-## Technical Implementation
+Use a standard Mastra project structure for proper detection and deployment.
 
-Mastra Cloud runs on the same core code as the platform-specific deployers with these modifications:
+<FileTree>
+  <FileTree.Folder name="src" defaultOpen>
+    <FileTree.Folder name="mastra" defaultOpen>
+      <FileTree.Folder name="agents" defaultOpen>
+        <FileTree.File name="agent-name.ts" />
+      </FileTree.Folder>
+      <FileTree.Folder name="tools" defaultOpen>
+        <FileTree.File name="tool-name.ts" />
+      </FileTree.Folder>
+      <FileTree.Folder name="workflows" defaultOpen>
+        <FileTree.File name="workflow-name.ts" />
+      </FileTree.Folder>
+      <FileTree.File name="index.ts" />
+    </FileTree.Folder>
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
 
-- **Edge Network Distribution** - Geographically distributed execution
-- **Dynamic Resource Allocation** - Adjusts compute resources based on traffic
-- **Mastra-specific Runtime** - Runtime optimized for agent execution
-- **Standard Deployment API** - Consistent deployment interface across environments
-- **Tracing Infrastructure** - Records all agent and workflow execution steps
+Mastra Cloud scans your repository for:
 
-## Use Cases
+- **Agents**: Defined using: `new Agent({...})`
+- **Tools**: Defined using: `createTool({...})`
+- **Workflows**: Defined using: `createWorkflow({...})`
+- **Steps**: Defined using: `createStep({...})`
+- **Environment Variables**: API keys and configuration variables
 
-Common usage patterns:
+## Technical implementation
 
-- Deploying applications without managing infrastructure
-- Maintaining staging and production environments
-- Monitoring agent behavior across many requests
-- Testing agent responses through a web interface
-- Deploying to multiple regions
+Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handles long-running requests, records detailed traces for every execution, and includes built-in support for evals.
 
-## Setup Process
+## Next steps
 
-1. [Configure a Mastra Cloud project](/docs/mastra-cloud/setting-up)
-2. [Deploy code](/docs/mastra-cloud/deploying)
-3. [View execution traces](/docs/mastra-cloud/observability)
+- [Setting Up and Deploying](/docs/mastra-cloud/setting-up)

package/.docs/raw/mastra-cloud/setting-up.mdx

@@ -3,126 +3,90 @@ title: Setting Up a Project
 description: Configuration steps for Mastra Cloud projects
 ---
 
-# Setting Up a Mastra Cloud Project
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+import { Steps } from "nextra/components";
 
-> **Beta Notice**
-> Mastra Cloud is currently in **beta**.
+# Setting Up and Deploying
 
-This page describes the steps to set up a project on Mastra Cloud using GitHub integration.
+This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/cloud) with automatic deployments using our GitHub integration.
 
-## Prerequisites
-
-- A Mastra Cloud account
-- A GitHub account
-- A GitHub repository containing a Mastra application
+<MastraCloudCallout />
 
-## Project Creation Process
-
-1. **Sign in to Mastra Cloud**
+## Prerequisites
 
-   - Navigate to the Mastra Cloud dashboard at https://cloud.mastra.ai
-   - Sign in with your account credentials
+- A [Mastra Cloud](https://mastra.ai/cloud) account
+- A GitHub account / repository containing a Mastra application
 
-2. **Add a New Project**
+> See our [Getting started](/docs/getting-started/installation) guide to scaffold out a new Mastra project with sensible defaults.
 
-   - From the "All Projects" view, click the "Add new" button in the top right
-   - This opens the GitHub repository import dialog
+## Setup and Deploy process
 
-   ![Mastra Cloud Projects Dashboard](/image/cloud-agents.png)
+<Steps>
 
-3. **Import Git Repository**
+### Sign in to Mastra Cloud
 
-   - Search for repositories or select from the list of available GitHub repositories
-   - Click the "Import" button next to the repository you want to deploy
+Head over to [https://cloud.mastra.ai/](https://cloud.mastra.ai) and sign in with either:
 
-4. **Configure Deployment Details**
-   The deployment configuration page includes:
-   - **Repo Name**: The GitHub repository name (read-only)
-   - **Project Name**: Customize the project name (defaults to repo name)
-   - **Branch**: Select the branch to deploy (dropdown, defaults to `main`)
-   - **Project root**: Set the root directory of your project (defaults to `/`)
-   - **Mastra Directory**: Specify where Mastra files are located (defaults to `src/mastra`)
-   - **Build Command**: Optional command to run during build process
-   - **Store Settings**: Configure data storage options
-   - **Environment Variables**: Add key-value pairs for configuration (e.g., API keys)
+- **GitHub**
+- **Google**
 
-## Project Structure Requirements
+### Install the Mastra GitHub app
 
-Mastra Cloud scans the GitHub repository for:
+When prompted, install the Mastra GitHub app.
 
-- **Agents**: Agent definitions (e.g., Weather Agent) with models and tools
-- **Workflows**: Workflow step definitions (e.g., weather-workflow)
-- **Environment Variables**: Required API keys and configuration variables
+![Install GitHub](/image/mastra-cloud/mastra-cloud-install-github.jpg)
 
-The repository should contain a standard Mastra project structure for proper detection and deployment.
+### Create a new project
 
-## Understanding the Dashboard
+Click the **Create new project** button to create a new project.
 
-After creating a project, the dashboard shows:
+![Create new project](/image/mastra-cloud/mastra-cloud-create-new-project.jpg)
 
-### Project Overview
+### Import a Git repository
 
-- **Created Date**: When the project was created
-- **Domains**: URLs for accessing your deployed application
-  - Format: `https://[project-name].mastra.cloud`
-  - Format: `https://[random-id].mastra.cloud`
-- **Status**: Current deployment status (success or archived)
-- **Branch**: The branch deployed (typically `main`)
-- **Environment Variables**: Configured API keys and settings
-- **Workflows**: List of detected workflows with step counts
-- **Agents**: List of detected agents with models and tools
-- **Database Usage**: Reads, writes, and storage statistics
+Search for a repository, then click **Import**.
 
-### Deployments Section
+![Import Git repository](/image/mastra-cloud/mastra-cloud-import-git-repository.jpg)
 
-- List of all deployments with:
-  - Deployment ID (based on commit hash)
-  - Status (success/archived)
-  - Branch
-  - Commit hash
-  - Timestamp
+### Configure the deployment
 
-### Logs Section
+Mastra Cloud automatically detects the right build settings, but you can customize them using the options described below.
 
-The Logs view displays:
+![Deployment details](/image/mastra-cloud/mastra-cloud-deployment-details.jpg)
 
-- Timestamp for each log entry
-- Log level (info, debug)
-- Hostname
-- Detailed log messages, including:
-  - API startup information
-  - Storage initialization
-  - Agent and workflow activity
+- **Importing from GitHub**: The GitHub repository name
+- **Project name**: Customize the project name
+- **Branch**: The branch to deploy from
+- **Project root**: The root directory of your project
+- **Mastra directory**: Where Mastra files are located
+- **Environment variables**: Add environment variables used by the application
+- **Build and Store settings**:
+   - **Install command**: Runs pre-build to install project dependencies
+   - **Project setup command**: Runs pre-build to prepare any external dependencies
+   - **Port**: The network port the server will use
+   - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/storage/overview) storage
+- **Deploy Project**: Starts the deployment process
 
-## Navigation
+### Deploy project
 
-The sidebar provides access to:
+Click **Deploy Project** to create and deploy your application using the configuration you’ve set.
 
-- **Overview**: Project summary and statistics
-- **Deployments**: Deployment history and details
-- **Logs**: Application logs for debugging
-- **Agents**: List and configuration of all agents
-- **Workflows**: List and structure of all workflows
-- **Settings**: Project configuration options
+</Steps>
 
-## Environment Variable Configuration
+## Successful deployment
 
-Set environment variables through the dashboard:
+After a successful deployment you'll be shown the **Overview** screen where you can view your project's status, domains, latest deployments and connected agents and workflows.
 
-1. Navigate to your project in the dashboard
-2. Go to the "Environment Variables" section
-3. Add or edit variables (such as `OPENAI_API_KEY`)
-4. Save the configuration
+![Successful deployment](/image/mastra-cloud/mastra-cloud-successful-deployment.jpg)
 
-Environment variables are encrypted and made available to your application during deployment and execution.
+## Continuous integration
 
-## Testing Your Deployment
+Your project is now configured with automatic deployments which occur whenever you push to the configured branch of your GitHub repository.
 
-After deployment, you can test your agents and workflows using:
+## Testing your application
 
-1. The custom domain assigned to your project: `https://[project-name].mastra.cloud`
-2. The dashboard interface for direct interaction with agents
+After a successful deployment you can test your agents and workflows from the [Playground](/docs/mastra-cloud/dashboard#playground) in Mastra Cloud, or interact with them using our [Client SDK](/docs/client-js/overview).
 
-## Next Steps
+## Next steps
 
-After setting up your project, automatic deployments occur whenever you push to the `main` branch of your GitHub repository. See the [deployment documentation](./deploying.mdx) for more details.
+- [Navigating the Dashboard](/docs/mastra-cloud/dashboard)

package/.docs/raw/memory/overview.mdx

@@ -8,6 +8,8 @@ The context window is the total information visible to the language model at any
 
 In Mastra, context is broken up into three parts: system instructions and information about the user ([working memory](./working-memory.mdx)), recent messages ([message history](#conversation-history)), and older messages that are relevant to the user’s query ([semantic recall](./semantic-recall.mdx)).
 
+Working memory can persist at different scopes - either per conversation thread (default) or across all threads for the same user (resource-scoped), enabling persistent user profiles that remember context across conversations.
+
 In addition, we provide [memory processors](./memory-processors.mdx) to trim context or remove information if the context is too long.
 
 ## Quick Start
@@ -69,6 +71,8 @@ Mastra organizes memory into threads, which are records that identify specific c
 1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
 2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
 
+The `resourceId` is particularly important for [resource-scoped working memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all conversation threads for the same user.
+
 ```typescript {2,3}
 const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
   resourceId: "user_alice",

package/.docs/raw/memory/working-memory.mdx

@@ -2,12 +2,19 @@ import YouTube from "@/components/youtube";
 
 # Working Memory
 
-While [conversation history](/docs/memory/overview#conversation-history) and [semantic recall](./semantic-recall.mdx) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions within a thread.
+While [conversation history](/docs/memory/overview#conversation-history) and [semantic recall](./semantic-recall.mdx) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
 
 Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
 
 This is useful for maintaining ongoing state that's always relevant and should always be available to the agent.
 
+Working memory can persist at two different scopes:
+- **Thread-scoped** (default): Memory is isolated per conversation thread
+- **Resource-scoped**: Memory persists across all conversation threads for the same user
+
+**Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
+
+
 ## Quick Start
 
 Here's a minimal example of setting up an agent with working memory:
@@ -38,6 +45,85 @@ Working memory is a block of Markdown text that the agent is able to update over
 
 <YouTube id="ik-ld_XA96s" />
 
+## Memory Persistence Scopes
+
+Working memory can operate in two different scopes, allowing you to choose how memory persists across conversations:
+
+### Thread-Scoped Memory (Default)
+
+By default, working memory is scoped to individual conversation threads. Each thread maintains its own isolated memory:
+
+```typescript
+const memory = new Memory({
+  storage,
+  options: {
+    workingMemory: {
+      enabled: true,
+      scope: 'thread', // Default - memory is isolated per thread
+      template: `# User Profile
+- **Name**: 
+- **Interests**: 
+- **Current Goal**: 
+`,
+    },
+  },
+});
+```
+
+**Use cases:**
+- Different conversations about separate topics
+- Temporary or session-specific information
+- Workflows where each thread needs working memory but threads are ephemeral and not related to each other
+
+### Resource-Scoped Memory
+
+Resource-scoped memory persists across all conversation threads for the same user (resourceId), enabling persistent user memory:
+
+```typescript
+const memory = new Memory({
+  storage,
+  options: {
+    workingMemory: {
+      enabled: true,
+      scope: 'resource', // Memory persists across all user threads
+      template: `# User Profile
+- **Name**: 
+- **Location**: 
+- **Interests**: 
+- **Preferences**: 
+- **Long-term Goals**: 
+`,
+    },
+  },
+});
+```
+
+**Use cases:**
+- Personal assistants that remember user preferences
+- Customer service bots that maintain customer context
+- Educational applications that track student progress
+
+### Usage with Agents
+
+When using resource-scoped memory, make sure to pass the `resourceId` parameter:
+
+```typescript
+// Resource-scoped memory requires resourceId
+const response = await agent.generate("Hello!", {
+  threadId: "conversation-123",
+  resourceId: "user-alice-456" // Same user across different threads
+});
+```
+
+## Storage Adapter Support
+
+Resource-scoped working memory requires specific storage adapters that support the `mastra_resources` table:
+
+### ✅ Supported Storage Adapters
+- **LibSQL** (`@mastra/libsql`)
+- **PostgreSQL** (`@mastra/pg`)
+- **Upstash** (`@mastra/upstash`)
+
 ## Custom Templates
 
 Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information.
@@ -161,3 +247,4 @@ instructions on _how_ and _when_ to use this template in your agent's `instructi
 
 - [Streaming working memory](/examples/memory/streaming-working-memory)
 - [Using a working memory template](/examples/memory/streaming-working-memory-advanced)
+- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/.docs/raw/observability/nextjs-tracing.mdx

@@ -59,7 +59,7 @@ npm install @opentelemetry/api langfuse-vercel
 import {
   NodeSDK,
   ATTR_SERVICE_NAME,
-  Resource,
+  resourceFromAttributes,
 } from "@mastra/core/telemetry/otel-vendor";
 import { LangfuseExporter } from "langfuse-vercel";
 
@@ -69,7 +69,7 @@ export function register() {
   });
 
   const sdk = new NodeSDK({
-    resource: new Resource({
+    resource: resourceFromAttributes({
       [ATTR_SERVICE_NAME]: "ai",
     }),
     traceExporter: exporter,

package/.docs/raw/reference/storage/libsql.mdx

@@ -67,4 +67,5 @@ The storage implementation handles schema creation and updates automatically. It
 
 - `threads`: Stores conversation threads
 - `messages`: Stores individual messages
+- `resources`: Stores user-specific data for resource-scoped working memory
 - `metadata`: Stores additional metadata for threads and messages

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -539,6 +539,7 @@ runtimeContext.set("filter", { category: "docs" });
 runtimeContext.set("databaseConfig", {
   pinecone: { namespace: "runtime-namespace" }
 });
+runtimeContext.set("model", openai.embedding("text-embedding-3-small"));
 
 const response = await agent.generate(
   "Find documentation from the knowledge base.",

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

@@ -0,0 +1,43 @@
+---
+title: "Reference: Workflow.sleep() | Building Workflows | Mastra Docs"
+description: Documentation for the `.sleep()` method in workflows, which pauses execution for a specified number of milliseconds.
+---
+
+# Workflow.sleep()
+
+The `.sleep()` method pauses execution for a specified number of milliseconds.
+
+## Usage
+
+```typescript
+workflow.sleep(1000);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "milliseconds",
+      type: "number",
+      description: "The number of milliseconds to pause execution",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

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

@@ -0,0 +1,43 @@
+---
+title: "Reference: Workflow.sleepUntil() | Building Workflows | Mastra Docs"
+description: Documentation for the `.sleepUntil()` method in workflows, which pauses execution until a specified date.
+---
+
+# Workflow.sleepUntil()
+
+The `.sleepUntil()` method pauses execution until a specified date.
+
+## Usage
+
+```typescript
+workflow.sleepUntil(new Date(Date.now() + 1000));
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "date",
+      type: "Date",
+      description: "The date until which to pause execution",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

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

@@ -0,0 +1,49 @@
+---
+title: "Reference: Workflow.waitForEvent() | Building Workflows | Mastra Docs"
+description: Documentation for the `.waitForEvent()` method in workflows, which pauses execution until an event is received.
+---
+
+# Workflow.waitForEvent()
+
+The `.waitForEvent()` method pauses execution until an event is received.
+
+## Usage
+
+```typescript
+workflow.waitForEvent('my-event-name', step1);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "eventName",
+      type: "string",
+      description: "The name of the event to wait for",
+      isOptional: false,
+    },
+    {
+      name: "step",
+      type: "Step",
+      description: "The step to resume after the event is received",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

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

@@ -55,7 +55,7 @@ Each tab includes detailed column information with types, constraints, and examp
 The data types include Messages, Threads, Workflows, Eval Datasets, and Traces.
 */}
 
-<Tabs items={['Messages', 'Threads', 'Workflows', 'Eval Datasets', 'Traces']}>
+<Tabs items={['Messages', 'Threads', 'Resources', '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.
 
@@ -212,6 +212,55 @@ Groups related messages together and associates them with a resource. Contains m
   ]}
 />
 
+</Tabs.Tab>
+  <Tabs.Tab>
+Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "id",
+      type: "text",
+      description: "Resource identifier (user or entity ID) - same as resourceId used in threads and agent calls",
+      constraints: [
+        { type: "primaryKey" },
+        { type: "nullable", value: false }
+      ]
+    },
+    {
+      name: "workingMemory",
+      type: "text",
+      description: "Persistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.",
+      constraints: [{ type: "nullable", value: true }]
+    },
+    {
+      name: "metadata",
+      type: "jsonb",
+      description: "Additional resource metadata as JSON. Example:",
+      example: {
+        preferences: { language: "en", timezone: "UTC" },
+        tags: ["premium", "beta-user"]
+      },
+      constraints: [{ type: "nullable", value: true }]
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      description: "When the resource record was first created",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "updatedAt",
+      type: "timestamp",
+      description: "When the working memory was last updated",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+
+**Note**: This table is only created and used by storage adapters that support resource-scoped working memory (LibSQL, PostgreSQL, Upstash). Other storage adapters will provide helpful error messages if resource-scoped memory is attempted.
+
 </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.