@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/guides/guide/chef-michel.mdx

@@ -19,7 +19,7 @@ You'll learn how to create the agent and register it with Mastra. Next, you'll i
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Creating the Agent
 
@@ -32,7 +32,6 @@ To create an agent in Mastra use the `Agent` class to define it and then registe
 Create a new file `src/mastra/agents/chefAgent.ts` and define your agent:
 
 ```ts copy title="src/mastra/agents/chefAgent.ts"
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const chefAgent = new Agent({
@@ -41,7 +40,7 @@ export const chefAgent = new Agent({
   instructions:
     "You are Michel, a practical and experienced home chef" +
     "You help people cook with whatever ingredients they have available.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 ```
 

package/.docs/raw/guides/guide/notes-mcp-server.mdx

@@ -18,7 +18,7 @@ In this guide, you'll learn how to build a complete MCP (Model Context Protocol)
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Adding necessary dependencies & files
 
@@ -38,7 +38,7 @@ npm install @mastra/mcp@beta
 
 <StepItem>
 
-After following the default [installation guide](/guides/v1/quickstarts/standalone-server) your project will include files that are not relevant for this guide. You can safely remove them:
+After following the default [installation guide](/guides/v1/getting-started/quickstart) your project will include files that are not relevant for this guide. You can safely remove them:
 
 ```bash copy
 rm -rf src/mastra/agents src/mastra/workflows src/mastra/tools/weather-tool.ts

package/.docs/raw/guides/guide/research-assistant.mdx

@@ -16,7 +16,7 @@ You'll use the foundational Transformer paper ["Attention Is All You Need"](http
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## How RAG works
 
@@ -57,7 +57,7 @@ Let's define the agent's behavior, connect it to your Mastra project, and create
 
 Install additional dependencies
 
-After running the [installation guide](/guides/v1/quickstarts/standalone-server) you'll need to install additional dependencies:
+After running the [installation guide](/guides/v1/getting-started/quickstart) you'll need to install additional dependencies:
 
 ```bash copy
 npm install @mastra/rag@beta ai@^4.0.0
