@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

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@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 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
+- 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.
+
+---

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -0,0 +1,141 @@
+---
+title: "Using with Cursor/Windsurf | Getting Started | Mastra Docs"
+description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
+---
+
+import YouTube from "../../../components/youtube";
+
+# Mastra Tools for your agentic IDE
+
+`@mastra/mcp-docs-server` provides direct access to Mastra's complete knowledge base in Cursor, Windsurf, Cline, or any other IDE that supports MCP.
+
+It has access to documentation, code examples, technical blog posts / feature announcements, and package changelogs which your IDE can read to help you build with Mastra.
+
+<YouTube id="vciV57lF0og" />
+
+The MCP server tools have been designed to allow an agent to query the specific information it needs to complete a Mastra related task - for example: adding a Mastra feature to an agent, scaffolding a new project, or helping you understand how something works.
+
+## How it works
+
+Once it's installed in your IDE you can write prompts and assume the agent will understand everything about Mastra.
+
+### Add features
+
+- "Add evals to my agent and write tests"
+- "Write me a workflow that does the following `[task]`"
+- "Make a new tool that allows my agent to access `[3rd party API]`"
+
+### Ask about integrations
+
+- "Does Mastra work with the AI SDK?
+  How can I use it in my `[React/Svelte/etc]` project?"
+- "What's the latest Mastra news around MCP?"
+- "Does Mastra support `[provider]` speech and voice APIs? Show me an example in my code of how I can use it."
+
+### Debug or update existing code
+
+- "I'm running into a bug with agent memory, have there been any related changes or bug fixes recently?"
+- "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
+- "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
+
+**And more** - if you have a question, try asking your IDE and let it look it up for you.
+
+## Automatic Installation
+
+Run `pnpm create mastra@latest` and select Cursor or Windsurf when prompted to install the MCP server. For other IDEs, or if you already have a Mastra project, install the MCP server by following the instructions below.
+
+## Manual Installation
+
+- **Cursor**: Edit `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for global configuration
+- **Windsurf**: Edit `~/.codeium/windsurf/mcp_config.json` (only supports global configuration)
+
+Add the following configuration:
+
+### MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+### Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+## After Configuration
+
+### Cursor
+
+1. Open Cursor settings
+2. Navigate to MCP settings
+3. Click "enable" on the Mastra MCP server
+4. If you have an agent chat open, you'll need to re-open it or start a new chat to use the MCP server
+
+### Windsurf
+
+1. Fully quit and re-open Windsurf
+2. If tool calls start failing, go to Windsurfs MCP settings and re-start the MCP server. This is a common Windsurf MCP issue and isn't related to Mastra. Right now Cursor's MCP implementation is more stable than Windsurfs is.
+
+In both IDEs it may take a minute for the MCP server to start the first time as it needs to download the package from npm.
+
+## Available Agent Tools
+
+### Documentation
+
+Access Mastra's complete documentation:
+
+- Getting started / installation
+- Guides and tutorials
+- API references
+
+### Examples
+
+Browse code examples:
+
+- Complete project structures
+- Implementation patterns
+- Best practices
+
+### Blog Posts
+
+Search the blog for:
+
+- Technical posts
+- Changelog and feature announcements
+- AI news and updates
+
+### Package Changes
+
+Track updates for Mastra and `@mastra/*` packages:
+
+- Bug fixes
+- New features
+- Breaking changes
+
+## Common Issues
+
+1. **Server Not Starting**
+
+   - Ensure npx is installed and working
+   - Check for conflicting MCP servers
+   - Verify your configuration file syntax
+   - On Windows, make sure to use the Windows-specific configuration
+
+2. **Tool Calls Failing**
+   - Restart the MCP server and/or your IDE
+   - Update to the latest version of your IDE

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              |

package/.docs/raw/index.mdx

@@ -0,0 +1,22 @@
+---
+title: "Introduction | Mastra Docs"
+description: "Mastra is a TypeScript agent framework. It helps you build AI applications and features quickly. It gives you the set of primitives you need: workflows, agents, RAG, integrations, syncs and evals."
+---
+
+# About Mastra
+
+Mastra is an open-source TypeScript agent framework. 
+
+It's designed to give you the primitives you need to build AI applications and features. 
+
+You can use Mastra to build [AI agents](/docs/agents/overview.mdx) that have memory and can execute functions, or chain LLM calls in deterministic [workflows](/docs/workflows/overview.mdx). You can chat with your agents in Mastra's [local dev environment](/docs/local-dev/mastra-dev.mdx), feed them application-specific knowledge with [RAG](/docs/rag/overview.mdx), and score their outputs with Mastra's [evals](/docs/evals/overview.mdx).
+
+The main features include:
+
+* **[Model routing](https://sdk.vercel.ai/docs/introduction)**: Mastra uses the [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) for model routing, providing a unified interface to interact with any LLM provider including OpenAI, Anthropic, and Google Gemini.
+* **[Agent memory and tool calling](/docs/agents/agent-memory.mdx)**: With Mastra, you can give your agent tools (functions) that it can call. You can persist agent memory and retrieve it based on recency, semantic similarity, or conversation thread.
+* **[Workflow graphs](/docs/workflows/overview.mdx)**: When you want to execute LLM calls in a deterministic way, Mastra gives you a graph-based workflow engine. You can define discrete steps, log inputs and outputs at each step of each run, and pipe them into an observability tool. Mastra workflows have a simple syntax for control flow (`step()`, `.then()`, `.after()`) that allows branching and chaining. 
+* **[Agent development environment](/docs/local-dev/mastra-dev.mdx)**: When you're developing an agent locally, you can chat with it and see its state and memory in Mastra's agent development environment.
+* **[Retrieval-augmented generation (RAG)](/docs/rag/overview.mdx)**: Mastra gives you APIs to process documents (text, HTML, Markdown, JSON) into chunks, create embeddings, and store them in a vector database. At query time, it retrieves relevant chunks to ground LLM responses in your data, with a unified API on top of multiple vector stores (Pinecone, pgvector, etc) and embedding providers (OpenAI, Cohere, etc).
+* **[Deployment](/docs/deployment/deployment.mdx)**: Mastra supports bundling your agents and workflows within an existing React, Next.js, or Node.js application, or into standalone endpoints. The Mastra deploy helper lets you easily bundle agents and workflows into a Node.js server using Hono, or deploy it onto a serverless platform like Vercel, Cloudflare Workers, or Netlify. 
+* **[Evals](/docs/evals/overview.mdx)**: Mastra provides automated evaluation metrics that use model-graded, rule-based, and statistical methods to assess LLM outputs, with built-in metrics for toxicity, bias, relevance, and factual accuracy. You can also define your own evals.