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

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

@@ -0,0 +1,378 @@
+### package.json
+```json
+{
+  "name": "mastra-ai-sdk-use-chat-example",
+  "version": "0.1.1",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.1.15",
+    "@ai-sdk/react": "^1.1.21",
+    "@mastra/core": "workspace:*",
+    "next": "15.1.7",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.0",
+    "@types/node": "^20.17.24",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "eslint": "^9.23.0",
+    "eslint-config-next": "15.1.7",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.8.2"
+  }
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+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: anthropic('claude-3-5-sonnet-20241022'),
+  tools: { weatherTool },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { createLogger } from '@mastra/core/logger';
+import { Mastra } from '@mastra/core/mastra';
+
+import { weatherAgent } from './agents';
+import { weatherWorkflow } from './workflows';
+
+export const mastra = new Mastra({
+  workflows: { weatherWorkflow },
+  agents: { weatherAgent },
+  logger: createLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+});
+
+```
+
+### 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';
+}
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+import { Agent } from '@mastra/core/agent';
+import { Step, Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const llm = anthropic('claude-3-5-sonnet-20241022');
+
+const agent = new Agent({
+  name: 'Weather Agent',
+  model: llm,
+  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.
+      `,
+});
+
+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()) as {
+      results: { latitude: number; longitude: number; name: string }[];
+    };
+
+    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()) as {
+      daily: {
+        time: string[];
+        temperature_2m_max: number[];
+        temperature_2m_min: number[];
+        precipitation_probability_mean: number[];
+        weathercode: number[];
+      };
+    };
+
+    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 }) => {
+    const forecast = context?.getStepResult<z.infer<typeof forecastSchema>>('fetch-weather');
+
+    if (!forecast || forecast.length === 0) {
+      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/assistant-ui.md

@@ -0,0 +1,37 @@
+### package.json
+```json
+{
+  "name": "examples-assistant-ui",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@assistant-ui/react": "0.7.85",
+    "@assistant-ui/react-markdown": "^0.7.21",
+    "@assistant-ui/react-ui": "^0.1.8",
+    "@mastra/client-js": "workspace:*",
+    "next": "15.0.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss-animate": "^1.0.7",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.27",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "15.0.3",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.8.2"
+  },
+  "version": "0.0.0"
+}
+
+```

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

@@ -0,0 +1,235 @@
+### package.json
+```json
+{
+  "name": "examples-bird-checker-with-express",
+  "description": "",
+  "type": "module",
+  "main": "index.js",
+  "version": "0.0.1",
+  "scripts": {
+    "start": "tsx src/index.ts"
+  },
+  "private": true,
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^4.0.0",
+    "@types/node": "^20.17.27",
+    "concurrently": "^9.1.2",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "nodemon": "^3.1.9",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "latest",
+    "@mastra/core": "workspace:*",
+    "ai": "latest",
+    "zod": "^3.24.2"
+  }
+}
+
+```
+
+### index.ts
+```typescript
+import { config } from 'dotenv';
+import express, { Request, Response } from 'express';
+import { z } from 'zod';
+
+import { getRandomImage, ImageQuery } from './lib/utils';
+import { mastra } from './mastra/index';
+
+config();
+
+const app = express();
+
+app.use(express.json());
+
+const port = process.env.PORT || 3001;
+
+app.get('/', (req: Request, res: Response) => {
+  res.send('Hello, TypeScript Express!');
+});
+
+app.get('/api/get-unsplash-image', async (req: Request, res: Response) => {
+  try {
+    const imageQuery = (req?.query?.query || 'wildlife') as ImageQuery;
+
+    const image = await getRandomImage({ query: imageQuery });
+
+    if (!image.ok) {
+      res.status(400).send({ msg: image.error });
+      return;
+    }
+
+    res.send(image.data);
+  } catch (err) {
+    console.log('get unsplash image err===', err);
+    res.status(400).send({ msg: 'Could not fetch image' });
+  }
+});
+
+app.post('/api/image-metadata', async (req: Request, res: Response) => {
+  try {
+    const imageUrl = req.body?.imageUrl;
+
+    if (!imageUrl) {
+      res.status(400).send({ msg: 'Image url is required' });
+      return;
+    }
+
+    const birdCheckerAgent = mastra.getAgent('birdCheckerAgent');
+
+    if (!birdCheckerAgent) {
+      res.sendStatus(404);
+      return;
+    }
+
+    const response = await birdCheckerAgent.generate(
+      [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'image',
+              image: imageUrl,
+            },
+            {
+              type: 'text',
+              text: "view this image and let me know if it's a bird or not, and the scientific name of the bird without any explanation. Also summarize the location for this picture in one or two short sentences understandable by a high school student",
+            },
+          ],
+        },
+      ],
+      {
+        output: z.object({
+          bird: z.boolean(),
+          species: z.string(),
+          location: z.string(),
+        }),
+      },
+    );
+
+    const { object } = response;
+
+    console.log('response==', JSON.stringify(object, null, 2));
+
+    res.send(object);
+  } catch (err) {
+    console.log('get image metadata err===', err);
+    res.status(400).send({ msg: 'Could not fetch image metadata' });
+  }
+});
+
+app.listen(port, () => {
+  console.log(`Server running at http://localhost:${port}`);
+});
+
+```
+
+### lib/utils.ts
+```typescript
+export type ImageQuery = 'wildlife' | 'feathers' | 'flying' | 'birds';
+
+export const getRandomImage = async ({ query }: { query: ImageQuery }) => {
+  const page = Math.floor(Math.random() * 20);
+  const order_by = Math.random() < 0.5 ? 'relevant' : 'latest';
+  try {
+    const res = await fetch(`https://api.unsplash.com/search/photos?query=${query}&page=${page}&order_by=${order_by}`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Client-ID ${process.env.UNSPLASH_ACCESS_KEY}`,
+        'Accept-Version': 'v1',
+      },
+      //@ts-ignore
+      cache: 'no-store',
+    });
+
+    if (!res.ok) {
+      console.log('res-----', res);
+      return {
+        ok: false,
+        error: 'Failed to fetch image',
+      };
+    }
+
+    const data = (await res.json()) as { results: any[] };
+    const randomNo = Math.floor(Math.random() * data.results.length);
+
+    const { urls, user } = data.results[randomNo];
+
+    const resp = {
+      imageUrl: urls?.raw,
+      photographerName: user?.first_name,
+      photographerProfile: user?.links?.html,
+    };
+
+    return {
+      ok: true,
+      data: resp,
+    };
+  } catch (err) {
+    console.log('Error in get_random_image api executor===', err);
+    return {
+      ok: false,
+      error: 'Error fetching image',
+    };
+  }
+};
+
+```
+
+### mastra/agents/agent.ts
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+import { Agent } from '@mastra/core/agent';
+
+export const birdCheckerAgent = new Agent({
+  name: 'Bird checker',
+  instructions:
+    'You can view an image and figure out if it is a bird or not. You can also figure out the species of the bird and where the picture was taken.',
+  model: anthropic('claude-3-haiku-20240307'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { createLogger } from '@mastra/core/logger';
+import { Mastra } from '@mastra/core';
+
+import { birdCheckerAgent } from './agents/agent';
+
+export const mastra = new Mastra({
+  agents: { birdCheckerAgent },
+  logger: createLogger({
+    name: 'CONSOLE',
+    level: 'info',
+  }),
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+import { getRandomImage } from '../../lib/utils';
+
+export const getRandomImageTool = createTool({
+  id: 'Get a random image from unsplash',
+  description: 'Gets a random image from unsplash based on the selected option',
+  inputSchema: z.object({
+    query: z.enum(['wildlife', 'feathers', 'flying', 'birds']),
+  }),
+  execute: async ({ context }) => {
+    return getRandomImage(context);
+  },
+});
+
+```