@mastra/mcp-docs-server 0.13.5 → 0.13.6

package/.docs/organized/code-examples/ai-sdk-v5.md

@@ -0,0 +1,201 @@
+### package.json
+```json
+{
+  "name": "mastra-ai-sdk-v5-use-chat-example",
+  "dependencies": {
+    "@ai-sdk/openai": "2.0.0-beta.1",
+    "@ai-sdk/react": "2.0.0-beta.1",
+    "@mastra/core": "0.0.0-ai-v5-20250625173645",
+    "@mastra/libsql": "0.0.0-ai-v5-20250625173645",
+    "@mastra/loggers": "0.0.0-ai-v5-20250625173645",
+    "@mastra/memory": "0.0.0-ai-v5-20250625173645",
+    "@mastra/pg": "0.0.0-ai-v5-20250625173645",
+    "@mastra/rag": "0.0.0-ai-v5-20250625173645",
+    "@mastra/server": "0.0.0-ai-v5-20250625173645",
+    "next": "15.2.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "swr": "^2.3.3",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "15.1.7",
+    "mastra": "0.0.0-ai-v5-20250625173645",
+    "postcss": "^8",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5"
+  }
+}
+```
+
+### mastra/agents/index.ts
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+import { weatherTool } from "../tools";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const memory = new Memory({
+  storage: new LibSQLStore({
+    url: `file:./mastra.db`,
+  }),
+  options: {
+    semanticRecall: false,
+    workingMemory: {
+      enabled: false,
+    },
+    lastMessages: 5,
+  },
+});
+
+export const weatherAgent = new Agent({
+  name: "Weather Agent",
+  instructions: `
+      You are a helpful weather assistant that provides accurate weather information.
+
+      Your primary function is to help users get weather details for specific locations. When responding:
+      - Always ask for a location if none is provided
+      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
+      - Include relevant details like humidity, wind conditions, and precipitation
+      - Keep responses concise but informative
+
+      Use the weatherTool to fetch current weather data.
+
+`,
+  model: openai("gpt-4o"),
+  tools: {
+    weatherTool,
+  },
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { ConsoleLogger } from "@mastra/core/logger";
+import { Mastra } from "@mastra/core/mastra";
+
+import { weatherAgent } from "./agents";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+  logger: new ConsoleLogger(),
+  // aiSdkCompat: "v4",
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+interface GeocodingResponse {
+  results: {
+    latitude: number;
+    longitude: number;
+    name: string;
+  }[];
+}
+interface WeatherResponse {
+  current: {
+    time: string;
+    temperature_2m: number;
+    apparent_temperature: number;
+    relative_humidity_2m: number;
+    wind_speed_10m: number;
+    wind_gusts_10m: number;
+    weather_code: number;
+  };
+}
+
+export const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("City name"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    feelsLike: z.number(),
+    humidity: z.number(),
+    windSpeed: z.number(),
+    windGust: z.number(),
+    conditions: z.string(),
+    location: z.string(),
+  }),
+  execute: async ({ context }) => {
+    return await getWeather(context.location);
+  },
+});
+
+const getWeather = async (location: string) => {
+  const geocodingUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}&count=1`;
+  const geocodingResponse = await fetch(geocodingUrl);
+  const geocodingData = (await geocodingResponse.json()) as GeocodingResponse;
+
+  if (!geocodingData.results?.[0]) {
+    throw new Error(`Location '${location}' not found`);
+  }
+
+  const { latitude, longitude, name } = geocodingData.results[0];
+
+  const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,wind_gusts_10m,weather_code`;
+
+  const response = await fetch(weatherUrl);
+  const data = (await response.json()) as WeatherResponse;
+
+  return {
+    temperature: data.current.temperature_2m,
+    feelsLike: data.current.apparent_temperature,
+    humidity: data.current.relative_humidity_2m,
+    windSpeed: data.current.wind_speed_10m,
+    windGust: data.current.wind_gusts_10m,
+    conditions: getWeatherCondition(data.current.weather_code),
+    location: name,
+  };
+};
+
+function getWeatherCondition(code: number): string {
+  const conditions: Record<number, string> = {
+    0: "Clear sky",
+    1: "Mainly clear",
+    2: "Partly cloudy",
+    3: "Overcast",
+    45: "Foggy",
+    48: "Depositing rime fog",
+    51: "Light drizzle",
+    53: "Moderate drizzle",
+    55: "Dense drizzle",
+    56: "Light freezing drizzle",
+    57: "Dense freezing drizzle",
+    61: "Slight rain",
+    63: "Moderate rain",
+    65: "Heavy rain",
+    66: "Light freezing rain",
+    67: "Heavy freezing rain",
+    71: "Slight snow fall",
+    73: "Moderate snow fall",
+    75: "Heavy snow fall",
+    77: "Snow grains",
+    80: "Slight rain showers",
+    81: "Moderate rain showers",
+    82: "Violent rain showers",
+    85: "Slight snow showers",
+    86: "Heavy snow showers",
+    95: "Thunderstorm",
+    96: "Thunderstorm with slight hail",
+    99: "Thunderstorm with heavy hail",
+  };
+  return conditions[code] || "Unknown";
+}
+
+```

package/.docs/organized/code-examples/assistant-ui.md

@@ -18,8 +18,8 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "eslint": "^9.29.0",
-    "eslint-config-next": "15.3.3",
+    "eslint": "^9.30.1",
+    "eslint-config-next": "15.3.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.8.2"

package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md

@@ -23,8 +23,8 @@
     "@types/node": "^20.17.57",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
-    "eslint": "^9.29.0",
-    "eslint-config-next": "15.3.3",
+    "eslint": "^9.30.1",
+    "eslint-config-next": "15.3.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.8.2"

package/.docs/organized/code-examples/bird-checker-with-nextjs.md

@@ -23,8 +23,8 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "eslint": "^9.29.0",
-    "eslint-config-next": "15.3.3",
+    "eslint": "^9.30.1",
+    "eslint-config-next": "15.3.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.8.2"

package/.docs/organized/code-examples/client-side-tools.md

@@ -15,7 +15,7 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@vitejs/plugin-react": "^4.3.4",
-    "eslint": "^9.29.0",
+    "eslint": "^9.30.1",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",
     "globals": "^15.15.0",

package/.docs/organized/code-examples/crypto-chatbot.md

@@ -71,14 +71,14 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "drizzle-kit": "^0.31.0",
-    "eslint": "^9.29.0",
-    "eslint-config-next": "15.3.3",
+    "eslint": "^9.30.1",
+    "eslint-config-next": "15.3.5",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-import-resolver-typescript": "^4.4.3",
-    "eslint-plugin-import": "^2.31.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-tailwindcss": "^3.18.0",
     "postcss": "^8.5.3",
-    "prettier": "^3.5.3",
+    "prettier": "^3.6.2",
     "tailwindcss": "^3.4.17",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3"

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

@@ -33,8 +33,8 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "eslint": "^9.29.0",
-    "eslint-config-next": "15.3.3",
+    "eslint": "^9.30.1",
+    "eslint-config-next": "15.3.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.8.2"

package/.docs/organized/code-examples/workflow-with-suspend-resume.md

@@ -0,0 +1,181 @@
+### package.json
+```json
+{
+  "name": "examples-workflow-with-suspend-resume",
+  "devDependencies": {
+    "@types/node": "^20.17.57",
+    "mastra": "latest",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "zod": "^3.25.67"
+  },
+  "dependencies": {
+    "@mastra/core": "latest",
+    "@mastra/libsql": "latest"
+  }
+}
+```
+
+### index.ts
+```typescript
+import { mastra } from './mastra';
+
+async function main() {
+  console.log('🚀 Starting workflow with suspend/resume example...\n');
+
+  const myWorkflow = mastra.getWorkflow('myWorkflow');
+  const run = await myWorkflow.createRunAsync();
+
+  try {
+    // Start the workflow - it will suspend at stepTwo
+    console.log('📝 Starting workflow with inputValue: 30');
+    const result = await run.start({
+      inputData: {
+        inputValue: 30,
+      },
+    });
+
+    console.log('📊 Workflow result:', JSON.stringify(result, null, 2));
+
+    // Check if the workflow is suspended
+    if (result.status === 'suspended') {
+      console.log('\n⏸️  Workflow is suspended! Suspended steps:', result.suspended);
+
+      // Resume the workflow with additional data
+      console.log('▶️  Resuming workflow with extraNumber: 5');
+      const resumedResult = await run.resume({
+        step: result.suspended[0], // Resume the first suspended step
+        resumeData: {
+          extraNumber: 5,
+        },
+      });
+
+      console.log('✅ Resumed workflow result:', JSON.stringify(resumedResult, null, 2));
+    } else {
+      console.log('✅ Workflow completed without suspension');
+    }
+  } catch (e) {
+    console.error('❌ Error:', e);
+  }
+}
+
+main();
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { LibSQLStore } from '@mastra/libsql';
+
+import { myWorkflow } from './workflows';
+
+export const mastra = new Mastra({
+  workflows: {
+    myWorkflow,
+  },
+  storage: new LibSQLStore({
+    url: 'file:./workflow-snapshots.db',
+  }),
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { createStep, createWorkflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const stepOne = createStep({
+  id: 'stepOne',
+  inputSchema: z.object({
+    inputValue: z.number(),
+  }),
+  outputSchema: z.object({
+    doubledValue: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    const doubledValue = inputData.inputValue * 2;
+    return { doubledValue };
+  },
+});
+
+const stepTwo = createStep({
+  id: 'stepTwo',
+  inputSchema: z.object({
+    doubledValue: z.number(),
+  }),
+  outputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  suspendSchema: z.object({}),
+  resumeSchema: z.object({
+    extraNumber: z.number(),
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    if (!resumeData?.extraNumber) {
+      await suspend({});
+      return { incrementedValue: 0 };
+    }
+    const incrementedValue = inputData.doubledValue + 1 + resumeData.extraNumber;
+    return { incrementedValue };
+  },
+});
+
+const stepThree = createStep({
+  id: 'stepThree',
+  inputSchema: z.object({
+    incrementedValue: z.number(),
+  }),
+  outputSchema: z.object({
+    tripledValue: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    const tripledValue = inputData.incrementedValue * 3;
+    return { tripledValue };
+  },
+});
+
+const stepFour = createStep({
+  id: 'stepFour',
+  inputSchema: z.object({
+    tripledValue: z.number(),
+  }),
+  outputSchema: z.object({
+    isEven: z.boolean(),
+  }),
+  execute: async ({ inputData }) => {
+    const isEven = inputData.tripledValue % 2 === 0;
+    return { isEven };
+  },
+});
+
+// Create a nested workflow
+export const nestedWorkflow = createWorkflow({
+  id: 'data-processing',
+  inputSchema: z.object({
+    inputValue: z.number(),
+  }),
+  outputSchema: z.object({
+    isEven: z.boolean(),
+  }),
+})
+  .then(stepOne)
+  .then(stepTwo)
+  .then(stepThree)
+  .then(stepFour)
+  .commit();
+
+export const myWorkflow = createWorkflow({
+  id: 'my-workflow',
+  inputSchema: z.object({
+    inputValue: z.number(),
+  }),
+  outputSchema: z.object({
+    isEven: z.boolean(),
+  }),
+})
+  .then(nestedWorkflow)
+  .commit();
+
+```

package/.docs/raw/agents/agent-memory.mdx

@@ -37,6 +37,132 @@ const agent = new Agent({
 
 This basic setup uses the default settings. Visit the [Memory documentation](/docs/memory/overview) for more configuration info.
 
+## Dynamic Memory Configuration
+
+Similar to how you can configure dynamic [instructions, models, and tools](./dynamic-agents.mdx), you can also configure memory dynamically using runtime context. This allows you to:
+
+- Use different memory systems based on user tiers or preferences
+- Switch between memory configurations for different environments
+- Enable or disable memory features based on feature flags
+- Customize memory behavior based on user context
+
+### Example: User Tier-Based Memory
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+import { PostgresStore } from "@mastra/pg";
+import { openai } from "@ai-sdk/openai";
+
+// Create different memory instances for different user tiers
+const premiumMemory = new Memory({
+  storage: new LibSQLStore({ url: "file:premium.db" }),
+  options: {
+    semanticRecall: { topK: 10, messageRange: 5 }, // More context for premium users
+    workingMemory: { enabled: true },
+  },
+});
+
+const standardMemory = new Memory({
+  storage: new LibSQLStore({ url: "file:standard.db" }),
+  options: {
+    semanticRecall: { topK: 3, messageRange: 2 }, // Basic recall for standard users
+    workingMemory: { enabled: false },
+  },
+});
+
+const agent = new Agent({
+  name: "TieredMemoryAgent",
+  instructions: "You are a helpful assistant with tiered memory capabilities.",
+  model: openai("gpt-4o"),
+  memory: ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("userTier");
+    return userTier === "premium" ? premiumMemory : standardMemory;
+  },
+});
+```
+
+### Example: Environment-Based Memory
+
+```typescript
+const agent = new Agent({
+  name: "EnvironmentAwareAgent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o"),
+  memory: ({ runtimeContext }) => {
+    const environment = runtimeContext.get("environment");
+    
+    if (environment === "test") {
+      // Use local storage for testing
+      return new Memory({
+        storage: new LibSQLStore({ url: ":memory:" }),
+        options: {
+          workingMemory: { enabled: true },
+        },
+      });
+    } else if (environment === "production") {
+      // Use production database
+      return new Memory({
+        storage: new PostgresStore({ connectionString: process.env.PRODUCTION_DB_URL }),
+        options: {
+          workingMemory: { enabled: true },
+        },
+      });
+    }
+    
+    // Development environment
+    return new Memory({
+      storage: new LibSQLStore({ url: "file:dev.db" }),
+    });
+  },
+});
+```
+
+### Example: Async Memory Configuration
+
+```typescript
+const agent = new Agent({
+  name: "AsyncMemoryAgent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o"),
+  memory: async ({ runtimeContext }) => {
+    const userId = runtimeContext.get("userId");
+    
+    // Simulate async memory setup (e.g., database lookup)
+    await new Promise(resolve => setTimeout(resolve, 10));
+    
+    return new Memory({
+      storage: new LibSQLStore({ 
+        url: `file:user_${userId}.db` 
+      }),
+    });
+  },
+});
+```
+
+### Using Dynamic Memory
+
+When using dynamic memory, pass the runtime context to your agent calls:
+
+```typescript
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+// Create runtime context with user information
+const runtimeContext = new RuntimeContext();
+runtimeContext.set("userTier", "premium");
+runtimeContext.set("environment", "production");
+
+// Use the agent with runtime context
+const response = await agent.generate("Remember my favorite color is blue.", {
+  memory: {
+    resource: "user_alice",
+    thread: { id: "preferences_thread" },
+  },
+  runtimeContext, // Pass the runtime context
+});
+```
+
 ## Using Memory in Agent Calls
 
 To utilize memory during interactions, you **must** provide `resourceId` and `threadId` when calling the agent's `stream()` or `generate()` methods.

package/.docs/raw/agents/dynamic-agents.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Dynamic Agents"
-description: Dynamically configure your agent's instruction, model and tools using runtime context.
+description: Dynamically configure your agent's instruction, model, tools, and memory using runtime context.
 ---
 
 # Dynamic Agents
 
 Dynamic agents use [runtime context](./runtime-variables), like user IDs and other important parameters, to adjust their settings in real-time.
 
-This means they can change the model they use, update their instructions, and select different tools as needed.
+This means they can change the model they use, update their instructions, select different tools, and configure memory as needed.
 
 By using this context, agents can better respond to each user's needs. They can also call any API to gather more information, which helps improve what the agents can do.
 
@@ -55,6 +55,37 @@ const supportAgent = new Agent({
 
     return baseTools;
   },
+
+  memory: ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier");
+    
+    if (userTier === "enterprise") {
+      return new Memory({
+        storage: new LibSQLStore({ url: "file:enterprise.db" }),
+        options: {
+          semanticRecall: { topK: 15, messageRange: 8 },
+          workingMemory: { enabled: true },
+        },
+      });
+    } else if (userTier === "pro") {
+      return new Memory({
+        storage: new LibSQLStore({ url: "file:pro.db" }),
+        options: {
+          semanticRecall: { topK: 8, messageRange: 4 },
+          workingMemory: { enabled: true },
+        },
+      });
+    }
+    
+    // Basic memory for free tier
+    return new Memory({
+      storage: new LibSQLStore({ url: "file:free.db" }),
+      options: {
+        semanticRecall: { topK: 3, messageRange: 2 },
+        workingMemory: { enabled: false },
+      },
+    });
+  },
 });
 ```
 
@@ -63,6 +94,7 @@ In this example, the agent:
 - Adjusts its instructions based on the user's subscription tier (free, pro, or enterprise)
 - Uses a more powerful model (GPT-4) for enterprise users
 - Provides different sets of tools based on the user's tier
+- Configures memory with different capabilities based on the user's tier
 - Responds in the user's preferred language
 
 This demonstrates how a single agent can handle different types of users and scenarios by leveraging runtime context, making it more flexible and maintainable than creating separate agents for each use case.

package/.docs/raw/agents/overview.mdx

@@ -9,6 +9,8 @@ description: Overview of agents in Mastra, detailing their capabilities and how
 
 Agents can run autonomously in a loop, run once, or take turns with a user. You can give short-term, long-term, and working memory of their user interactions. They can stream text or return structured output (ie, JSON). They can access third-party APIs, query knowledge bases, and so on.
 
+Additionally, agents support dynamic configuration, allowing you to change their instructions, model, tools, and memory based on runtime context like user preferences, subscription tiers, or environment settings.
+
 ## 1. Creating an Agent
 
 To create an agent in Mastra, you use the `Agent` class and define its properties:
@@ -36,6 +38,8 @@ Also, make sure you have the `@mastra/core` package installed:
 npm install @mastra/core@latest
 ```
 
+All agent properties (instructions, model, tools, memory) can be configured dynamically using runtime context. See the [Dynamic Agents guide](./dynamic-agents.mdx) for examples of how to adapt agent behavior based on user context, subscription tiers, or other runtime variables.
+
 ### Registering the Agent
 
 Register your agent with Mastra to enable logging and access to configured tools and integrations:
@@ -282,5 +286,6 @@ For more details, see the [Local Dev Playground](/docs/server-db/local-dev-playg
 ## Next Steps
 
 - Learn about Agent Memory in the [Agent Memory](./agent-memory.mdx) guide.
+- Learn about Dynamic Agent configuration in the [Dynamic Agents](./dynamic-agents.mdx) guide.
 - Learn about Agent Tools in the [Agent Tools and MCP](./using-tools-and-mcp.mdx) guide.
 - See an example agent in the [Chef Michel](../../guides/guide/chef-michel.mdx) example.