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

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.

package/.docs/raw/integrations/index.mdx

@@ -0,0 +1,213 @@
+---
+title: "Using Mastra Integrations | Mastra Local Development Docs"
+description: Documentation for Mastra integrations, which are auto-generated, type-safe API clients for third-party services.
+---
+
+# Using Mastra Integrations
+
+Integrations in Mastra are auto-generated, type-safe API clients for third-party services. They can be used as tools for agents or as steps in workflows.
+
+## Installing an Integration
+
+Mastra's default integrations are packaged as individually installable npm modules. You can add an integration to your project by installing it via npm and importing it into your Mastra configuration.
+
+### Example: Adding the GitHub Integration
+
+1. **Install the Integration Package**
+
+To install the GitHub integration, run:
+
+```bash
+npm install @mastra/github
+```
+
+2. **Add the Integration to Your Project**
+
+Create a new file for your integrations (e.g., `src/mastra/integrations/index.ts`) and import the integration:
+
+```typescript filename="src/mastra/integrations/index.ts" showLineNumbers copy
+import { GithubIntegration } from "@mastra/github";
+
+export const github = new GithubIntegration({
+  config: {
+    PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PAT!,
+  },
+});
+```
+
+Make sure to replace `process.env.GITHUB_PAT!` with your actual GitHub Personal Access Token or ensure that the environment variable is properly set.
+
+3. **Use the Integration in Tools or Workflows**
+
+You can now use the integration when defining tools for your agents or in workflows.
+
+```typescript filename="src/mastra/tools/index.ts" showLineNumbers copy
+import { createTool } from "@mastra/core";
+import { z } from "zod";
+import { github } from "../integrations";
+
+export const getMainBranchRef = createTool({
+  id: "getMainBranchRef",
+  description: "Fetch the main branch reference from a GitHub repository",
+  inputSchema: z.object({
+    owner: z.string(),
+    repo: z.string(),
+  }),
+  outputSchema: z.object({
+    ref: z.string().optional(),
+  }),
+  execute: async ({ context }) => {
+    const client = await github.getApiClient();
+
+    const mainRef = await client.gitGetRef({
+      path: {
+        owner: context.owner,
+        repo: context.repo,
+        ref: "heads/main",
+      },
+    });
+
+    return { ref: mainRef.data?.ref };
+  },
+});
+```
+
+In the example above:
+
+- We import the `github` integration.
+- We define a tool called `getMainBranchRef` that uses the GitHub API client to fetch the reference of the main branch of a repository.
+- The tool accepts `owner` and `repo` as inputs and returns the reference string.
+
+## Using Integrations in Agents
+
+Once you've defined tools that utilize integrations, you can include these tools in your agents.
+
+```typescript filename="src/mastra/agents/index.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { getMainBranchRef } from "../tools";
+
+export const codeReviewAgent = new Agent({
+  name: "Code Review Agent",
+  instructions:
+    "An agent that reviews code repositories and provides feedback.",
+  model: openai("gpt-4o-mini"),
+  tools: {
+    getMainBranchRef,
+    // other tools...
+  },
+});
+```
+
+In this setup:
+
+- We create an agent named `Code Review Agent`.
+- We include the `getMainBranchRef` tool in the agent's available tools.
+- The agent can now use this tool to interact with GitHub repositories during conversations.
+
+## Environment Configuration
+
+Ensure that any required API keys or tokens for your integrations are properly set in your environment variables. For example, with the GitHub integration, you need to set your GitHub Personal Access Token:
+
+```bash
+GITHUB_PAT=your_personal_access_token
+```
+
+Consider using a `.env` file or another secure method to manage sensitive credentials.
+
+### Example: Adding the Mem0 Integration
+
+In this example you'll learn how to use the [Mem0](https://mem0.ai) platform to add long-term memory capabilities to an agent via tool-use.
+This memory integration can work alongside Mastra's own [agent memory features](https://mastra.ai/docs/agents/agent-memory).
+Mem0 enables your agent to memorize and later remember facts per-user across all interactions with that user, while Mastra's memory works per-thread. Using the two in conjunction will allow Mem0 to store long term memories across conversations/interactions, while Mastra's memory will maintain linear conversation history in individual conversations.
+
+1. **Install the Integration Package**
+
+To install the Mem0 integration, run:
+
+```bash
+npm install @mastra/mem0
+```
+
+2. **Add the Integration to Your Project**
+
+Create a new file for your integrations (e.g., `src/mastra/integrations/index.ts`) and import the integration:
+
+```typescript filename="src/mastra/integrations/index.ts" showLineNumbers copy
+import { Mem0Integration } from "@mastra/mem0";
+
+export const mem0 = new Mem0Integration({
+  config: {
+    apiKey: process.env.MEM0_API_KEY!,
+    userId: "alice",
+  },
+});
+```
+
+3. **Use the Integration in Tools or Workflows**
+
+You can now use the integration when defining tools for your agents or in workflows.
+
+```typescript filename="src/mastra/tools/index.ts" showLineNumbers copy
+import { createTool } from "@mastra/core";
+import { z } from "zod";
+import { mem0 } from "../integrations";
+
+export const mem0RememberTool = createTool({
+  id: "Mem0-remember",
+  description:
+    "Remember your agent memories that you've previously saved using the Mem0-memorize tool.",
+  inputSchema: z.object({
+    question: z
+      .string()
+      .describe("Question used to look up the answer in saved memories."),
+  }),
+  outputSchema: z.object({
+    answer: z.string().describe("Remembered answer"),
+  }),
+  execute: async ({ context }) => {
+    console.log(`Searching memory "${context.question}"`);
+    const memory = await mem0.searchMemory(context.question);
+    console.log(`\nFound memory "${memory}"\n`);
+
+    return {
+      answer: memory,
+    };
+  },
+});
+
+export const mem0MemorizeTool = createTool({
+  id: "Mem0-memorize",
+  description:
+    "Save information to mem0 so you can remember it later using the Mem0-remember tool.",
+  inputSchema: z.object({
+    statement: z.string().describe("A statement to save into memory"),
+  }),
+  execute: async ({ context }) => {
+    console.log(`\nCreating memory "${context.statement}"\n`);
+    // to reduce latency memories can be saved async without blocking tool execution
+    void mem0.createMemory(context.statement).then(() => {
+      console.log(`\nMemory "${context.statement}" saved.\n`);
+    });
+    return { success: true };
+  },
+});
+```
+
+In the example above:
+
+- We import the `@mastra/mem0` integration.
+- We define two tools that uses the Mem0 API client to create new memories and recall previously saved memories.
+- The tool accepts `question` as an input and returns the memory as a string.
+
+## Available Integrations
+
+Mastra provides several built-in integrations; primarily API-key based integrations that do not require OAuth. Some available integrations including Github, Stripe, Resend, Firecrawl, and more.
+
+Check [Mastra's codebase](https://github.com/mastra-ai/mastra/tree/main/integrations) or [npm packages](https://www.npmjs.com/search?q=%22%40mastra%22) for a full list of available integrations.
+
+## Conclusion
+
+Integrations in Mastra enable your AI agents and workflows to interact with external services seamlessly. By installing and configuring integrations, you can extend the capabilities of your application to include operations such as fetching data from APIs, sending messages, or managing resources in third-party systems.
+
+Remember to consult the documentation of each integration for specific usage details and to adhere to best practices for security and type safety.

package/.docs/raw/local-dev/add-to-existing-project.mdx

@@ -0,0 +1,48 @@
+---
+title: "Adding to an Existing Project | Mastra Local Development Docs"
+description: "Add Mastra to your existing Node.js applications"
+---
+
+# Adding to an Existing Project
+
+You can add Mastra to an existing project using the CLI:
+
+```bash npm2yarn copy
+npm install -g mastra@latest 
+mastra init
+```
+
+Changes made to project:
+1. Creates `src/mastra` directory with entry point
+2. Adds required dependencies
+3. Configures TypeScript compiler options
+
+
+## Interactive Setup
+
+Running commands without arguments starts a CLI prompt for:
+
+1. Component selection
+2. LLM provider configuration
+3. API key setup
+4. Example code inclusion
+
+## Non-Interactive Setup
+
+To initialize mastra in non-interactive mode use the following command arguments:
+
+```bash
+Arguments:
+  --components     Specify components: agents, tools, workflows
+  --llm-provider   LLM provider: openai, anthropic, or groq
+  --add-example    Include example implementation
+  --llm-api-key    Provider API key
+  --dir            Directory for Mastra files (defaults to src/)
+```
+For more details, refer to the [mastra init CLI documentation](../../reference/cli/init).
+
+
+
+
+
+

package/.docs/raw/local-dev/creating-a-new-project.mdx

@@ -0,0 +1,54 @@
+---
+title: "Creating a new Project | Mastra Local Development Docs"
+description: "Create new Mastra projects or add Mastra to existing Node.js applications using the CLI"
+---
+
+# Creating a new project
+
+You can create a new project using the `create-mastra` package:
+
+```bash npm2yarn copy
+npm create mastra@latest 
+```
+
+You can also create a new project by using the `mastra` CLI directly:
+
+```bash npm2yarn copy
+npm install -g mastra@latest 
+mastra create
+```
+
+## Interactive Setup
+
+Running commands without arguments starts a CLI prompt for:
+
+1. Project name
+1. Component selection
+2. LLM provider configuration
+3. API key setup
+4. Example code inclusion
+
+## Non-Interactive Setup
+
+To initialize mastra in non-interactive mode use the following command arguments:
+
+```bash
+Arguments:
+  --components     Specify components: agents, tools, workflows
+  --llm-provider   LLM provider: openai, anthropic, groq, google, or cerebras
+  --add-example    Include example implementation
+  --llm-api-key    Provider API key
+  --project-name   Project name that will be used in package.json and as the project directory name
+```
+
+
+
+Generated project structure:
+```
+my-project/
+├── src/
+│   └── mastra/
+│       └── index.ts    # Mastra entry point
+├── package.json
+└── tsconfig.json
+```

package/.docs/raw/local-dev/mastra-dev.mdx

@@ -0,0 +1,108 @@
+---
+title: "Inspecting Agents with `mastra dev` | Mastra Local Dev Docs"
+description: Documentation for the Mastra local development environment for Mastra applications.
+---
+import YouTube from "../../../components/youtube";
+
+# Local Development Environment
+
+Mastra provides a local development environment where you can test your agents, workflows, and tools while developing locally.
+
+<YouTube id="spGlcTEjuXY" />
+
+## Launch Development Server
+
+You can launch the Mastra development environment using the Mastra CLI by running:
+
+```bash
+mastra dev
+```
+
+By default, the server runs at http://localhost:4111, but you can change the port with the `--port` flag.
+
+## Dev Playground
+
+`mastra dev` serves a playground UI for interacting with your agents, workflows, and tools. The playground provides dedicated interfaces for testing each component of your Mastra application during development.
+
+### Agent Playground
+
+The Agent playground provides an interactive chat interface where you can test and debug your agents during development. Key features include:
+
+- **Chat Interface**: Directly interact with your agents to test their responses and behavior.
+- **Prompt CMS**: Experiment with different system instructions for your agent:
+  - A/B test different prompt versions.
+  - Track performance metrics for each variant.
+  - Select and deploy the most effective prompt version.
+- **Agent Traces**: View detailed execution traces to understand how your agent processes requests, including:
+  - Prompt construction.
+  - Tool usage.
+  - Decision-making steps.
+  - Response generation.
+- **Agent Evals**: When you've set up [Agent evaluation metrics](/docs/evals/overview), you can:
+  - Run evaluations directly from the playground.
+  - View evaluation results and metrics.
+  - Compare agent performance across different test cases.
+
+### Workflow Playground
+
+The Workflow playground helps you visualize and test your workflow implementations:
+
+- **Workflow Visualization**: Workflow graph visualization.
+
+- **Run Workflows**:
+  - Trigger test workflow runs with custom input data.
+  - Debug workflow logic and conditions.
+  - Simulate different execution paths.
+  - View detailed execution logs for each step.
+
+- **Workflow Traces**: Examine detailed execution traces that show:
+  - Step-by-step workflow progression.
+  - State transitions and data flow.
+  - Tool invocations and their results.
+  - Decision points and branching logic.
+  - Error handling and recovery paths.
+
+### Tools Playground
+
+The Tools playground allows you to test your custom tools in isolation:
+
+- Test individual tools without running a full agent or workflow.
+- Input test data and view tool responses.
+- Debug tool implementation and error handling.
+- Verify tool input/output schemas.
+- Monitor tool performance and execution time.
+
+## REST API Endpoints
+
+`mastra dev` also spins up REST API routes for your agents and workflows via the local [Mastra Server](/docs/deployment/server). This allows you to test your API endpoints before deployment. See [Mastra Dev reference](/reference/cli/dev#routes) for more details about all endpoints.
+
+You can then leverage the [Mastra Client](/docs/deployment/client) SDK to interact with your served REST API routes seamlessly.
+
+## OpenAPI Specification
+
+`mastra dev` provides an OpenAPI spec at http://localhost:4111/openapi.json
+
+## Local Dev Architecture
+
+The local development server is designed to run without any external dependencies or containerization. This is achieved through:
+
+- **Dev Server**: Uses [Hono](https://hono.dev) as the underlying framework to power the [Mastra Server](/docs/deployment/server).
+
+- **In-Memory Storage**: Uses [LibSQL](https://libsql.org/) memory adapters for:
+  - Agent memory management.
+  - Trace storage.
+  - Evals storage.
+  - Workflow snapshots.
+
+- **Vector Storage**: Uses [FastEmbed](https://github.com/qdrant/fastembed) for:
+  - Default embedding generation.
+  - Vector storage and retrieval.
+  - Semantic search capabilities.
+
+This architecture allows you to start developing immediately without setting up databases or vector stores, while still maintaining production-like behavior in your local environment.
+
+## Summary
+
+`mastra dev` makes it easy to develop, debug, and iterate on your AI logic in a self-contained environment before deploying to production.
+
+- [Mastra Dev reference](../../reference/cli/dev.mdx)