@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.10

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.

package/.docs/raw/guides/index.mdx

@@ -1,43 +1,11 @@
 ---
 title: "Overview"
 description: "Guides on building with Mastra"
+showCopyButton: false
 ---
 
 import { CardGrid, CardGridItem } from "@site/src/components/CardGrid";
 
-# Guides
+# Mastra Guides
 
-While examples show quick implementations and docs explain specific features, these guides are a bit longer and designed to demonstrate core Mastra concepts:
-
-<CardGrid>
-  <CardGridItem
-    title="AI Recruiter"
-    description="Create a workflow that processes candidate resumes and conducts interviews, demonstrating branching logic and LLM integration in Mastra workflows."
-    href="/guides/v1/guide/ai-recruiter"
-  />
-  <CardGridItem
-    title="Chef Assistant"
-    description="Build an AI chef agent that helps users cook meals with available ingredients, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/chef-michel"
-  />
-  <CardGridItem
-    title="Research Assistant"
-    description="Develop an AI research assistant that analyzes academic papers using Retrieval Augmented Generation (RAG), demonstrating document processing and question answering."
-    href="/guides/v1/guide/research-assistant"
-  />
-  <CardGridItem
-    title="Stock Agent"
-    description="Implement a simple agent that fetches stock prices, illustrating the basics of creating tools and integrating them with Mastra agents."
-    href="/guides/v1/guide/stock-agent"
-  />
-  <CardGridItem
-    title="Notes MCP Server"
-    description="Build an AI notes assistant that helps users manage their notes, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/notes-mcp-server"
-  />
-  <CardGridItem
-    title="Web Search"
-    description="A step-by-step guide to creating an agent that can search the web."
-    href="/guides/v1/guide/web-search"
-  />
-</CardGrid>
+Mastra offers a variety of guides to help you build and work with Mastra, from building agents and workflows to using the Mastra SDK and API, and implementing different UI frameworks. To find what you need, use the left-hand side navigation to browse by topic or use the search bar to look up specific implementation details, frameworks, or features.

package/.docs/raw/guides/migrations/agentnetwork.mdx

