@mastra/mcp-docs-server 0.13.4 → 0.13.5-alpha.0

package/.docs/organized/code-examples/memory-per-resource-example.md

@@ -3,7 +3,7 @@
 {
   "name": "memory-per-resource-example",
   "dependencies": {
-    "@ai-sdk/openai": "^0.0.68",
+    "@ai-sdk/openai": "^1.3.22",
     "@mastra/core": "latest",
     "@mastra/memory": "latest",
     "@mastra/libsql": "latest",

package/.docs/organized/code-examples/memory-with-pg.md

@@ -9,7 +9,7 @@
     "@mastra/pg": "latest"
   },
   "devDependencies": {
-    "dotenv": "^16.5.0",
+    "dotenv": "^17.0.0",
     "tsx": "^4.19.3"
   }
 }

package/.docs/organized/code-examples/memory-with-upstash.md

@@ -10,7 +10,7 @@
     "@mastra/upstash": "latest"
   },
   "devDependencies": {
-    "dotenv": "^16.5.0",
+    "dotenv": "^17.0.0",
     "tsx": "^4.19.3"
   }
 }

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -9,10 +9,10 @@
     "@mastra/github": "latest",
     "@mastra/loggers": "latest",
     "@mastra/rag": "latest",
-    "@radix-ui/react-accordion": "^1.2.3",
-    "@radix-ui/react-dialog": "^1.1.6",
-    "@radix-ui/react-select": "^2.1.6",
-    "@radix-ui/react-slot": "^1.1.2",
+    "@radix-ui/react-accordion": "^1.2.11",
+    "@radix-ui/react-dialog": "^1.1.14",
+    "@radix-ui/react-select": "^2.2.5",
+    "@radix-ui/react-slot": "^1.2.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.454.0",

package/.docs/raw/client-js/overview.mdx

