@mastra/mcp-docs-server 0.13.4 → 0.13.5

package/.docs/raw/community/licensing.mdx

@@ -5,36 +5,39 @@ description: "Mastra License"
 
 # License
 
-## Elastic License 2.0 (ELv2)
+## Apache License 2.0
 
-Mastra is licensed under the Elastic License 2.0 (ELv2), a modern license designed to balance open-source principles with sustainable business practices.
+Mastra is licensed under the Apache License 2.0, a permissive open-source license that provides users with broad rights to use, modify, and distribute the software.
 
-### What is Elastic License 2.0?
+### What is Apache License 2.0?
 
-The Elastic License 2.0 is a source-available license that grants users broad rights to use, modify, and distribute the software while including specific limitations to protect the project's sustainability. It allows:
+The Apache License 2.0 is a permissive open-source license that grants users extensive rights to use, modify, and distribute the software. It allows:
 
-- Free use for most purposes
+- Free use for any purpose, including commercial use
 - Viewing, modifying, and redistributing the source code
 - Creating and distributing derivative works
-- Commercial use within your organization
+- Commercial use without restrictions
+- Patent protection from contributors
 
-The primary limitation is that you cannot provide Mastra as a hosted or managed service that offers users access to the substantial functionality of the software.
+The Apache License 2.0 is one of the most permissive and business-friendly open-source licenses available.
 
-### Why We Chose Elastic License 2.0
+### Why We Chose Apache License 2.0
 
-We selected the Elastic License 2.0 for several important reasons:
+We selected the Apache License 2.0 for several important reasons:
 
-1. **Sustainability**: It enables us to maintain a healthy balance between openness and the ability to sustain long-term development.
+1. **True Open Source**: It's a recognized open-source license that aligns with open-source principles and community expectations.
 
-2. **Innovation Protection**: It ensures we can continue investing in innovation without concerns about our work being repackaged as competing services.
+2. **Business Friendly**: It allows for unrestricted commercial use and distribution, making it ideal for businesses of all sizes.
 
-3. **Community Focus**: It maintains the spirit of open source by allowing users to view, modify, and learn from our code while protecting our ability to support the community.
+3. **Patent Protection**: It includes explicit patent protection for users, providing additional legal security.
 
-4. **Business Clarity**: It provides clear guidelines for how Mastra can be used in commercial contexts.
+4. **Community Focus**: It encourages community contributions and collaboration without restrictions.
+
+5. **Widely Adopted**: It's one of the most popular and well-understood open-source licenses in the industry.
 
 ### Building Your Business with Mastra
 
-Despite the licensing restrictions, there are numerous ways to build successful businesses using Mastra:
+The Apache License 2.0 provides maximum flexibility for building businesses with Mastra:
 
 #### Allowed Business Models
 
@@ -43,6 +46,8 @@ Despite the licensing restrictions, there are numerous ways to build successful
 - **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
 - **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
 - **Training and Education**: Offer courses and educational materials about using Mastra effectively
+- **Hosted Services**: Offer Mastra as a hosted or managed service
+- **SaaS Platforms**: Build SaaS platforms powered by Mastra
 
 #### Examples of Compliant Usage
 
@@ -50,14 +55,17 @@ Despite the licensing restrictions, there are numerous ways to build successful
 - A consulting firm offers implementation and customization services for Mastra
 - A developer creates specialized agents and tools with Mastra and licenses them to other businesses
 - A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
+- A company offers Mastra as a hosted service to their customers
+- A SaaS platform integrates Mastra as their AI backend
 
-#### What to Avoid
+#### Compliance Requirements
 
-The main restriction is that you cannot offer Mastra itself as a hosted service where users access its core functionality. This means:
+The Apache License 2.0 has minimal requirements:
 
-- Don't create a SaaS platform that is essentially Mastra with minimal modifications
-- Don't offer a managed Mastra service where customers are primarily paying to use Mastra's features
+- **Attribution**: Maintain copyright notices and license information (including NOTICE file)
+- **State Changes**: If you modify the software, state that you have made changes
+- **Include License**: Include a copy of the Apache License 2.0 when distributing
 
 ### Questions About Licensing?
 
