@mastra/mcp-docs-server 0.13.5 → 0.13.7-alpha.0

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.8.3"
+  }
+}
+```
+
+### 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,11 +18,11 @@
     "@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"
+    "typescript": "^5.8.3"
   }
 }
 ```

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

@@ -11,7 +11,7 @@
     "nodemon": "^3.1.9",
     "ts-node": "^10.9.2",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "latest",

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

@@ -23,11 +23,11 @@
     "@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"
+    "typescript": "^5.8.3"
   }
 }
 ```

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

@@ -23,11 +23,11 @@
     "@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"
+    "typescript": "^5.8.3"
   }
 }
 ```

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

@@ -15,12 +15,12 @@
     "@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",
-    "typescript": "~5.7.2",
-    "typescript-eslint": "^8.24.1",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.38.0",
     "vite": "^6.2.0"
   }
 }

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

@@ -20,7 +20,7 @@
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-tooltip": "^1.2.7",
     "@radix-ui/react-visually-hidden": "^1.2.3",
-    "@typescript-eslint/parser": "^8.31.0",
+    "@typescript-eslint/parser": "^8.38.0",
     "@vercel/analytics": "^1.5.0",
     "@vercel/blob": "^1.0.0",
     "@vercel/postgres": "^0.10.0",
@@ -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/fireworks-r1.md

@@ -20,7 +20,7 @@
     "dotenv": "^17.0.0",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   }
 }
 ```

package/.docs/organized/code-examples/memory-with-mem0.md

@@ -11,7 +11,7 @@
   "devDependencies": {
     "@types/node": "^22.15.29",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   }
 }
 ```

package/.docs/organized/code-examples/memory-with-pg.md

@@ -176,6 +176,7 @@ export const memory = new Memory({
       messageRange: 2,
     },
   },
+  embedder: openai.embedding('text-embedding-3-small'),
 });
 
 export const chefAgent = new Agent({

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

@@ -33,11 +33,11 @@
     "@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"
+    "typescript": "^5.8.3"
   },
   "peerDependencies": {
     "react": ">= 0.14.0 || 19",

package/.docs/organized/code-examples/quick-start.md

@@ -5,7 +5,7 @@
   "devDependencies": {
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-ai-recruiter.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-inline-steps.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-memory.md

@@ -5,7 +5,7 @@
   "devDependencies": {
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-separate-steps.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

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.3",
+    "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();
+
+```