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

package/.docs/raw/frameworks/next-js.mdx

@@ -0,0 +1,238 @@
+---
+title: "Getting started with Mastra and NextJS | Mastra Guides"
+description: Guide on integrating Mastra with NextJS.
+---
+import { Callout, Steps, Tabs } from "nextra/components";
+
+# Integrate Mastra in your Next.js project
+
+There are two main ways to integrate Mastra with your Next.js application: as a separate backend service or directly integrated into your Next.js app.
+
+## 1. Separate Backend Integration
+
+Best for larger projects where you want to:
+- Scale your AI backend independently
+- Keep clear separation of concerns
+- Have more deployment flexibility
+
+<Steps>
+### Create Mastra Backend
+
+Create a new Mastra project using our CLI:
+
+<Tabs items={["npx", "npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npx create-mastra@latest
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+npm create mastra
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn create mastra
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm create mastra
+```
+  </Tabs.Tab>
+</Tabs>
+
+For detailed setup instructions, see our [installation guide](/docs/getting-started/installation).
+
+### Install  MastraClient
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npm install @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn add @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm add @mastra/client-js
+```
+  </Tabs.Tab>
+</Tabs>
+
+### Use MastraClient
+
+Create a client instance and use it in your Next.js application:
+
+```typescript filename="lib/mastra.ts" copy
+import { MastraClient } from '@mastra/client-js';
+
+// Initialize the client
+export const mastraClient = new MastraClient({
+  baseUrl: process.env.NEXT_PUBLIC_MASTRA_API_URL || 'http://localhost:4111',
+});
+```
+
+Example usage in your React component:
+
+```typescript filename="app/components/SimpleWeather.tsx" copy
+'use client'
+
+import { mastraClient } from '@/lib/mastra'
+
+export function SimpleWeather() {
+  async function handleSubmit(formData: FormData) {
+    const city = formData.get('city')
+    const agent = mastraClient.getAgent('weatherAgent')
+    
+    try {
+      const response = await agent.generate({
+        messages: [{ role: 'user', content: `What's the weather like in ${city}?` }],
+      })
+      // Handle the response
+      console.log(response.text)
+    } catch (error) {
+      console.error('Error:', error)
+    }
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="city" placeholder="Enter city name" />
+      <button type="submit">Get Weather</button>
+    </form>
+  )
+}
+```
+
+### Deployment
+
+When you're ready to deploy, you can use any of our platform-specific deployers (Vercel, Netlify, Cloudflare) or deploy to any Node.js hosting platform. Check our [deployment guide](/docs/deployment/deployment) for detailed instructions.
+</Steps>
+
+## 2. Direct Integration
+
+Better for smaller projects or prototypes. This approach bundles Mastra directly with your Next.js application.
+
+<Steps>
+### Initialize Mastra in your Next.js Root
+
+First, navigate to your Next.js project root and initialize Mastra:
+
+```bash copy
+cd your-nextjs-app
+```
+
+Then run the initialization command:
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npx mastra@latest init
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn dlx mastra@latest init
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm dlx mastra@latest init
+```
+  </Tabs.Tab>
+</Tabs>
+
+This will set up Mastra in your Next.js project. For more details about init and other configuration options, see our [mastra init reference](/reference/cli/init).
+
+### Configure Next.js
+
+Add to your `next.config.js`:
+
+```js filename="next.config.js" copy
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  serverExternalPackages: ["@mastra/*"],
+  // ... your other Next.js config
+}
+
+module.exports = nextConfig
+```
+
+#### Server Actions Example
+
+```typescript filename="app/actions.ts" copy
+'use server'
+
+import { mastra } from '@/mastra'
+
+export async function getWeatherInfo(city: string) {
+  const agent = mastra.getAgent('weatherAgent')
+  
+  const result = await agent.generate(`What's the weather like in ${city}?`)
+
+  return result
+}
+```
+
+Use it in your component:
+
+```typescript filename="app/components/Weather.tsx" copy
+'use client'
+
+import { getWeatherInfo } from '../actions'
+
+export function Weather() {
+  async function handleSubmit(formData: FormData) {
+    const city = formData.get('city') as string
+    const result = await getWeatherInfo(city)
+    // Handle the result
+    console.log(result)
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="city" placeholder="Enter city name" />
+      <button type="submit">Get Weather</button>
+    </form>
+  )
+}
+```
+
+#### API Routes Example
+
+```typescript filename="app/api/chat/route.ts" copy
+import { mastra } from '@/mastra'
+import { NextResponse } from 'next/server'
+
+export async function POST(req: Request) {
+  const { city } = await req.json()
+  const agent = mastra.getAgent('weatherAgent')
+
+  const result = await agent.stream(`What's the weather like in ${city}?`)
+
+  return result.toDataStreamResponse()
+}
+```
+
+### Deployment
+
+When using direct integration, your Mastra instance will be deployed alongside your Next.js application. Ensure you:
+- Set up environment variables for your LLM API keys in your deployment platform
+- Implement proper error handling for production use
+- Monitor your AI agent's performance and costs
+</Steps>
+
+## Observability
+
+Mastra provides built-in observability features to help you monitor, debug, and optimize your AI operations. This includes:
+- Tracing of AI operations and their performance
+- Logging of prompts, completions, and errors
+- Integration with observability platforms like Langfuse and LangSmith
+
+For detailed setup instructions and configuration options specific to Next.js local development, see our [Next.js Observability Configuration Guide](/docs/deployment/logging-and-tracing#nextjs-configuration).

package/.docs/raw/getting-started/installation.mdx

@@ -0,0 +1,442 @@
+---
+title: "Installing Mastra Locally | Getting Started | Mastra Docs"
+description: Guide on installing Mastra and setting up the necessary prerequisites for running it with various LLM providers.
+---
+
+import { Callout, Steps, Tabs } from "nextra/components";
+import YouTube from "../../../components/youtube";
+
+# Installing Mastra Locally
+
+To run Mastra, you need access to an LLM. Typically, you'll want to get an API key from an LLM provider such as [OpenAI](https://platform.openai.com/), [Anthropic](https://console.anthropic.com/settings/keys), or [Google Gemini](https://ai.google.dev/gemini-api/docs). You can also run Mastra with a local LLM using [Ollama](https://ollama.ai/).
+
+## Prerequisites
+
+- Node.js `v20.0` or higher
+- Access to a [supported large language model (LLM)](/docs/frameworks/ai-sdk)
+
+## Automatic Installation
+
+<YouTube id="spGlcTEjuXY" />
+
+<Steps>
+
+### Create a New Project
+
+We recommend starting a new Mastra project using `create-mastra`, which will scaffold your project. To create
+a project, run:
+
+<Tabs items={["npx", "npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+  ```bash copy 
+  npx create-mastra@latest 
+  ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+   npm create mastra@latest 
+   ```
+   </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+   yarn create mastra@latest 
+   ```
+   </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+   pnpm create mastra@latest
+  ```
+  </Tabs.Tab>
+</Tabs>
+
+On installation, you'll be guided through the following prompts:
+
+```bash
+What do you want to name your project? my-mastra-app
+Choose components to install:
+  ◯ Agents (recommended)
+  ◯ Tools
+  ◯ Workflows
+Select default provider:
+  ◯ OpenAI (recommended)
+  ◯ Anthropic
+  ◯ Groq
+Would you like to include example code? No / Yes
+Turn your IDE into a Mastra expert? (Installs MCP server)
+  ◯ Skip for now
+  ◯ Cursor
+  ◯ Windsurf
+```
+
+After the prompts, `create-mastra` will:
+
+1. Set up your project directory with TypeScript
+2. Install dependencies
+3. Configure your selected components and LLM provider
+4. Configure the MCP server in your IDE (if selected) for instant access to docs, examples, and help while you code
+
+**MCP Note:** If you're using a different IDE, you can install the MCP server manually by following the instructions in the [MCP server docs](/docs/getting-started/mcp-docs-server). **Also** note that there are additional steps for [Cursor and Windsurf](/docs/getting-started/mcp-docs-server#after-configuration) to activate the MCP server.
+
+### Set Up your API Key
+
+Add the API key for your configured LLM provider in your `.env` file.
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-openai-key>
+```
+
+</Steps>
+
+**Non-Interactive mode**:
+If you prefer to run the command with flags (non-interactive mode) and include the example code, you can use:
+
+```bash copy
+npx create-mastra@latest  --components agents,tools --llm openai --example
+```
+
+**Configure Installation Timeout**:
+To configure and specify a timeout if installation takes too long use the timeout flag:
+
+```bash copy
+npx create-mastra@latest --timeout
+```
+
+**Note for LLMs**:
+For a quick one liner that includes examples you can run `npx -y mastra@latest --project-name <ask-the-user> --example --components "tools,agents,workflows" --llm <ask-the-user>`. The available options for the llm flag are `openai|anthropic|groq|google|cerebras`
+
+## Manual Installation
+
+<br/>
+<Steps>
+
+If you prefer to set up your Mastra project manually, follow these steps:
+
+### Create a New Project
+
+Create a project directory and navigate into it:
+
+```bash copy
+mkdir hello-mastra
+cd hello-mastra
+```
+
+Then, initialize a TypeScript project including the `@mastra/core` package:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tabs.Tab>
+  ```bash copy
+  npm init -y 
+  npm install typescript tsx @types/node mastra --save-dev 
+  npm install @mastra/core zod @ai-sdk/openai npx tsc --init 
+  ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+  pnpm init
+  pnpm add typescript tsx @types/node mastra --save-dev
+  pnpm add @mastra/core zod @ai-sdk/openai
+  pnpm dlx tsc --init 
+  ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+  yarn init -y
+  yarn add typescript tsx @types/node mastra --dev
+  yarn add @mastra/core zod @ai-sdk/openai
+  yarn dlx tsc --init 
+  ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+  ```bash copy
+  bun init -y
+  bun add typescript tsx @types/node mastra --dev
+  bun add @mastra/core zod @ai-sdk/openai
+  bunx tsc --init 
+  ```
+  </Tabs.Tab>
+</Tabs>
+
+### Initialize TypeScript
+
+Create a `tsconfig.json` file in your project root with the following configuration:
+
+```json copy
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".mastra"]
+}
+```
+
+This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
+
+### Set Up your API Key
+
+Create a `.env` file in your project root directory and add your API key:
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-openai-key>
+```
+
+Replace your_openai_api_key with your actual API key.
+
+### Create a Tool
+
+Create a `weather-tool` tool file:
+
+```bash copy
+mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts
+```
+
+Then, add the following code to `src/mastra/tools/weather-tool.ts`:
+
+```ts filename="src/mastra/tools/weather-tool.ts" showLineNumbers copy
+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";
+}
+```
+
+### Create an Agent
+
+Create a `weather` agent file:
+
+```bash copy
+mkdir -p src/mastra/agents && touch src/mastra/agents/weather.ts
+```
+
+Then, add the following code to `src/mastra/agents/weather.ts`:
+
+```ts filename="src/mastra/agents/weather.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { weatherTool } from "../tools/weather-tool";
+
+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
+- 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-mini"),
+  tools: { weatherTool },
+});
+```
+
+### Register Agent
+
+Finally, create the Mastra entry point in `src/mastra/index.ts` and register agent:
+
+```ts filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core";
+
+import { weatherAgent } from "./agents/weather";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+});
+```
+
+This registers your agent with Mastra so that `mastra dev` can discover and serve it.
+
+</Steps>
+
+## Existing Project Installation
+
+  To add Mastra to an existing project, see our Local development docs on [adding mastra to an existing project](/docs/local-dev/add-to-existing-project).
+  
+  You can also checkout our framework specific docs e.g [Next.js](/docs/frameworks/next-js)
+
+## Start the Mastra Server
+
+Mastra provides commands to serve your agents via REST endpoints
+
+### Development Server
+
+Run the following command to start the Mastra server:
+
+```bash copy
+npm run dev
+```
+
+If you have the mastra CLI installed, run:
+
+```bash copy
+mastra dev
+```
+
+This command creates REST API endpoints for your agents.
+
+### Test the Endpoint
+
+You can test the agent's endpoint using `curl` or `fetch`:
+
+<Tabs items={['curl', 'fetch']}>
+  <Tabs.Tab>
+```bash copy
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+-H "Content-Type: application/json" \
+-d '{"messages": ["What is the weather in London?"]}'
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```js copy showLineNumbers
+fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    messages: ['What is the weather in London?'],
+  }),
+})
+  .then(response => response.json())
+  .then(data => {
+    console.log('Agent response:', data.text);
+  })
+  .catch(error => {
+    console.error('Error:', error);
+  });
+```
+  </Tabs.Tab>
+</Tabs>
+
+## Use Mastra on the Client
+
+To use Mastra in your frontend applications, you can use our type-safe client SDK to
+interact with your Mastra REST APIs.
+
+See the [Mastra Client SDK documentation](/docs/deployment/client) for detailed usage instructions.
+
+## Run from the command line
+
+If you'd like to directly call agents from the command line, you can create a script to get an agent and call it:
+
+```ts filename="src/index.ts" showLineNumbers copy
+import { mastra } from "./mastra";
+
+async function main() {
+  const agent = await mastra.getAgent("weatherAgent");
+
+  const result = await agent.generate("What is the weather in London?");
+
+  console.log("Agent response:", result.text);
+}
+
+main();
+```
+
+Then, run the script to test that everything is set up correctly:
+
+```bash copy
+npx tsx src/index.ts
+```
+
+This should output the agent's response to your console.
+
+---