@@ -76,14 +76,14 @@ Create a new file `src/mastra/agents/researchAgent.ts` and define your agent:
 
 ```ts copy title="src/mastra/agents/researchAgent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 import { createVectorQueryTool } from "@mastra/rag";
 
 // Create a tool for semantic search over the paper embeddings
 const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "libSqlVector",
   indexName: "papers",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 export const researchAgent = new Agent({
@@ -94,7 +94,7 @@ export const researchAgent = new Agent({
     and provide accurate, well-supported answers based on the retrieved content.
     Focus on the specific content available in the tool and acknowledge if you cannot find sufficient information to answer a question.
     Base your responses only on the content provided, not on general knowledge.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: {
     vectorQueryTool,
   },
@@ -229,9 +229,8 @@ This allows the agent to efficiently search and retrieve relevant information.
 
 Open the `src/store.ts` file and add the following:
 
-```ts copy title="src/store.ts" {2-4, 20-99}
+```ts copy title="src/store.ts"
 import { MDocument } from "@mastra/rag";
-import { openai } from "@ai-sdk/openai";
 import { embedMany } from "ai";
 import { mastra } from "./mastra";
 
@@ -251,7 +250,7 @@ const chunks = await doc.chunk({
 
 // Generate embeddings
 const { embeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 

package/.docs/raw/guides/guide/stock-agent.mdx

@@ -17,7 +17,7 @@ In this guide, you're going to create a simple agent that fetches the last day's
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Creating the Agent
 
@@ -30,7 +30,6 @@ To create an agent in Mastra use the `Agent` class to define it and then registe
 Create a new file `src/mastra/agents/stockAgent.ts` and define your agent:
 
 ```ts copy title="src/mastra/agents/stockAgent.ts"
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const stockAgent = new Agent({
@@ -38,7 +37,7 @@ export const stockAgent = new Agent({
   name: "Stock Agent",
   instructions:
     "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -104,8 +103,7 @@ export const stockPrices = createTool({
 
 Inside `src/mastra/agents/stockAgent.ts` import your newly created `stockPrices` tool and add it to the agent.
 
-```ts copy title="src/mastra/agents/stockAgent.ts" {3, 10-12}
-import { openai } from "@ai-sdk/openai";
+```ts copy title="src/mastra/agents/stockAgent.ts" {9-11}
 import { Agent } from "@mastra/core/agent";
 import { stockPrices } from "../tools/stockPrices";
 
@@ -114,7 +112,7 @@ export const stockAgent = new Agent({
   name: "Stock Agent",
   instructions:
     "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: {
     stockPrices,
   },

package/.docs/raw/guides/guide/web-search.mdx

@@ -19,7 +19,7 @@ When building a web search agent, you have two main strategies to consider:
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Using native search tools
 
@@ -61,7 +61,7 @@ Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'openai/gpt-4o-mini',
+        model: "openai/gpt-5.1",
     });
     ```
 
@@ -76,7 +76,7 @@ Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'google/gemini-2.5-flash',
+        model: "google/gemini-2.5-flash",
     });
     ```
 
@@ -93,7 +93,7 @@ Setup the tool:
 <Tabs>
     <TabItem value="openai" label="Open AI">
 
-    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-12}
     import { openai } from "@ai-sdk/openai";
     import { Agent } from "@mastra/core/agent";
 
@@ -102,7 +102,7 @@ Setup the tool:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'openai/gpt-4o-mini',
+        model: "openai/gpt-5.1",
         tools: {
             webSearch: openai.tools.webSearch()
         }
@@ -112,7 +112,7 @@ Setup the tool:
     </TabItem>
     <TabItem value="gemini" label="Gemini">
 
-    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-14}
     import { google } from "@ai-sdk/google";
     import { Agent } from "@mastra/core/agent";
 
@@ -121,9 +121,11 @@ Setup the tool:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'google/gemini-2.5-flash',
+        model: "google/gemini-2.5-flash",
         tools: {
-            webSearch: google.tools.googleSearch()
+          webSearch: google.tools.googleSearch({
+            mode: "MODE_DYNAMIC"
+          })
         }
     });
     ```
@@ -191,7 +193,7 @@ export const searchAgent = new Agent({
   name: "Search Agent",
   instructions:
     "You are a search agent that can search the web for information.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -252,7 +254,7 @@ export const searchAgent = new Agent({
   name: "Search Agent",
   instructions:
     "You are a search agent that can search the web for information.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   tools: {
     webSearch,
   },

package/.docs/raw/guides/guide/whatsapp-chat-bot.mdx

@@ -0,0 +1,421 @@
+---
+title: "WhatsApp Chat Bot"
+description: Create a WhatsApp chat bot using Mastra agents and workflows to handle incoming messages and respond naturally via text messages.
+---
+
+# WhatsApp Chat Bot
+
+This guide demonstrates how to create a WhatsApp chat bot using Mastra agents and workflows. The bot receives incoming WhatsApp messages via webhook, processes them through an AI agent, breaks responses into natural text messages, and sends them back via the WhatsApp Business API.
+
+## Prerequisites
+
+This example requires a WhatsApp Business API setup and uses the `anthropic` model. Add these environment variables to your `.env` file:
+
+```bash title=".env" copy
+ANTHROPIC_API_KEY=<your-anthropic-api-key>
+WHATSAPP_VERIFY_TOKEN=<your-verify-token>
+WHATSAPP_ACCESS_TOKEN=<your-whatsapp-access-token>
+WHATSAPP_BUSINESS_PHONE_NUMBER_ID=<your-phone-number-id>
+WHATSAPP_API_VERSION=v22.0
+```
+
+## Creating the WhatsApp client
+
+This client handles sending messages to users via the WhatsApp Business API.
+
+```typescript title="src/whatsapp-client.ts" showLineNumbers copy
+// Simple WhatsApp Business API client for sending messages
+
+interface SendMessageParams {
+  to: string;
+  message: string;
+}
+
+export async function sendWhatsAppMessage({ to, message }: SendMessageParams) {
+  // Get environment variables for WhatsApp API
+  const apiVersion = process.env.WHATSAPP_API_VERSION || "v22.0";
+  const phoneNumberId = process.env.WHATSAPP_BUSINESS_PHONE_NUMBER_ID;
+  const accessToken = process.env.WHATSAPP_ACCESS_TOKEN;
+
+  // Check if required environment variables are set
+  if (!phoneNumberId || !accessToken) {
+    return false;
+  }
+
+  // WhatsApp Business API endpoint
+  const url = `https://graph.facebook.com/${apiVersion}/${phoneNumberId}/messages`;
+
+  // Message payload following WhatsApp API format
+  const payload = {
+    messaging_product: "whatsapp",
+    recipient_type: "individual",
+    to: to,
+    type: "text",
+    text: {
+      body: message,
+    },
+  };
+
+  try {
+    // Send message via WhatsApp Business API
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    const result = await response.json();
+
+    if (response.ok) {
+      console.log(`✅ WhatsApp message sent to ${to}: "${message}"`);
+      return true;
+    } else {
+      console.error("❌ Failed to send WhatsApp message:", result);
+      return false;
+    }
+  } catch (error) {
+    console.error("❌ Error sending WhatsApp message:", error);
+    return false;
+  }
+}
+```
+
+## Creating the chat agent
+
+This agent handles the main conversation logic with a friendly, conversational personality.
+
+```typescript title="src/mastra/agents/chat-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const chatAgent = new Agent({
+  id: "chat-agent",
+  name: "Chat Agent",
+  instructions: `
+    You are a helpful, friendly, and knowledgeable AI assistant that loves to chat with users via WhatsApp.
+
+    Your personality:
+    - Warm, approachable, and conversational
+    - Enthusiastic about helping with any topic
+    - Use a casual, friendly tone like you're chatting with a friend
+    - Be concise but informative
+    - Show genuine interest in the user's questions
+
+    Your capabilities:
+    - Answer questions on a wide variety of topics
+    - Provide helpful advice and suggestions
+    - Engage in casual conversation
+    - Help with problem-solving and creative tasks
+    - Explain complex topics in simple terms
+
+    Guidelines:
+    - Keep responses informative but not overwhelming
+    - Ask follow-up questions when appropriate
+    - Be encouraging and positive
+    - If you don't know something, admit it honestly
+    - Adapt your communication style to match the user's tone
+    - Remember this is WhatsApp, so keep it conversational and natural
+
+    Always aim to be helpful while maintaining a friendly, approachable conversation style.
+  `,
+  model: "anthropic/claude-4-sonnet-20250514",
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: "file:../mastra.db",
+    }),
+  }),
+});
+```
+
+## Creating the text message agent
+
+This agent converts longer responses into natural, bite-sized text messages suitable for WhatsApp.
+
+```typescript title="src/mastra/agents/text-message-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const textMessageAgent = new Agent({
+  id: "text-message-agent",
+  name: "Text Message Agent",
+  instructions: `
+    You are a text message converter that takes formal or lengthy text and breaks it down into natural, casual text messages.
+
+    Your job is to:
+    - Convert any input text into 5-8 short, casual text messages
+    - Each message should be 1-2 sentences maximum
+    - Use natural, friendly texting language (contractions, casual tone)
+    - Maintain all the important information from the original text
+    - Make it feel like you're texting a friend
+    - Use appropriate emojis sparingly to add personality
+    - Keep the conversational flow logical and easy to follow
+
+    Think of it like you're explaining something exciting to a friend via text - break it into bite-sized, engaging messages that don't overwhelm them with a long paragraph.
+
+    Always return exactly 5-8 messages in the messages array.
+  `,
+  model: "anthropic/claude-4-sonnet-20250514",
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: "file:../mastra.db",
+    }),
+  }),
+});
+```
+
+## Creating the chat workflow
+
+This workflow orchestrates the entire chat process: generating a response, breaking it into messages, and sending them via WhatsApp.
+
+```typescript title="src/mastra/workflows/chat-workflow.ts" showLineNumbers copy
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+import { sendWhatsAppMessage } from "../../whatsapp-client";
+
+const respondToMessage = createStep({
+  id: "respond-to-message",
+  description: "Generate response to user message",
+  inputSchema: z.object({ userMessage: z.string() }),
+  outputSchema: z.object({ response: z.string() }),
+  execute: async ({ inputData, mastra }) => {
+    const agent = mastra?.getAgent("chatAgent");
+    if (!agent) {
+      throw new Error("Chat agent not found");
+    }
+
+    const response = await agent.generate([
+      { role: "user", content: inputData.userMessage },
+    ]);
+
+    return { response: response.text };
+  },
+});
+
+const breakIntoMessages = createStep({
+  id: "break-into-messages",
+  description: "Breaks response into text messages",
+  inputSchema: z.object({ prompt: z.string() }),
+  outputSchema: z.object({ messages: z.array(z.string()) }),
+  execute: async ({ inputData, mastra }) => {
+    const agent = mastra?.getAgent("textMessageAgent");
+    if (!agent) {
+      throw new Error("Text Message agent not found");
+    }
+
+    const response = await agent.generate(
+      [{ role: "user", content: inputData.prompt }],
+      {
+        structuredOutput: {
+          schema: z.object({
+            messages: z.array(z.string()),
+          }),
+        },
+      },
+    );
+
+    if (!response.object) throw new Error("Error generating messages");
+
+    return response.object;
+  },
+});
+
+const sendMessages = createStep({
+  id: "send-messages",
+  description: "Sends text messages via WhatsApp",
+  inputSchema: z.object({
+    messages: z.array(z.string()),
+    userPhone: z.string(),
+  }),
+  outputSchema: z.object({ sentCount: z.number() }),
+  execute: async ({ inputData }) => {
+    const { messages, userPhone } = inputData;
+
+    console.log(
+      `\n🔥 Sending ${messages.length} WhatsApp messages to ${userPhone}...`,
+    );
+
+    let sentCount = 0;
+
+    // Send each message with a small delay for natural flow
+    for (let i = 0; i < messages.length; i++) {
+      const success = await sendWhatsAppMessage({
+        to: userPhone,
+        message: messages[i],
+      });
+
+      if (success) {
+        sentCount++;
+      }
+
+      // Add delay between messages for natural texting rhythm
+      if (i < messages.length - 1) {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+
+    console.log(
+      `\n✅ Successfully sent ${sentCount}/${messages.length} WhatsApp messages\n`,
+    );
+
+    return { sentCount };
+  },
+});
+
+export const chatWorkflow = createWorkflow({
+  id: "chat-workflow",
+  inputSchema: z.object({ userMessage: z.string() }),
+  outputSchema: z.object({ sentCount: z.number() }),
+})
+  .then(respondToMessage)
+  .map(async ({ inputData }) => ({
+    prompt: `Break this AI response into 3-8 casual, friendly text messages that feel natural for WhatsApp conversation:\n\n${inputData.response}`,
+  }))
+  .then(breakIntoMessages)
+  .map(async ({ inputData, getInitData }) => {
+    // Parse the original stringified input to get user phone
+    const initData = getInitData();
+    const webhookData = JSON.parse(initData.userMessage);
+    const userPhone =
+      webhookData.entry?.[0]?.changes?.[0]?.value?.messages?.[0]?.from ||
+      "unknown";
+
+    return {
+      messages: inputData.messages,
+      userPhone,
+    };
+  })
+  .then(sendMessages);
+
+chatWorkflow.commit();
+```
+
+## Setting up Mastra configuration
+
+Configure your Mastra instance with the agents, workflow, and WhatsApp webhook endpoints.
+
+```typescript title="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core";
+import { registerApiRoute } from "@mastra/core/server";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+
+import { chatWorkflow } from "./workflows/chat-workflow";
+import { textMessageAgent } from "./agents/text-message-agent";
+import { chatAgent } from "./agents/chat-agent";
+
+export const mastra = new Mastra({
+  workflows: { chatWorkflow },
+  agents: { textMessageAgent, chatAgent },
+  storage: new LibSQLStore({
+    id: 'agent-storage',
+    url: ":memory:",
+  }),
+  logger: new PinoLogger({
+    name: "Mastra",
+    level: "info",
+  }),
+  server: {
+    apiRoutes: [
+      registerApiRoute("/whatsapp", {
+        method: "GET",
+        handler: async (c) => {
+          const verifyToken = process.env.WHATSAPP_VERIFY_TOKEN;
+          const {
+            "hub.mode": mode,
+            "hub.challenge": challenge,
+            "hub.verify_token": token,
+          } = c.req.query();
+
+          if (mode === "subscribe" && token === verifyToken) {
+            return c.text(challenge, 200);
+          } else {
+            return c.status(403);
+          }
+        },
+      }),
+      registerApiRoute("/whatsapp", {
+        method: "POST",
+        handler: async (c) => {
+          const mastra = c.get("mastra");
+          const chatWorkflow = mastra.getWorkflow("chatWorkflow");
+
+          const body = await c.req.json();
+
+          const workflowRun = await chatWorkflow.createRun();
+          const runResult = await workflowRun.start({
+            inputData: { userMessage: JSON.stringify(body) },
+          });
+
+          return c.json(runResult);
+        },
+      }),
+    ],
+  },
+});
+```
+
+## Testing the chat bot
+
+You can test the chat bot locally by simulating a WhatsApp webhook payload.
+
+```typescript title="src/test-whatsapp-bot.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+// Simulate a WhatsApp webhook payload
+const mockWebhookData = {
+  entry: [
+    {
+      changes: [
+        {
+          value: {
+            messages: [
+              {
+                from: "1234567890", // Test phone number
+                text: {
+                  body: "Hello! How are you today?",
+                },
+              },
+            ],
+          },
+        },
+      ],
+    },
+  ],
+};
+
+const workflow = mastra.getWorkflow("chatWorkflow");
+const workflowRun = await workflow.createRun();
+
+const result = await workflowRun.start({
+  inputData: { userMessage: JSON.stringify(mockWebhookData) },
+});
+
+console.log("Workflow completed:", result);
+```
+
+## Example output
+
+When a user sends "Hello! How are you today?" to your WhatsApp bot, it might respond with multiple messages like:
+
+```text
+Hey there! 👋 I'm doing great, thanks for asking!
+
+How's your day going so far?
+
+I'm here and ready to chat about whatever's on your mind
+
+Whether you need help with something or just want to talk, I'm all ears! 😊
+
+What's new with you?
+```
+
+The bot maintains conversation context through memory and delivers responses that feel natural for WhatsApp messaging.