@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/organized/code-examples/weather-agent.md

@@ -0,0 +1,353 @@
+### package.json
+```json
+{
+  "name": "examples-weather-agent",
+  "type": "module",
+  "private": true,
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "dev": "npx tsx src/mastra/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+
+import { weatherTool } from '../tools';
+
+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 the location name isn’t in English, please translate it
+- 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 },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { weatherAgent } from './agents';
+import { weatherWorkflow } from './workflows';
+
+const mastra = new Mastra({
+  agents: { weatherAgent },
+  workflows: { weatherWorkflow },
+});
+
+async function agentExample() {
+  const agent = await mastra.getAgent('weatherAgent');
+  const result = await agent.generate('What is the weather in London?');
+  console.log(result.text);
+}
+
+async function workflowExample() {
+  const { start } = mastra.getWorkflow('weatherWorkflow').createRun();
+
+  const result = await start({
+    triggerData: {
+      city: 'London',
+    },
+  });
+
+  console.log('\n \n');
+  console.log(result);
+}
+
+// agentExample();
+workflowExample();
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+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();
+
+  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: WeatherResponse = await response.json();
+
+  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';
+}
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Step, Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const agent = new Agent({
+  name: 'Weather Agent',
+  instructions: `
+        You are a local activities and travel expert who excels at weather-based planning. Analyze the weather data and provide practical activity recommendations.
+        For each day in the forecast, structure your response exactly as follows:
+        📅 [Day, Month Date, Year]
+        ═══════════════════════════
+        🌡️ WEATHER SUMMARY
+        • Conditions: [brief description]
+        • Temperature: [X°C/Y°F to A°C/B°F]
+        • Precipitation: [X% chance]
+        🌅 MORNING ACTIVITIES
+        Outdoor:
+        • [Activity Name] - [Brief description including specific location/route]
+          Best timing: [specific time range]
+          Note: [relevant weather consideration]
+        🌞 AFTERNOON ACTIVITIES
+        Outdoor:
+        • [Activity Name] - [Brief description including specific location/route]
+          Best timing: [specific time range]
+          Note: [relevant weather consideration]
+        🏠 INDOOR ALTERNATIVES
+        • [Activity Name] - [Brief description including specific venue]
+          Ideal for: [weather condition that would trigger this alternative]
+        ⚠️ SPECIAL CONSIDERATIONS
+        • [Any relevant weather warnings, UV index, wind conditions, etc.]
+        Guidelines:
+        - Suggest 2-3 time-specific outdoor activities per day
+        - Include 1-2 indoor backup options
+        - For precipitation >50%, lead with indoor activities
+        - All activities must be specific to the location
+        - Include specific venues, trails, or locations
+        - Consider activity intensity based on temperature
+        - Keep descriptions concise but informative
+        Maintain this exact formatting for consistency, using the emoji and section headers as shown.
+      `,
+  model: openai('gpt-4o'),
+});
+
+const fetchWeather = new Step({
+  id: 'fetch-weather',
+  description: 'Fetches weather forecast for a given city',
+  inputSchema: z.object({
+    city: z.string().describe('The city to get the weather for'),
+  }),
+  execute: async ({ context }) => {
+    const triggerData = context?.getStepResult<{ city: string }>('trigger');
+
+    if (!triggerData) {
+      throw new Error('Trigger data not found');
+    }
+
+    const geocodingUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(triggerData.city)}&count=1`;
+    const geocodingResponse = await fetch(geocodingUrl);
+    const geocodingData = await geocodingResponse.json();
+
+    if (!geocodingData.results?.[0]) {
+      throw new Error(`Location '${triggerData.city}' not found`);
+    }
+
+    const { latitude, longitude, name } = geocodingData.results[0];
+
+    const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&daily=temperature_2m_max,temperature_2m_min,precipitation_probability_mean,weathercode&timezone=auto`;
+    const response = await fetch(weatherUrl);
+    const data = await response.json();
+
+    const forecast = data.daily.time.map((date: string, index: number) => ({
+      date,
+      maxTemp: data.daily.temperature_2m_max[index],
+      minTemp: data.daily.temperature_2m_min[index],
+      precipitationChance: data.daily.precipitation_probability_mean[index],
+      condition: getWeatherCondition(data.daily.weathercode[index]),
+      location: name,
+    }));
+
+    return forecast;
+  },
+});
+
+const forecastSchema = z.array(
+  z.object({
+    date: z.string(),
+    maxTemp: z.number(),
+    minTemp: z.number(),
+    precipitationChance: z.number(),
+    condition: z.string(),
+    location: z.string(),
+  }),
+);
+
+const planActivities = new Step({
+  id: 'plan-activities',
+  description: 'Suggests activities based on weather conditions',
+  inputSchema: forecastSchema,
+  execute: async ({ context, mastra }) => {
+    const forecast = context?.getStepResult<z.infer<typeof forecastSchema>>('fetch-weather');
+
+    if (!forecast) {
+      throw new Error('Forecast data not found');
+    }
+
+    const prompt = `Based on the following weather forecast for ${forecast[0].location}, suggest appropriate activities:
+      ${JSON.stringify(forecast, null, 2)}
+      `;
+
+    const response = await agent.stream([
+      {
+        role: 'user',
+        content: prompt,
+      },
+    ]);
+
+    let activitiesText = '';
+
+    for await (const chunk of response.textStream) {
+      process.stdout.write(chunk);
+      activitiesText += chunk;
+    }
+
+    return {
+      activities: activitiesText,
+    };
+  },
+});
+
+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',
+    61: 'Slight rain',
+    63: 'Moderate rain',
+    65: 'Heavy rain',
+    71: 'Slight snow fall',
+    73: 'Moderate snow fall',
+    75: 'Heavy snow fall',
+    95: 'Thunderstorm',
+  };
+  return conditions[code] || 'Unknown';
+}
+
+const weatherWorkflow = new Workflow({
+  name: 'weather-workflow',
+  triggerSchema: z.object({
+    city: z.string().describe('The city to get the weather for'),
+  }),
+})
+  .step(fetchWeather)
+  .then(planActivities);
+
+weatherWorkflow.commit();
+
+export { weatherWorkflow };
+
+```

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

