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

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

@@ -0,0 +1,436 @@
+---
+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/reference/llm/providers-and-models)
+
+## 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
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn create mastra
+```
+</Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm create mastra
+```
+</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
+```
+
+After the prompts, `create-mastra` will set up your project directory with TypeScript, install dependencies, and configure your selected components and LLM provider.
+
+### 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>
+Extra Notes:
+
+ 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
+```
+
+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
+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
+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
+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
+- 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 dev docs on [mastra
+  init](/docs/local-dev/creating-projects#adding-to-an-existing-project).
+  
+  You can also checkout our framework specific docs e.g [Next.js](/docs/frameworks/01-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 our [Client SDK documentation](/docs/reference/client-js) 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.
+
+---

package/.docs/raw/getting-started/project-structure.mdx

@@ -0,0 +1,80 @@
+---
+title: "Local Project Structure | Getting Started | Mastra Docs"
+description: Guide on organizing folders and files in Mastra, including best practices and recommended structures.
+---
+
+import { FileTree } from 'nextra/components';
+
+# Project Structure
+
+This page provides a guide for organizing folders and files in Mastra. Mastra is a modular framework, and you can use any of the modules separately or together.
+
+You could write everything in a single file (as we showed in the quick start), or separate each agent, tool, and workflow into their own files.
+
+We don't enforce a specific folder structure, but we do recommend some best practices, and the CLI will scaffold a project with a sensible structure.
+
+## Using the CLI
+
+`mastra init` is an interactive CLI that allows you to:
+
+- **Choose a directory for Mastra files**: Specify where you want the Mastra files to be placed (default is `src/mastra`).
+- **Select components to install**: Choose which components you want to include in your project:
+  - Agents
+  - Tools
+  - Workflows
+- **Select a default LLM provider**: Choose from supported providers like OpenAI, Anthropic, or Groq.
+- **Include example code**: Decide whether to include example code to help you get started.
+
+### Example Project Structure
+
+Assuming you select all components and include example code, your project structure will look like this:
+
+<FileTree>
+  <FileTree.Folder name="root" defaultOpen>
+    <FileTree.Folder name="src" defaultOpen>
+      <FileTree.Folder name="mastra" defaultOpen>
+        <FileTree.Folder name="agents" defaultOpen>
+          <FileTree.File name="index.ts" />
+        </FileTree.Folder>
+        <FileTree.Folder name="tools" defaultOpen>
+          <FileTree.File name="index.ts" />
+        </FileTree.Folder>
+        <FileTree.Folder name="workflows" defaultOpen>
+          <FileTree.File name="index.ts" />
+        </FileTree.Folder>
+        <FileTree.File name="index.ts" />
+      </FileTree.Folder>
+    </FileTree.Folder>
+    <FileTree.File name=".env" />
+  </FileTree.Folder>
+</FileTree>
+{/* 
+```
+root/
+├── src/
+│   └── mastra/
+│       ├── agents/
+│       │   └── index.ts
+│       ├── tools/
+│       │   └── index.ts
+│       ├── workflows/
+│       │   └── index.ts
+│       ├── index.ts
+├── .env
+``` */}
+
+### Top-level Folders
+
+| Folder                 | Description                          |
+| ---------------------- | ------------------------------------ |
+| `src/mastra`           | Core application folder              |
+| `src/mastra/agents`    | Agent configurations and definitions |
+| `src/mastra/tools`     | Custom tool definitions              |
+| `src/mastra/workflows` | Workflow definitions                 |
+
+### Top-level Files
+
+| File                  | Description                        |
+| --------------------- | ---------------------------------- |
+| `src/mastra/index.ts` | Main configuration file for Mastra |
+| `.env`                | Environment variables              |