@@ -40,7 +40,7 @@ const agent = new AgentNetwork({
   name: "agent-network",
   agents: [agent1, agent2],
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -61,7 +61,7 @@ const agent = new Agent({
   name: "agent-network",
   agents: { agent1, agent2 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,
@@ -83,7 +83,7 @@ const agent = new NewAgentNetwork({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -104,7 +104,7 @@ const agent = new Agent({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,

package/.docs/raw/guides/migrations/ai-sdk-v4-to-v5.mdx

@@ -0,0 +1,119 @@
+---
+title: "Migration: AI SDK v4 to v5 | Migration Guide"
+description: "Mastra-specific guidance for upgrading from AI SDK v4 to v5."
+---
+
+# Migrate from AI SDK v4 to v5
+
+Looking for integration docs? See [Using AI SDK](/guides/v1/build-your-ui/ai-sdk-ui).
+
+Follow the official [AI SDK v5 Migration Guide](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0) for all AI SDK core breaking changes, package updates, and API changes.
+
+This guide covers only the Mastra-specific aspects of the migration.
+
+- **Data compatibility**: New data stored in v5 format will no longer work if you downgrade from v5 to v4
+- **Backup recommendation**: Keep DB backups from before you upgrade to v5
+
+### Memory and Storage
+
+Mastra automatically handles AI SDK v4 data using its internal `MessageList` class, which manages format conversion—including v4 to v5. No database migrations are required; your existing messages are translated on the fly and continue working after you upgrade.
+
+### Message Format Conversion
+
+For cases where you need to manually convert messages between AI SDK and Mastra formats, use the `convertMessages()` utility:
+
+```typescript
+import { convertMessages } from "@mastra/core/agent";
+
+// Convert AI SDK v4 messages to v5
+const aiv5Messages = convertMessages(aiv4Messages).to("AIV5.UI");
+
+// Convert Mastra messages to AI SDK v5
+const aiv5Messages = convertMessages(mastraMessages).to("AIV5.Core");
+
+// Supported output formats:
+// 'Mastra.V2', 'AIV4.UI', 'AIV5.UI', 'AIV5.Core', 'AIV5.Model'
+```
+
+This utility is helpful when you want to fetch messages directly from your storage DB and convert them for use in AI SDK.
+
+### Type Inference for Tools
+
+When using tools with TypeScript in AI SDK v5, Mastra provides type inference helpers to ensure type safety for your tool inputs and outputs.
+
+#### `InferUITool`
+
+The `InferUITool` type helper infers the input and output types of a single Mastra tool:
+
+```typescript title="app/types.ts" copy
+import { InferUITool, createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get the current weather",
+  inputSchema: z.object({
+    location: z.string().describe("The city and state"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async (inputData) => {
+    return {
+      temperature: 72,
+      conditions: "sunny",
+    };
+  },
+});
+
+// Infer the types from the tool
+type WeatherUITool = InferUITool<typeof weatherTool>;
+// This creates:
+// {
+//   input: { location: string };
+//   output: { temperature: number; conditions: string };
+// }
+```
+
+#### `InferUITools`
+
+The `InferUITools` type helper infers the input and output types of multiple tools:
+
+```typescript title="app/mastra/tools.ts" copy
+import { InferUITools, createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// Using weatherTool from the previous example
+const tools = {
+  weather: weatherTool,
+  calculator: createTool({
+    id: "calculator",
+    description: "Perform basic arithmetic",
+    inputSchema: z.object({
+      operation: z.enum(["add", "subtract", "multiply", "divide"]),
+      a: z.number(),
+      b: z.number(),
+    }),
+    outputSchema: z.object({
+      result: z.number(),
+    }),
+    execute: async (inputData) => {
+      // implementation...
+      return { result: 0 };
+    },
+  }),
+};
+
+// Infer types from the tool set
+export type MyUITools = InferUITools<typeof tools>;
+// This creates:
+// {
+//   weather: { input: { location: string }; output: { temperature: number; conditions: string } };
+//   calculator: { input: { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }; output: { result: number } };
+// }
+```
+
+These type helpers provide full TypeScript support when using Mastra tools with AI SDK v5 UI components, ensuring type safety across your application.
+
+

package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx

@@ -25,7 +25,7 @@ To migrate, replace all calls to `mastra.getAgents()` with `mastra.listAgents()`
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/agent-get-agents .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -177,6 +177,16 @@ To migrate, move `abortSignal` from `modelSettings` to the top level.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/agent-abort-signal .
+```
+
+:::
+
 ### `output` to `structuredOutput.schema`
 
 The deprecated `output` and `experimental_output` options have been removed. This change consolidates on a single, stable API for structured output.
@@ -192,6 +202,46 @@ To migrate, update from `output` or `experimental_output` to `structuredOutput.s
   });
 ```
 
+### Agent `id` field is now required
+
+The `id` field is now required when creating an Agent. Previously, agents could be created without an explicit ID, but this is no longer supported.
+
+To migrate, add an `id` field to all Agent configurations.
+
+```diff
+  const agent = new Agent({
++   id: 'my-agent',
+    name: 'My Agent',
+    instructions: 'You are a helpful assistant',
+    model: openai('gpt-4'),
+  });
+```
+
+The `id` can be the same as the `name`, or you can use a different identifier. The ID will be used when calling `mastra.getAgentById()` and must be unique within your Mastra instance.
+
+```typescript
+// Register agent with Mastra
+const mastra = new Mastra({
+  agents: {
+    myAgent: agent, // key can differ from id
+  },
+});
+
+// Retrieve by ID
+const agent = mastra.getAgentById('my-agent');
+```
+
+### Stream API responses now redact sensitive data
+
+The Mastra server now automatically redacts sensitive information from agent stream responses. This prevents accidental exposure of system prompts, tool definitions, and API keys in `step-start`, `step-finish`, and `finish` stream chunks.
+
+**What's redacted:**
+- `request.body` containing LLM request payloads (system prompts, tool schemas)
+- `metadata.request` in step results
+- `output.steps[].request` in nested step data
+
+This behavior is enabled by default. If you need access to the full request data (e.g., for debugging or internal services), you can disable redaction when using server adapters directly (e.g., `@mastra/hono` or `@mastra/express`).
+
 ## Removed
 
 ### `generateVNext` and `streamVNext` methods