@@ -0,0 +1,159 @@
+### package.json
+```json
+{
+  "name": "examples-workflow-ai-recruiter",
+  "type": "module",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "mastra dev",
+    "start:dev": "npx bun src/mastra/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "mastra": "workspace:*",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "zod": "^3.24.2"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "ai": "latest"
+  },
+  "version": "0.0.1-alpha.2"
+}
+
+```
+
+### mastra/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Mastra } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import { Step, Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const recruiter = new Agent({
+  name: 'Recruiter Agent',
+  instructions: `You are a recruiter.`,
+  model: openai('gpt-4o-mini'),
+});
+
+const gatherCandidateInfo = new Step({
+  id: 'gatherCandidateInfo',
+  inputSchema: z.object({
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    candidateName: z.string(),
+    isTechnical: z.boolean(),
+    specialty: z.string(),
+    resumeText: z.string(),
+  }),
+  execute: async ({ context, mastra }) => {
+    const resumeText = context?.getStepResult<{ resumeText: string }>('trigger')?.resumeText;
+
+    const prompt = `
+          You are given this resume text:
+          "${resumeText}"
+        `;
+    const res = await recruiter.generate(prompt, {
+      output: z.object({
+        candidateName: z.string(),
+        isTechnical: z.boolean(),
+        specialty: z.string(),
+        resumeText: z.string(),
+      }),
+    });
+
+    return res.object;
+  },
+});
+
+interface CandidateInfo {
+  candidateName: string;
+  isTechnical: boolean;
+  specialty: string;
+  resumeText: string;
+}
+
+const askAboutSpecialty = new Step({
+  id: 'askAboutSpecialty',
+  outputSchema: z.object({
+    question: z.string(),
+  }),
+  execute: async ({ context, mastra }) => {
+    const candidateInfo = context?.getStepResult<CandidateInfo>('gatherCandidateInfo');
+
+    const prompt = `
+          You are a recruiter. Given the resume below, craft a short question
+          for ${candidateInfo?.candidateName} about how they got into "${candidateInfo?.specialty}".
+          Resume: ${candidateInfo?.resumeText}
+        `;
+    const res = await recruiter.generate(prompt);
+    return { question: res?.text?.trim() || '' };
+  },
+});
+
+const askAboutRole = new Step({
+  id: 'askAboutRole',
+  outputSchema: z.object({
+    question: z.string(),
+  }),
+  execute: async ({ context, mastra }) => {
+    const candidateInfo = context?.getStepResult<CandidateInfo>('gatherCandidateInfo');
+
+    const prompt = `
+          You are a recruiter. Given the resume below, craft a short question
+          for ${candidateInfo?.candidateName} asking what interests them most about this role.
+          Resume: ${candidateInfo?.resumeText}
+        `;
+    const res = await recruiter.generate(prompt);
+    return { question: res?.text?.trim() || '' };
+  },
+});
+
+const candidateWorkflow = new Workflow({
+  name: 'candidate-workflow',
+  triggerSchema: z.object({
+    resumeText: z.string(),
+  }),
+});
+
+candidateWorkflow
+  .step(gatherCandidateInfo)
+  .then(askAboutSpecialty, {
+    when: { 'gatherCandidateInfo.isTechnical': true },
+  })
+  .after(gatherCandidateInfo)
+  .step(askAboutRole, {
+    when: { 'gatherCandidateInfo.isTechnical': false },
+  });
+
+candidateWorkflow.commit();
+
+const mastra = new Mastra({
+  workflows: {
+    candidateWorkflow,
+  },
+});
+
+(async () => {
+  const { runId, start } = mastra.getWorkflow('candidateWorkflow').createRun();
+
+  console.log('Run', runId);
+
+  const runResult = await start({
+    triggerData: { resumeText: 'Simulated resume content...' },
+  });
+
+  console.log('Final output:', runResult.results);
+})();
+
+```

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

@@ -0,0 +1,111 @@
+### package.json
+```json
+{
+  "name": "workflow-with-inline-steps",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "mastra dev"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "mastra": "workspace:*",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "zod": "^3.24.2"
+  },
+  "dependencies": {
+    "@mastra/core": "workspace:*"
+  },
+  "version": "0.0.1-alpha.2"
+}
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { myWorkflow } from './workflows';
+
+export const mastra = new Mastra({
+  workflows: {
+    myWorkflow,
+  },
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { Step, Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const myWorkflow = new Workflow({
+  name: 'my-workflow',
+  triggerSchema: z.object({
+    inputValue: z.number(),
+  }),
+});
+
+myWorkflow
+  .step(
+    new Step({
+      id: 'stepOne',
+      inputSchema: z.object({
+        value: z.number(),
+      }),
+      outputSchema: z.object({
+        doubledValue: z.number(),
+      }),
+      execute: async ({ context }) => {
+        const doubledValue = context?.triggerData.inputValue * 2;
+        return { doubledValue };
+      },
+    }),
+  )
+  .then(
+    new Step({
+      id: 'stepTwo',
+      inputSchema: z.object({
+        valueToIncrement: z.number(),
+      }),
+      outputSchema: z.object({
+        incrementedValue: z.number(),
+      }),
+      execute: async ({ context }) => {
+        if (context?.steps.stepOne.status === 'success') {
+          const incrementedValue = context?.steps.stepOne.output.doubledValue + 1;
+          return { incrementedValue };
+        }
+        return { incrementedValue: 0 };
+      },
+    }),
+  )
+  .then(
+    new Step({
+      id: 'stepThree',
+      execute: async ({ context, suspend }) => {
+        if (context?.resumeData?.confirm !== 'true') {
+          return suspend({
+            message: 'Do you accept?',
+          });
+        }
+
+        return {
+          message: 'Thank you for accepting',
+        };
+      },
+    }),
+  );
+
+myWorkflow.commit();
+
+export { myWorkflow };
+
+```