@@ -78,6 +78,22 @@ const client = new MastraClient({
 });
 ```
 
+## AbortSignal
+
+The Mastra Client SDK supports request cancellation using the standard Web API `AbortSignal`. Pass an `AbortSignal` to the client constructor to enable cancellation for all requests:
+
+```typescript
+const controller = new AbortController();
+
+const client = new MastraClient({
+  baseUrl: "http://localhost:4111",
+  abortSignal: controller.signal,
+});
+
+// Cancel all requests from this client
+controller.abort();
+```
+
 ## Example
 
 Once your MastraClient is initialized you can start making client calls via the type-safe

package/.docs/raw/deployment/cloud-providers/aws-lambda.mdx

@@ -0,0 +1,279 @@
+---
+title: "AWS Lambda"
+description: "Deploy your Mastra applications to AWS Lambda using Docker containers and the AWS Lambda Web Adapter."
+---
+
+import { Callout, Steps } from "nextra/components";
+
+## AWS Lambda
+
+Deploy your Mastra applications to AWS Lambda using Docker containers and the AWS Lambda Web Adapter.
+This approach allows you to run your Mastra server as a containerized Lambda function with automatic scaling.
+
+<Callout>
+  This guide assumes your Mastra application has been created using the default
+  `npx create-mastra@latest` command.
+  For more information on how to create a new Mastra application,
+  refer to our [getting started guide](/docs/getting-started/installation)
+</Callout>
+
+### Prerequisites
+
+Before deploying to AWS Lambda, ensure you have:
+
+- [AWS CLI](https://aws.amazon.com/cli/) installed and configured
+- [Docker](https://www.docker.com/) installed and running
+- An AWS account with appropriate permissions for Lambda, ECR, and IAM
+- Your Mastra application configured with appropriate memory storage
+
+### Memory Configuration
+
+<Callout>
+  AWS Lambda uses an ephemeral file system,
+  meaning that any files written to the file system are short-lived and may be lost.
+  Avoid using a Mastra storage provider that uses the file system,
+  such as `LibSQLStore` with a file URL.
+</Callout>
+
+Lambda functions have limitations with file system storage. Configure your Mastra application to use either in-memory or external storage providers:
+
+#### Option 1: In-Memory (Simplest)
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: ":memory:", // in-memory storage
+});
+```
+
+#### Option 2: External Storage Providers
+
+For persistent memory across Lambda invocations, use external storage providers like `LibSQLStore` with Turso or other storage providers like `PostgreStore`:
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  url: "libsql://your-database.turso.io", // External Turso database
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+For more memory configuration options, see the [Memory documentation](/docs/memory/overview).
+
+### Creating a Dockerfile
+
+<Steps>
+
+#### Create a Dockerfile in your project root
+
+Create a `Dockerfile` in your Mastra project root directory:
+
+```dockerfile filename="Dockerfile" copy showLineNumbers
+FROM node:22-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY src ./src
+RUN npx mastra build
+RUN apk add --no-cache gcompat
+
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 /lambda-adapter /opt/extensions/lambda-adapter
+RUN addgroup -g 1001 -S nodejs && \
+  adduser -S mastra -u 1001 && \
+  chown -R mastra:nodejs /app
+
+USER mastra
+
+ENV PORT=8080
+ENV NODE_ENV=production
+ENV READINESS_CHECK_PATH="/api"
+
+EXPOSE 8080
+
+CMD ["node", "--import=./.mastra/output/instrumentation.mjs", ".mastra/output/index.mjs"]
+```
+
+</Steps>
+
+### Building and Deploying
+
+<Steps>
+
+#### Set up environment variables
+
+Set up your environment variables for the deployment process:
+
+```bash copy
+export PROJECT_NAME="your-mastra-app"
+export AWS_REGION="us-east-1"
+export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
+```
+
+#### Build the Docker image
+
+Build your Docker image locally:
+
+```bash copy
+docker build -t "$PROJECT_NAME" .
+```
+
+#### Create an ECR repository
+
+Create an Amazon ECR repository to store your Docker image:
+
+```bash copy
+aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"
+```
+
+#### Authenticate Docker with ECR
+
+Log in to Amazon ECR:
+
+```bash copy
+aws ecr get-login-password --region "$AWS_REGION" | docker login --username AWS --password-stdin "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"
+```
+
+#### Tag and push the image
+
+Tag your image with the ECR repository URI and push it:
+
+```bash copy
+docker tag "$PROJECT_NAME":latest "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
+docker push "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
+```
+
+#### Create the Lambda function
+
+Create a Lambda function using the AWS Console:
+
+1. Navigate to the [AWS Lambda Console](https://console.aws.amazon.com/lambda/)
+2. Click **Create function**
+3. Select **Container image**
+4. Configure the function:
+   - **Function name**: Your function name (e.g., `mastra-app`)
+   - **Container image URI**: Click **Browse images** and select your ECR repository, then choose the `latest` tag
+   - **Architecture**: Select the architecture that matches your Docker build (typically `x86_64`)
+
+#### Configure Function URL
+
+Enable Function URL for external access:
+
+1. In the Lambda function configuration, go to **Configuration** > **Function URL**
+2. Click **Create function URL**
+3. Set **Auth type** to **NONE** (for public access)
+4. Configure **CORS** settings:
+   - **Allow-Origin**: `*` (restrict to your domain in production)
+   - **Allow-Headers**: `content-type`
+   - **Allow-Methods**: `*` (audit and restrict in production)
+5. Click **Save**
+
+#### Configure environment variables
+
+Add your environment variables in the Lambda function configuration:
+
+1. Go to **Configuration** > **Environment variables**
+2. Add the required variables for your Mastra application:
+   - `OPENAI_API_KEY`: Your OpenAI API key (if using OpenAI)
+   - `ANTHROPIC_API_KEY`: Your Anthropic API key (if using Anthropic)
+   - `TURSO_AUTH_TOKEN`: Your Turso auth token (if using LibSQL with Turso)
+   - Other provider-specific API keys as needed
+
+#### Adjust function settings
+
+Configure the function's memory and timeout settings:
+
+1. Go to **Configuration** > **General configuration**
+2. Set the following recommended values:
+   - **Memory**: 512 MB (adjust based on your application needs)
+   - **Timeout**: 30 seconds (adjust based on your application needs)
+   - **Ephemeral storage**: 512 MB (optional, for temporary files)
+
+</Steps>
+
+### Testing your deployment
+
+Once deployed, test your Lambda function:
+
+1. Copy the **Function URL** from the Lambda console
+2. Visit the URL in your browser to see your Mastra's server home screen
+3. Test your agents and workflows using the generated API endpoints
+
+For more information about available API endpoints, see the [Server documentation](/docs/deployment/server).
+
+### Connecting your client
+
+Update your client application to use the Lambda function URL:
+
+```typescript filename="src/client.ts" copy showLineNumbers
+import { MastraClient } from "@mastra/client-js";
+
+const mastraClient = new MastraClient({
+  baseUrl: "https://your-function-url.lambda-url.us-east-1.on.aws",
+});
+```
+
+### Troubleshooting
+
+#### Function timeout errors
+
+If your Lambda function times out:
+
+- Increase the timeout value in **Configuration** > **General configuration**
+- Optimize your Mastra application for faster cold starts
+- Consider using provisioned concurrency for consistent performance
+
+#### Memory issues
+
+If you encounter memory-related errors:
+
+- Increase the memory allocation in **Configuration** > **General configuration**
+- Monitor memory usage in CloudWatch Logs
+- Optimize your application's memory usage
+
+#### CORS issues
+
+If you encounter CORS errors when accessing endpoints but not the home page:
+
+- Verify CORS headers are properly set in your Mastra server configuration
+- Check the Lambda Function URL CORS configuration
+- Ensure your client is making requests to the correct URL
+
+#### Container image issues
+
+If the Lambda function fails to start:
+
+- Verify the Docker image builds successfully locally
+- Check that the `CMD` instruction in your Dockerfile is correct
+- Review CloudWatch Logs for container startup errors
+- Ensure the Lambda Web Adapter is properly installed in the container
+
+### Production considerations
+
+For production deployments:
+
+#### Security
+
+- Restrict CORS origins to your trusted domains
+- Use AWS IAM roles for secure access to other AWS services
+- Store sensitive environment variables in AWS Secrets Manager or Parameter Store
+
+#### Monitoring
+
+- Enable CloudWatch monitoring for your Lambda function
+- Set up CloudWatch alarms for errors and performance metrics
+- Use AWS X-Ray for distributed tracing
+
+#### Scaling
+
+- Configure provisioned concurrency for predictable performance
+- Monitor concurrent executions and adjust limits as needed
+- Consider using Application Load Balancer for more complex routing needs
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)
+- [AWS Lambda documentation](https://docs.aws.amazon.com/lambda/)
+- [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)

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

@@ -30,7 +30,6 @@ Before you begin, ensure you have:
 
 Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
 
-
 ```diff filename="src/mastra/index.ts" showLineNumbers
 export const mastra = new Mastra({
   // ...

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -189,6 +189,103 @@ export default function Page() {
 }
 ```
 
+### With additional data / RuntimeContext
+
+You can send additional data via the UI hooks that can be leveraged in Mastra as RuntimeContext using the `sendExtraMessageFields` option.
+
+#### Frontend: Using sendExtraMessageFields
+
+```typescript
+import { useChat } from '@ai-sdk/react';
+
+export function ChatComponent() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+    sendExtraMessageFields: true, // Enable sending extra fields
+  });
+
+  const handleFormSubmit = (e: React.FormEvent) => {
+        e.preventDefault();        
+        handleSubmit(e,{
+            // Add context data to the message
+            data: {
+                userId: 'user123',
+                preferences: { language: 'en', temperature: 'celsius' },
+            },
+        });
+  };
+
+  return (
+    <form onSubmit={handleFormSubmit}>
+      <input value={input} onChange={handleInputChange} />
+    </form>
+  );
+}
+```
+
+#### Backend: Handling in API Route
+
+```typescript filename="app/api/chat/route.ts" copy
+import { mastra } from "@/src/mastra";
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+export async function POST(req: Request) {
+  const { messages, data } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  
+  const runtimeContext = new RuntimeContext();
+  
+  if (data) {
+    Object.entries(data).forEach(([key, value]) => {
+      runtimeContext.set(key, value);
+    });
+  }
+  
+  const stream = await myAgent.stream(messages, { runtimeContext });
+  return stream.toDataStreamResponse();
+}
+```
+
+#### Alternative: Server Middleware
+
+You can also handle this at the server middleware level:
+
+```typescript filename="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+  server: {
+    middleware: [
+      async (c, next) => {
+        const runtimeContext = c.get("runtimeContext");
+        
+        if (c.req.method === 'POST') {
+          try {
+            // Clone the request since reading the body can only be done once
+            const clonedReq = c.req.raw.clone();
+            const body = await clonedReq.json();
+            
+            
+            if (body?.data) {
+              Object.entries(body.data).forEach(([key, value]) => {
+                runtimeContext.set(key, value);
+              });
+            }
+          } catch {
+            // Continue without additional data
+          }
+        }
+        
+        await next();
+      },
+    ],
+  },
+});
+```
+
+You can then access this data in your tools via the `runtimeContext` parameter. See the [Runtime Context documentation](/docs/agents/runtime-variables) for more details.
+
 ## Tool Calling
 
 ### AI SDK Tool Format

package/.docs/raw/frameworks/agentic-uis/assistant-ui.mdx

@@ -69,6 +69,40 @@ You now have a basic Mastra server project ready. You should have the following
 Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
 </Callout>
 
+### Compatibility Fix
+
+Currently, to ensure proper compatibility between Mastra and Assistant UI, you need to setup server middleware. Update your `/mastra/index.ts` file with the following configuration:
+
+```typescript showLineNumbers copy filename="src/mastra/index.ts"
+export const mastra = new Mastra({
+  //mastra server middleware
+  server:{
+  middleware: [{
+    path: '/api/agents/*/stream',
+    handler: async (c,next)=>{
+    
+      const body = await c.req.json();
+  
+      if ('state' in body && body.state == null) {
+        delete body.state;
+        delete body.tools;
+      }
+  
+       c.req.json = async() => body;
+  
+      return next()
+    }
+  }]
+ },
+});
+```
+
+This middleware ensures that when Assistant UI sends a request with `state: null` and `tools: {}` in the request body, we remove those properties to make the request work properly with Mastra.
+
+<Callout type="info">
+The `state: null` property can cause errors like `Cannot use 'in' operator to search for 'input' in null` in Mastra. Additionally, passing `tools: {}` overrides Mastra's built-in tools. Mastra only supports `clientTools` via the Mastra client SDK from the client side. For more information about client tools, see the [Client Tools documentation](/reference/client-js/agents#client-tools).
+</Callout>
+
 ### Run the Mastra Server
 
 Run the Mastra server using the following command:

package/.docs/raw/local-dev/mastra-dev.mdx

@@ -4,6 +4,7 @@ description: Documentation for the Mastra local development environment for Mast
 ---
 
 import YouTube from "@/components/youtube";
+import { VideoPlayer } from "@/components/video-player"
 import { Tabs, Tab } from "@/components/tabs";
 
 # Playground
@@ -42,7 +43,9 @@ The Playground lets you interact with your agents, workflows, and tools. It prov
 
 Quickly test and debug your agents during development using the interactive chat interface in the Agent Playground.
 
-![Agents Playground](/image/local-dev/local-dev-agents-playground.jpg)
+<VideoPlayer
+  src="https://res.cloudinary.com/dygi6femd/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4"
+/>
 
 Key features:
 
@@ -56,7 +59,9 @@ Key features:
 
 Validate workflows by supplying defined inputs and visualizing each step within the Workflow Playground.
 
-![Workflows Playground](/image/local-dev/local-dev-workflow-playground.jpg)
+<VideoPlayer
+  src="https://res.cloudinary.com/dygi6femd/video/upload/v1751406027/local-dev-workflows-playground_100_rbc466.mp4"
+/>
 
 Key features:
 
@@ -70,7 +75,9 @@ Key features:
 
 Quickly test and debug custom tools in isolation using the Tools Playground, without running a full agent or workflow.
 
-![Tools Playground](/image/local-dev/local-dev-tools-playground.jpg)
+<VideoPlayer
+  src="https://res.cloudinary.com/dygi6femd/video/upload/v1751406316/local-dev-agents-tools_100_fe1jdt.mp4"
+/>
 
 Key features:
 

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

@@ -96,7 +96,7 @@ const memory = new Memory({
 });
 ```
 
-By default, title generation uses the same model as your agent. For cost optimization, you can specify a cheaper model specifically for title generation:
+By default, title generation uses the same model and default instructions as your agent. For customization or cost optimization, you can specify a different model or provide custom instructions specifically for title generation:
 
 ```typescript {5-7}
 const memory = new Memory({
@@ -104,6 +104,7 @@ const memory = new Memory({
     threads: {
       generateTitle: {
         model: openai("gpt-4.1-nano"), // Use cheaper model for titles
+        instructions: "Generate a concise title for this conversation based on the first user message.",
       },
     },
   },

package/.docs/raw/reference/agents/generate.mdx

@@ -265,10 +265,11 @@ Configuration options for memory management:
           parameters: [
             {
               name: "generateTitle",
-              type: "boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>) }",
+              type: "boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>), instructions: string | ((ctx: RuntimeContext) => string | Promise<string>) }",
               isOptional: true,
               description:
-                "Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object with a custom model for title generation (useful for cost optimization). Example: { model: openai('gpt-4.1-nano') }",
+                `Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model and/or custom instructions for title generation (useful for cost optimization or title customization).
+Example: { model: openai('gpt-4.1-nano'), instructions: 'Generate a concise title based on the initial user message.' }`,
             },
           ],
         },

package/.docs/raw/reference/agents/stream.mdx

@@ -271,10 +271,11 @@ Configuration options for memory management:
           parameters: [
             {
               name: "generateTitle",
-              type: "boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>) }",
+              type: "boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>), instructions: string | ((ctx: RuntimeContext) => string | Promise<string>) }",
               isOptional: true,
               description:
-                "Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object with a custom model for title generation (useful for cost optimization). Example: { model: openai('gpt-4.1-nano') }",
+                `Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model and/or custom instructions for title generation (useful for cost optimization or title customization).
+Example: { model: openai('gpt-4.1-nano'), instructions: 'Generate a concise title based on the initial user message.' }`,
             },
           ],
         },

package/.docs/raw/reference/cli/dev.mdx

@@ -48,6 +48,18 @@ mastra dev [options]
       description: "Path to custom environment file",
       isOptional: true,
     },
+    {
+      name: "--inspect",
+      type: "boolean", 
+      description: "Start the dev server in inspect mode for debugging (cannot be used with --inspect-brk)",
+      isOptional: true,
+    },
+    {
+      name: "--inspect-brk",
+      type: "boolean",
+      description: "Start the dev server in inspect mode and break at the beginning of the script (cannot be used with --inspect)",
+      isOptional: true,
+    },
     {
       name: "--help",
       type: "boolean",

package/.docs/raw/reference/legacyWorkflows/createRun.mdx

@@ -74,7 +74,3 @@ try {
 - [Workflow Class Reference](./workflow.mdx)
 - [Step Class Reference](./step-class.mdx)
 - See the [Creating a Workflow](../../examples/workflows_legacy/creating-a-workflow.mdx) example for complete usage
-
-```
-
-```