@mastra/mcp-docs-server 0.0.1-alpha.1

package/.docs/organized/code-examples/stock-price-tool.md

@@ -0,0 +1,124 @@
+### package.json
+```json
+{
+  "name": "examples-stock-price-tool",
+  "type": "module",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "dev": "mastra dev",
+    "test": "cross-env NODE_OPTIONS='--experimental-vm-modules --max-old-space-size=8192' jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0",
+    "mastra": "workspace:*",
+    "ts-jest": "^29.2.6"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### index.ts
+```typescript
+import { mastra } from './mastra';
+
+async function main() {
+  const stockAgent = mastra.getAgent('stockAgent');
+  const response = await stockAgent.generate('What is the current stock price of Apple (AAPL)?');
+
+  const toolCall: any = response.toolResults.find((result: any) => result.toolName === 'stockPrices');
+
+  const currentPrice = toolCall?.result?.currentPrice;
+
+  console.log(`The current price of Apple (AAPL) is $${currentPrice}`);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+
+import { stockPrices } from '../tools/stock-price';
+
+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'),
+  tools: {
+    stockPrices,
+  },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { stockAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { stockAgent },
+});
+
+```
+
+### mastra/tools/stock-price.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const getStockPrice = async (symbol: string) => {
+  const data = await fetch(`https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`).then(r => r.json());
+  return data.prices['4. close'];
+};
+
+export const stockPrices = createTool({
+  id: 'Get Stock Price',
+  inputSchema: z.object({
+    symbol: z.string(),
+  }),
+  description: `Fetches the last day's closing stock price for a given symbol`,
+  execute: async ({ context }) => {
+    console.log('Using tool to fetch stock price for', context.symbol);
+    return {
+      symbol: context.symbol,
+      currentPrice: await getStockPrice(context.symbol),
+    };
+  },
+});
+
+```
+
+### mastra/tools/tools.test.ts
+```typescript
+import { describe, it, expect } from 'vitest';
+
+import { getStockPrice } from './stock-price';
+
+describe('Test Tools', () => {
+  it('should run the stockPrices', async () => {
+    const result = await getStockPrice('AAPL');
+
+    console.log(result);
+    expect(result).toBeDefined();
+  });
+});
+
+```

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

@@ -0,0 +1,352 @@
+### 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": "ISC",
+  "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 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": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "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);
+})();
+
+```