@mastra/mcp-docs-server 0.13.1-alpha.0 → 0.13.1-alpha.2

package/.docs/raw/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -0,0 +1,28 @@
+# Advanced Configuration of Semantic Recall
+
+We can configure semantic recall in more detail by setting options for the `semanticRecall` option:
+
+```typescript
+const memory = new Memory({
+  storage: new LibSQLStore({
+    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+  }),
+  embedder: openai.embedding("text-embedding-3-small"),
+  options: {
+    semanticRecall: {
+      topK: 3,
+      messageRange: {
+        before: 2,
+        after: 1,
+      },
+    },
+  },
+});
+```
+
+The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information. The default value is `2`.
+
+The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.

package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md

@@ -6,11 +6,18 @@ Let's update our agent with working memory capabilities:
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a memory instance with working memory configuration
 const memory = new Memory({
+  storage: new LibSQLStore({
+    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
+  }), // Storage for message history
+  vector: new LibSQLVector({
+    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+  }), // Vector database for semantic search
+  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
   options: {
-    lastMessages: 20,
     semanticRecall: {
       topK: 3,
       messageRange: {
@@ -20,7 +27,6 @@ const memory = new Memory({
     },
     workingMemory: {
       enabled: true,
-      use: "tool-call", // Recommended setting
     },
   },
 });
@@ -52,12 +58,6 @@ export const memoryAgent = new Agent({
 The `workingMemory` configuration has several important options:
 
 - `enabled`: Whether working memory is enabled
-- `use`: How the agent interacts with working memory (recommended setting is "tool-call")
-
-The `use` option can be set to:
-
-- `"tool-call"`: The agent updates working memory via tool calls (recommended)
-- `"direct"`: The agent directly edits the working memory text
-- `"read-only"`: The agent can read but not update working memory
+- `template`: A template for the working memory content
 
 The instructions for the agent are also important. They guide the agent on what information to store in working memory and how to use that information when responding to the user.

package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md

@@ -11,8 +11,14 @@ import { openai } from "@ai-sdk/openai";
 
 // Create a memory instance with a custom working memory template
 const memory = new Memory({
+  storage: new LibSQLStore({
+    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
+  }), // Storage for message history
+  vector: new LibSQLVector({
+    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+  }), // Vector database for semantic search
+  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
   options: {
-    lastMessages: 20,
     semanticRecall: {
       topK: 3,
       messageRange: {
@@ -22,7 +28,9 @@ const memory = new Memory({
     },
     workingMemory: {
       enabled: true,
-      use: "tool-call",
+    },
+    workingMemory: {
+      enabled: true,
       template: `
 # User Profile
 

package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md

@@ -11,9 +11,17 @@ Let's create a comprehensive agent that utilizes conversation history, semantic
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a comprehensive memory configuration
 const memory = new Memory({
+  storage: new LibSQLStore({
+    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+  }),
+  embedder: openai.embedding("text-embedding-3-small"),
   options: {
     // Conversation history configuration
     lastMessages: 20, // Include the last 20 messages in the context
@@ -30,7 +38,6 @@ const memory = new Memory({
     // Working memory configuration
     workingMemory: {
       enabled: true,
-      use: "tool-call",
       template: `
 # User Profile
 

package/.docs/raw/course/03-agent-memory/27-creating-learning-assistant.md

@@ -7,9 +7,17 @@ Let's create a practical example of a memory-enhanced agent: a Personal Learning
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
 // Create a specialized memory configuration for the learning assistant
 const learningMemory = new Memory({
+  storage: new LibSQLStore({
+    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
+  }),
+  embedder: openai.embedding("text-embedding-3-small"),
   options: {
     lastMessages: 20,
     semanticRecall: {
@@ -21,7 +29,6 @@ const learningMemory = new Memory({
     },
     workingMemory: {
       enabled: true,
-      use: "tool-call",
       template: `
 # Learner Profile
 

package/.docs/raw/deployment/deployment.mdx

@@ -5,7 +5,9 @@ description: "Build and deploy Mastra applications using platform-specific deplo
 
 # Serverless Deployment
 
-This guide covers deploying Mastra to Cloudflare Workers, Vercel, and Netlify using platform-specific deployers
+This guide covers deploying standalone Mastra applications to Cloudflare Workers, Vercel, and Netlify using platform-specific deployers.
+
+Deployers **aren't** required when integrating Mastra with a framework. See [Web Framework Integration](/docs/deployment/web-framework) for more information.
 
 For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/deployment/server) guide.
 
@@ -18,112 +20,39 @@ Before you begin, ensure you have:
   - An account with your chosen platform
   - Required API keys or credentials
 
-## Serverless Platform Deployers
-
-Platform-specific deployers handle configuration and deployment for:
-
-- **[Cloudflare Workers](/reference/deployer/cloudflare)**
-- **[Vercel](/reference/deployer/vercel)**
-- **[Netlify](/reference/deployer/netlify)**
-- **[Mastra Cloud](/docs/mastra-cloud/overview)** _(beta)_. You can join the [cloud waitlist](https://mastra.ai/cloud-beta) for early access.
-
-### Installing Deployers
+## LibSQLStore
 
-```bash copy
-# For Cloudflare
-npm install @mastra/deployer-cloudflare@latest
+`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`.
 
-# For Vercel
-npm install @mastra/deployer-vercel@latest
+Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
 
-# For Netlify
-npm install @mastra/deployer-netlify@latest
-```
-
-### Configuring Deployers
-
-Configure the deployer in your entry file:
-
-```typescript copy showLineNumbers
-import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/loggers";
-import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
 
+```diff filename="src/mastra/index.ts" showLineNumbers
 export const mastra = new Mastra({
-  agents: {
-    /* your agents here */
-  },
-  logger: new PinoLogger({ name: "MyApp", level: "debug" }),
-  deployer: new CloudflareDeployer({
-    scope: "your-cloudflare-scope",
-    projectName: "your-project-name",
-    // See complete configuration options in the reference docs
-  }),
+  // ...
+-  storage: new LibSQLStore({
+-    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
+-    url: ":memory:",
+-  })
 });
 ```
 
-### Deployer Configuration
-
-Each deployer has specific configuration options. Below are basic examples, but refer to the reference documentation for complete details.
-
-#### Cloudflare Deployer
-
-```typescript copy showLineNumbers
-new CloudflareDeployer({
-  scope: "your-cloudflare-account-id",
-  projectName: "your-project-name",
-  // For complete configuration options, see the reference documentation
+``` diff filename="src/mastra/agents/weather-agent.ts" showLineNumbers
+export const weatherAgent = new Agent({
+  // ..
+-  memory: new Memory({
+-    storage: new LibSQLStore({
+-      url: "file:../mastra.db" // path is relative to the .mastra/output directory
+-    })
+-  })
 });
 ```
 
-[View Cloudflare Deployer Reference →](/reference/deployer/cloudflare)
-
-#### Vercel Deployer
-
-```typescript copy showLineNumbers
-new VercelDeployer({
-  teamSlug: "your-vercel-team-slug",
-  projectName: "your-project-name",
-  token: "your-vercel-token",
-  // For complete configuration options, see the reference documentation
-});
-```
-
-[View Vercel Deployer Reference →](/reference/deployer/vercel)
-
-#### Netlify Deployer
-
-```typescript copy showLineNumbers
-new NetlifyDeployer({
-  scope: "your-netlify-team-slug",
-  projectName: "your-project-name",
-  token: "your-netlify-token",
-});
-```
-
-[View Netlify Deployer Reference →](/reference/deployer/netlify)
-
-## Environment Variables
-
-Required variables:
-
-1. Platform deployer variables (if using platform deployers):
-   - Platform credentials
-2. Agent API keys:
-   - `OPENAI_API_KEY`
-   - `ANTHROPIC_API_KEY`
-3. Server configuration (for universal deployment):
-   - `PORT`: HTTP server port (default: 3000)
-   - `HOST`: Server host (default: 0.0.0.0)
-
-## Build Mastra Project
-
-To build your Mastra project for your target platform run:
+## Serverless Platform Deployers
 
-```bash
-npx mastra build
-```
+Platform-specific deployers handle configuration and deployment for:
 
-When a Deployer is used, the build output is automatically prepared for the target platform.
-You can then deploy the build output `.mastra/output` via your platform's (Vercel, netlify, cloudfare e.t.c)
-CLI/UI.
+- **[Cloudflare Workers](/reference/deployer/cloudflare)**
+- **[Vercel](/reference/deployer/vercel)**
+- **[Netlify](/reference/deployer/netlify)**
+- **[Mastra Cloud](/docs/mastra-cloud/overview)** _(beta)_. You can join the [cloud waitlist](https://mastra.ai/cloud-beta) for early access.

package/.docs/raw/deployment/overview.mdx

@@ -5,7 +5,7 @@ description: Learn about different deployment options for your Mastra applicatio
 
 # Deployment Overview
 
-Mastra offers multiple deployment options to suit your application's needs, from fully-managed solutions to self-hosted options. This guide will help you understand the available deployment paths and choose the right one for your project.
+Mastra offers multiple deployment options to suit your application's needs, from fully-managed solutions to self-hosted options, and web framework integrations. This guide will help you understand the available deployment paths and choose the right one for your project.
 
 ## Deployment Options
 
@@ -21,6 +21,18 @@ Mastra Cloud is a deployment platform that connects to your GitHub repository, a
 
 [View Mastra Cloud documentation →](/docs/mastra-cloud/overview)
 
+
+### With a Web Framework
+
+Mastra can be integrated with a variety of web frameworks. For example, see one of the following for a detailed guide.
+
+- [With Next.js](/docs/frameworks/web-frameworks/next-js)
+- [With Astro](/docs/frameworks/web-frameworks/astro)
+
+When integrated with a framework, Mastra typically requires no additional configuration for deployment.
+
+[View Web Framework Integration →](/docs/deployment/web-framework)
+
 ### With a Server
 
 You can deploy Mastra as a standard Node.js HTTP server, which gives you full control over your infrastructure and deployment environment.
@@ -56,8 +68,11 @@ Once your Mastra application is deployed, you'll need to configure your client t
 
 ## Choosing a Deployment Option
 
-| Option                   | Best For                                                      | Key Benefits                                                   |
+| Option                   | Best For                                                      | Key Benefits                                                    |
 | ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
 | **Mastra Cloud**         | Teams wanting to ship quickly without infrastructure concerns | Fully-managed, automatic scaling, built-in observability       |
+| **Framework Deployment** | Teams already using Next.js, Astro etc                          | Simplify deployment with a unified codebase for frontend and backend  |
 | **Server Deployment**    | Teams needing maximum control and customization               | Full control, custom middleware, integrate with existing apps  |
-| **Serverless Platforms** | Teams already using Vercel, Netlify, or Cloudflare            | Platform integration, simplified deployment, automatic scaling |
+| **Serverless Platforms** | Teams already using Vercel, Netlify, or Cloudflare             | Platform integration, simplified deployment, automatic scaling  |
+
+

package/.docs/raw/deployment/web-framework.mdx

@@ -0,0 +1,63 @@
+---
+title: "Deploying Mastra with a Web Framework"
+description: "Learn how Mastra can be deployed when integrated with a Web Framework"
+---
+
+# Web Framework Integration
+
+This guide covers deploying integrated Mastra applications. Mastra can be integrated with a variety of web frameworks, see one of the following for a detailed guide.
+
+- [With Next.js](/docs/frameworks/web-frameworks/next-js)
+- [With Astro](/docs/frameworks/web-frameworks/astro)
+
+When integrated with a framework, Mastra typically requires no additional configuration for deployment.
+
+## With Next.js on Vercel
+
+If you've integrated Mastra with Next.js [by following our guide](/docs/frameworks/web-frameworks/next-js) and plan to deploy to Vercel, no additional setup is required.
+
+The only thing to verify is that you've added the following to your `next.config.ts` and removed any usage of [LibSQLStore](/docs/deployment/deployment#libsqlstore), which is not supported in serverless environments:
+
+```typescript {4} filename="next.config.ts" showLineNumbers copy
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: ["@mastra/*"],
+};
+
+export default nextConfig;
+```
+
+## With Astro on Vercel
+
+If you've integrated Mastra with Astro [by following our guide](/docs/frameworks/web-frameworks/astro) and plan to deploy to Vercel, no additional setup is required.
+
+The only thing to verify is that you've added the following to your `astro.config.mjs` and removed any usage of [LibSQLStore](/docs/deployment/deployment#libsqlstore), which is not supported in serverless environments:
+
+```javascript {2,6,7} filename="astro.config.mjs" showLineNumbers copy
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel';
+
+export default defineConfig({
+  // ...
+  adapter: vercel(),
+  output: "server"
+});
+```
+
+## With Astro on Netlify
+
+If you've integrated Mastra with Astro [by following our guide](/docs/frameworks/web-frameworks/astro) and plan to deploy to Vercel, no additional setup is required.
+
+The only thing to verify is that you've added the following to your `astro.config.mjs` and removed any usage of [LibSQLStore](/docs/deployment/deployment#libsqlstore), which is not supported in serverless environments:
+
+```javascript {2,6,7} filename="astro.config.mjs" showLineNumbers copy
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/netlify';
+
+export default defineConfig({
+  // ...
+  adapter: netlify(),
+  output: "server"
+});
+```

package/.docs/raw/frameworks/web-frameworks/astro.mdx

@@ -109,10 +109,11 @@ OPENAI_API_KEY=<your-api-key>
 
 ## Update .gitignore
 
-Add `.mastra` to your `.gitignore` file:
+Add `.mastra` and `.vercel` to your `.gitignore` file:
 
 ```bash filename=".gitignore" copy
 .mastra
+.vercel
 ```
 
 ## Update the Mastra Agent
@@ -365,6 +366,7 @@ Add `.mastra` to your `.gitignore` file:
 
 ```bash filename=".gitignore" copy
 .mastra
+.vercel
 ```
 
 ## Update the Mastra Agent
@@ -510,3 +512,7 @@ Let me know if you need more information!
   </Steps>
   </Tabs.Tab>
 </Tabs>
+
+## Next Steps
+
+- [Deployment | With Astro on Vercel](/docs/deployment/web-framework#with-astro-on-vercel)

package/.docs/raw/frameworks/web-frameworks/next-js.mdx

@@ -491,4 +491,4 @@ Let me know if you need more information!
 
 ## Next Steps
 
-- [Serverless Deployment](/docs/deployment/deployment)
+- [Deployment | With Next.js on Vercel](/docs/deployment/web-framework#with-nextjs-on-vercel)