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

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";
+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](/docs/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](/docs/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)

package/.docs/raw/memory/memory-processors.mdx

@@ -0,0 +1,131 @@
+# Memory Processors
+
+Memory Processors allow you to modify the list of messages retrieved from memory _before_ they are added to the agent's context window and sent to the LLM. This is useful for managing context size, filtering content, and optimizing performance.
+
+Processors operate on the messages retrieved based on your memory configuration (e.g., `lastMessages`, `semanticRecall`). They do **not** affect the new incoming user message.
+
+## Built-in Processors
+
+Mastra provides built-in processors:
+
+### `TokenLimiter`
+
+This processor is used to prevent errors caused by exceeding the LLM's context window limit. It counts the tokens in the retrieved memory messages and removes the oldest messages until the total count is below the specified `limit`.
+
+```typescript copy showLineNumbers {9-12}
+import { Memory } from "@mastra/memory";
+import { TokenLimiter } from "@mastra/memory/processors";
+import { Agent } from "@mastra/core";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    processors: [
+      // Ensure the total tokens from memory don't exceed ~127k
+      new TokenLimiter(127000),
+    ],
+  }),
+});
+```
+
+The `TokenLimiter` uses the `o200k_base` encoding by default (suitable for GPT-4o). You can specify other encodings if needed for different models:
+
+```typescript copy showLineNumbers {6-9}
+// Import the encoding you need (e.g., for older OpenAI models)
+import cl100k_base from "js-tiktoken/ranks/cl100k_base";
+
+const memoryForOlderModel = new Memory({
+  processors: [
+    new TokenLimiter({
+      limit: 16000, // Example limit for a 16k context model
+      encoding: cl100k_base,
+    }),
+  ],
+});
+```
+
+See the [OpenAI cookbook](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken#encodings) or [`js-tiktoken` repo](https://github.com/dqbd/tiktoken) for more on encodings.
+
+### `ToolCallFilter`
+
+This processor removes tool calls from the memory messages sent to the LLM. It saves tokens by excluding potentially verbose tool interactions from the context, which is useful if the details aren't needed for future interactions. It's also useful if you always want your agent to call a specific tool again and not rely on previous tool results in memory.
+
+```typescript copy showLineNumbers {5-14}
+import { Memory } from "@mastra/memory";
+import { ToolCallFilter, TokenLimiter } from "@mastra/memory/processors";
+
+const memoryFilteringTools = new Memory({
+  processors: [
+    // Example 1: Remove all tool calls/results
+    new ToolCallFilter(),
+
+    // Example 2: Remove only noisy image generation tool calls/results
+    new ToolCallFilter({ exclude: ["generateImageTool"] }),
+
+    // Always place TokenLimiter last
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+## Applying Multiple Processors
+
+You can chain multiple processors. They execute in the order they appear in the `processors` array. The output of one processor becomes the input for the next.
+
+**Order matters!** It's generally best practice to place `TokenLimiter` **last** in the chain. This ensures it operates on the final set of messages after other filtering has occurred, providing the most accurate token limit enforcement.
+
+```typescript copy showLineNumbers {7-14}
+import { Memory } from "@mastra/memory";
+import { ToolCallFilter, TokenLimiter } from "@mastra/memory/processors";
+// Assume a hypothetical 'PIIFilter' custom processor exists
+// import { PIIFilter } from './custom-processors';
+
+const memoryWithMultipleProcessors = new Memory({
+  processors: [
+    // 1. Filter specific tool calls first
+    new ToolCallFilter({ exclude: ["verboseDebugTool"] }),
+    // 2. Apply custom filtering (e.g., remove hypothetical PII - use with caution)
+    // new PIIFilter(),
+    // 3. Apply token limiting as the final step
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+## Creating Custom Processors
+
+You can create custom logic by extending the base `MemoryProcessor` class.
+
+```typescript copy showLineNumbers {4-19,23-26}
+import { Memory, CoreMessage } from "@mastra/memory";
+import { MemoryProcessor, MemoryProcessorOpts } from "@mastra/core/memory";
+
+class ConversationOnlyFilter extends MemoryProcessor {
+  constructor() {
+    // Provide a name for easier debugging if needed
+    super({ name: "ConversationOnlyFilter" });
+  }
+
+  process(
+    messages: CoreMessage[],
+    _opts: MemoryProcessorOpts = {}, // Options passed during memory retrieval, rarely needed here
+  ): CoreMessage[] {
+    // Filter messages based on role
+    return messages.filter(
+      (msg) => msg.role === "user" || msg.role === "assistant",
+    );
+  }
+}
+
+// Use the custom processor
+const memoryWithCustomFilter = new Memory({
+  processors: [
+    new ConversationOnlyFilter(),
+    new TokenLimiter(127000), // Still apply token limiting
+  ],
+});
+```
+
+When creating custom processors avoid mutating the input `messages` array or its objects directly.
+

package/.docs/raw/memory/overview.mdx

@@ -0,0 +1,119 @@
+## Overview
+
+Memory is how agents manage the context that's available to them, it's a condensation of all chat messages into their context window.
+
+## The Context Window
+
+The context window is the total information visible to the language model at any given time.
+
+In Mastra, context is broken up into three parts: system instructions and information about the user ([working memory](./working-memory.mdx)), recent messages ([message history](#conversation-history)), and older messages that are relevant to the user’s query ([semantic recall](./semantic-recall.mdx)).
+
+In addition, we provide [memory processors](./memory-processors.mdx) to trim context or remove information if the context is too long.
+
+## Quick Start
+
+The fastest way to see memory in action is using the built-in development playground.
+
+If you haven't already, create a new Mastra project following the main [Getting Started guide](/docs/getting-started/installation).
+
+**1. Install the memory package:**
+
+```bash npm2yarn copy
+npm install @mastra/memory
+```
+
+**2. Create an agent and attach a `Memory` instance:**
+
+```typescript filename="src/mastra/agents/index.ts" {10}
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+export const myMemoryAgent = new Agent({
+  name: "MemoryAgent",
+  instructions: "...",
+  model: openai("gpt-4o"),
+
+  memory: new Memory(),
+});
+```
+
+**3. Start the Development Server:**
+
+```bash npm2yarn copy
+npm run dev
+```
+
+**4. Open the playground (http://localhost:4111) and select your `MemoryAgent`:**
+
+Send a few messages and notice that it remembers information across turns:
+
+```
+➡️ You: My favorite color is blue.
+⬅️ Agent: Got it! I'll remember that your favorite color is blue.
+➡️ You: What is my favorite color?
+⬅️ Agent: Your favorite color is blue.
+```
+
+## Memory Threads
+
+Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:
+
+1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
+2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
+
+```typescript {2,3}
+const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
+  resourceId: "user_alice",
+  threadId: "conversation_123",
+});
+```
+
+**Important:** without these ID's your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID's yourself when using memory in your application.
+
+## Conversation History
+
+By default, the `Memory` instance includes the [last 40 messages](../reference/memory/Memory.mdx) from the current Memory thread in each new request. This provides the agent with immediate conversational context.
+
+```ts {3}
+const memory = new Memory({
+  options: {
+    lastMessages: 10,
+  },
+});
+```
+
+**Important:** Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the [AI SDK Memory Example](../../examples/memory/use-chat.mdx) for how to handle this with when using the `useChat` frontend hooks.
+
+### Storage Configuration
+
+Conversation history relies on a [storage adapter](/docs/reference/memory/Memory#parameters) to store messages.
+
+```ts {7-12}
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/core/storage/libsql";
+
+const agent = new Agent({
+  memory: new Memory({
+    // this is the default storage db if omitted
+    storage: new LibSQLStore({
+      config: {
+        url: "file:local.db",
+      },
+    }),
+  }),
+});
+```
+
+**Storage code Examples**:
+
+- [LibSQL](/examples/memory/memory-with-libsql)
+- [Postgres](/examples/memory/memory-with-pg)
+- [Upstash](/examples/memory/memory-with-upstash)
+
+## Next Steps
+
+Now that you understand the core concepts, continue to [semantic recall](./semantic-recall.mdx) to learn how to add RAG memory to your Mastra agents.
+
+Alternatively you can visit the [configuration reference](../../reference/memory/Memory.mdx) for available options, or browse [usage examples](../../examples/memory/use-chat.mdx).