-If you have specific questions about how the Elastic License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting legitimate business use cases while protecting the sustainability of the project.
+If you have specific questions about how the Apache License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting all legitimate use cases while maintaining the open-source nature of the project.

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/cloud-providers/digital-ocean.mdx

@@ -100,7 +100,7 @@ The guide assumes your droplet runs Ubuntu 24+.
 
 You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.
 
-Refer to the [`MastraClient` documentation](../../client-js/overview.mdx) for more information.
+Refer to the [`MastraClient` documentation](/docs/server-db/mastra-client) for more information.
 
 ```typescript copy showLineNumbers
 import { MastraClient } from "@mastra/client-js";

package/.docs/raw/deployment/server-deployment.mdx

@@ -0,0 +1,56 @@
+---
+title: "Deploy A Mastra Server"
+description: "Deploy a Mastra server with middleware and other options"
+---
+
+# Deploy A Mastra Server
+
+Mastra builds to a standard Node.js server, so you can deploy it to any platform that supports Node.js applications.
+
+- Cloud VMs (AWS EC2, DigitalOcean Droplets, GCP Compute Engine)
+- Container platforms (Docker, Kubernetes)
+- Platform as a Service (Heroku, Railway)
+- Self-hosted servers
+
+See the [Cloud Providers](/docs/deployment/cloud-providers/) for more information.
+
+### Building
+
+Build the application:
+
+```bash copy
+# Build from current directory
+mastra build
+
+# Or specify a directory
+mastra build --dir ./my-project
+```
+
+The build process:
+
+1. Locates entry file (`src/mastra/index.ts` or `src/mastra/index.js`)
+2. Creates `.mastra` output directory
+3. Bundles code using Rollup with tree shaking and source maps
+4. Generates [Hono](https://hono.dev) HTTP server
+
+See [`mastra build`](/reference/cli/build) for all options.
+
+### Running the Server
+
+Start the HTTP server:
+
+```bash copy
+node .mastra/output/index.mjs
+```
+
+### Enable Telemetry for build output
+
+Load instrumentation for the build output like so:
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs
+```
+
+## Serverless Deployment
+
+Mastra also supports serverless deployment on Cloudflare Workers, Vercel, and Netlify. See [Serverless Platforms](/docs/deployment/serverless-platforms/) for more information.

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/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/rag/retrieval.mdx

@@ -456,7 +456,10 @@ Here's how to use re-ranking:
 
 ```ts showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
-import { rerank } from "@mastra/rag";
+import { 
+  rerankWithScorer as rerank, 
+  MastraAgentRelevanceScorer 
+} from "@mastra/rag";
 
 // Get initial results from vector search
 const initialResults = await pgVector.query({
@@ -465,19 +468,35 @@ const initialResults = await pgVector.query({
   topK: 10,
 });
 
+// Create a relevance scorer
+const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', openai("gpt-4o-mini"));
+
 // Re-rank the results
-const rerankedResults = await rerank(
-  initialResults,
+const rerankedResults = await rerank({
+  results: initialResults,
   query,
-  openai("gpt-4o-mini"),
+  provider: relevanceProvider,
+  options: {
+    topK: 10,
+  },
 );
 ```
 
 > **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
+You can also use other relevance score providers like Cohere or ZeroEntropy:
+
+```ts showLineNumbers copy
+const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5');
+```
+
+```ts showLineNumbers copy
+const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1');
+```
+
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
-For more details about re-ranking, see the [rerank()](/reference/rag/rerank) method.
+For more details about re-ranking, see the [rerank()](/reference/rag/rerankWithScorer) method.
 
 For an example of how to use the re-ranking method, see the [Re-ranking Results](../../examples/rag/rerank/rerank.mdx) example.
 

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.' }`,
             },
           ],
         },