@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

package/.docs/course/02-agent-tools-mcp/20-updating-mcp-config-hackernews.md

@@ -0,0 +1,36 @@
+# Updating Your MCP Configuration
+
+Unlike the previous MCP servers that use URLs, the Hacker News MCP server can be run directly using NPX. This means we don't need to set up any external services or authentication.
+
+Let's update your MCP configuration in `src/mastra/agents/index.ts` to include the Hacker News server:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    zapier: {
+      url: new URL(process.env.ZAPIER_MCP_URL || ''),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.ZAPIER_MCP_API_KEY}`,
+        },
+      },
+    },
+    github: {
+      url: new URL('https://api.githubcopilot.com/mcp/'),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
+        },
+      },
+    },
+    hackernews: {
+      command: 'npx',
+      args: ['-y', '@devabdultech/hn-mcp-server'],
+    },
+  },
+})
+```
+
+This configuration tells MCP to run the Hacker News server using NPX when needed. The `-y` flag automatically confirms any prompts, making it seamless to use.
+
+Unlike the Zapier and GitHub servers that connect to external services via URLs, the Hacker News server is run locally using NPX. This approach is simpler because it doesn't require any authentication or external service setup.

package/.docs/course/02-agent-tools-mcp/21-updating-agent-instructions-hackernews.md

@@ -0,0 +1,38 @@
+# Updating Your Agent's Instructions
+
+Next, let's update your agent's instructions to include information about the Hacker News tools:
+
+```typescript
+export const personalAssistantAgent = new Agent({
+  name: 'Personal Assistant',
+  instructions: `
+    You are a helpful personal assistant that can help with various tasks such as email, 
+    monitoring github activity, scheduling social media posts, and providing tech news.
+    
+    You have access to the following tools:
+    
+    1. Gmail:
+       - Use these tools for reading and categorizing emails from Gmail
+       - You can categorize emails by priority, identify action items, and summarize content
+       - You can also use this tool to send emails
+    
+    2. GitHub:
+       - Use these tools for monitoring and summarizing GitHub activity
+       - You can summarize recent commits, pull requests, issues, and development patterns
+    
+    3. Hackernews:
+       - Use this tool to search for stories on Hackernews
+       - You can use it to get the top stories or specific stories
+       - You can use it to retrieve comments for stories
+    
+    Keep your responses concise and friendly.
+  `,
+  model: 'openai/gpt-5.4',
+  tools: { ...mcpTools },
+  memory,
+})
+```
+
+By updating your agent's instructions to include information about the Hacker News tools, you're helping it understand when and how to use these tools. The instructions provide context about what the Hacker News tools can do, such as searching for stories, retrieving top stories, and accessing comments.
+
+This context helps your agent make better decisions about when to use the Hacker News tools and how to interpret the results they provide. When a user asks about tech news or specific topics on Hacker News, your agent will know to use these tools to provide relevant information.

package/.docs/course/02-agent-tools-mcp/26-updating-mcp-config-filesystem.md

@@ -0,0 +1,43 @@
+# Updating Your MCP Configuration
+
+Now, let's update your MCP configuration in `src/mastra/agents/index.ts` to include the Filesystem server:
+
+```typescript
+import path from 'path'
+
+const mcp = new MCPClient({
+  servers: {
+    zapier: {
+      url: new URL(process.env.ZAPIER_MCP_URL || ''),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.ZAPIER_MCP_API_KEY}`,
+        },
+      },
+    },
+    github: {
+      url: new URL('https://api.githubcopilot.com/mcp/'),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
+        },
+      },
+    },
+    hackernews: {
+      command: 'npx',
+      args: ['-y', '@devabdultech/hn-mcp-server'],
+    },
+    textEditor: {
+      command: 'pnpx',
+      args: [
+        `@modelcontextprotocol/server-filesystem`,
+        path.join(process.cwd(), '..', '..', 'notes'), // relative to output directory
+      ],
+    },
+  },
+})
+```
+
+This configuration tells MCP to run the Filesystem server using PNPX, pointing it to the "notes" directory we created. The `path.join(process.cwd(), "notes")` ensures that the path is correct regardless of where the application is run from.
+
+The `textEditor` key is a unique identifier for this server in your configuration. The `command` property specifies that we want to use PNPX to run the server, and the `args` property provides the arguments to pass to PNPX, including the package name and the path to the notes directory.

package/.docs/course/02-agent-tools-mcp/27-updating-agent-instructions-filesystem.md

@@ -0,0 +1,45 @@
+# Updating Your Agent's Instructions
+
+Next, let's update your agent's instructions to include information about the Filesystem tools:
+
+```typescript
+export const personalAssistantAgent = new Agent({
+  name: 'Personal Assistant',
+  instructions: `
+    You are a helpful personal assistant that can help with various tasks such as email, 
+    monitoring github activity, scheduling social media posts, providing tech news,
+    and managing notes and to-do lists.
+    
+    You have access to the following tools:
+    
+    1. Gmail:
+       - Use these tools for reading and categorizing emails from Gmail
+       - You can categorize emails by priority, identify action items, and summarize content
+       - You can also use this tool to send emails
+    
+    2. GitHub:
+       - Use these tools for monitoring and summarizing GitHub activity
+       - You can summarize recent commits, pull requests, issues, and development patterns
+    
+    3. Hackernews:
+       - Use this tool to search for stories on Hackernews
+       - You can use it to get the top stories or specific stories
+       - You can use it to retrieve comments for stories
+    
+    4. Filesystem:
+       - You also have filesystem read/write access to a notes directory. 
+       - You can use that to store info for later use or organize info for the user.
+       - You can use this notes directory to keep track of to-do list items for the user.
+       - Notes dir: ${path.join(process.cwd(), 'notes')}
+    
+    Keep your responses concise and friendly.
+  `,
+  model: 'openai/gpt-5.4',
+  tools: { ...mcpTools },
+  memory,
+})
+```
+
+By updating your agent's instructions to include information about the Filesystem tools, you're helping it understand when and how to use these tools. The instructions provide context about what the Filesystem tools can do, such as storing information for later use and keeping track of to-do list items.
+
+This context helps your agent make better decisions about when to use the Filesystem tools and how to organize the information it stores. The inclusion of the notes directory path in the instructions ensures that your agent knows exactly where it can read from and write to.

package/.docs/course/02-agent-tools-mcp/31-enhancing-memory-configuration.md

@@ -0,0 +1,78 @@
+# Enhancing Memory Configuration
+
+Finally, let's enhance our memory configuration to make our agent even more helpful:
+
+```typescript
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db',
+  }),
+  vector: new LibSQLVector({
+    id: 'learning-memory-vector',
+    url: 'file:../../memory.db',
+  }),
+  embedder: 'openai/text-embedding-3-small',
+  options: {
+    // Keep last 20 messages in context
+    lastMessages: 20,
+    // Enable semantic search to find relevant past conversations
+    semanticRecall: {
+      topK: 3,
+      messageRange: {
+        before: 2,
+        after: 1,
+      },
+    },
+    // Enable working memory to remember user information
+    workingMemory: {
+      enabled: true,
+      template: `
+      <user>
+         <first_name></first_name>
+         <username></username>
+         <preferences></preferences>
+         <interests></interests>
+         <conversation_style></conversation_style>
+       </user>`,
+    },
+  },
+})
+```
+
+And update the agent instructions to use this enhanced memory:
+
+```typescript
+export const personalAssistantAgent = new Agent({
+  name: 'Personal Assistant',
+  instructions: `
+    // ... existing instructions ...
+    
+    You have access to conversation memory and can remember details about users.
+    When you learn something about a user, update their working memory using the appropriate tool.
+    This includes:
+    - Their interests
+    - Their preferences
+    - Their conversation style (formal, casual, etc.)
+    - Any other relevant information that would help personalize the conversation
+
+    Always maintain a helpful and professional tone.
+    Use the stored information to provide more personalized responses.
+  `,
+  model: 'openai/gpt-5.4',
+  tools: { ...mcpTools },
+  memory,
+})
+```
+
+This enhanced memory configuration gives your agent more sophisticated memory capabilities:
+
+1. **Conversation History**: The `lastMessages` option keeps the last 20 messages in context, allowing your agent to reference recent conversations.
+
+2. **Semantic Recall**: The `semanticRecall` option enables your agent to find relevant past conversations using semantic search, even if they happened a long time ago. For `semanticRecall` to work, you need to have a vector store and an embedder configured
+
+3. **Working Memory**: The `workingMemory` option allows your agent to remember specific information about users, such as their preferences and interests, and use that information to provide more personalized responses.
+
+By updating your agent's instructions to include information about these memory capabilities, you're helping it understand how to use them effectively to provide a better user experience.

package/.docs/course/02-agent-tools-mcp/32-conclusion.md

@@ -0,0 +1,17 @@
+# Conclusion
+
+Congratulations! You've successfully enhanced your Mastra agent with MCP servers, giving it powerful capabilities including:
+
+1. Email and social media integration through Zapier
+2. GitHub monitoring through the official GitHub MCP server
+3. Tech news access through the Hacker News MCP server
+4. Local file management through the Filesystem MCP server
+5. Enhanced memory for personalized interactions
+
+Your agent is now a versatile personal assistant that can help with a wide range of tasks. Feel free to experiment with different MCP servers and configurations to further enhance your agent's capabilities.
+
+The power of MCP lies in its ability to connect your agent to a wide variety of external services and data sources without requiring you to write custom tool functions for each one. This modular approach makes it easy to add new capabilities to your agent as needed.
+
+As you continue to develop your Mastra agent, consider exploring other MCP servers and tools that might be useful for your specific use case. The Mastra ecosystem is constantly growing, with new tools and capabilities being added regularly.
+
+For more information on MCP and available servers, check out the [Mastra MCP documentation](https://mastra.ai/docs/mcp/overview).

package/.docs/course/03-agent-memory/03-installing-memory.md

@@ -0,0 +1,13 @@
+# Installing Memory
+
+Let's start by installing the Mastra memory package:
+
+```bash
+npm install @mastra/memory@latest @mastra/libsql@latest
+```
+
+The `@mastra/memory` package provides all the functionality you need to add memory capabilities to your Mastra agents. It includes support for conversation history, semantic recall, and working memory.
+
+The `@mastra/libsql` package is **one of many** storage adapters that complement the memory package. The purpose of a storage adapter is to provide a way to persist the memory data to a database or other storage system. The `@mastra/libsql` package provides a storage adapter for LibSQL, which is a fast, open-source fork of SQLite.
+
+These packages are separate from the core Mastra package, allowing you to only include them when you need memory capabilities in your project. This modular approach helps keep your project dependencies lean when you don't need all features.

package/.docs/course/03-agent-memory/04-creating-basic-memory-agent.md

@@ -0,0 +1,36 @@
+# Creating a Basic Memory Agent
+
+Now, let's create a simple agent with memory capabilities. We'll start with the basics and add more advanced features in the following steps.
+
+Create or update your `src/mastra/agents/index.ts` file:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+// Create a basic memory instance
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }),
+})
+
+// Create an agent with memory
+export const memoryAgent = new Agent({
+  name: 'MemoryAgent',
+  instructions: `
+    You are a helpful assistant with memory capabilities.
+    You can remember previous conversations and user preferences.
+    When a user shares information about themselves, acknowledge it and remember it for future reference.
+    If asked about something mentioned earlier in the conversation, recall it accurately.
+  `,
+  model: 'openai/gpt-5.4',
+  memory: memory,
+})
+```
+
+In this example, we're creating a basic `Memory` instance without any special configuration. This default configuration will still provide your agent with the ability to remember previous messages in the conversation.
+
+The key part is adding the `memory` property to your agent configuration, which connects the memory instance to your agent.

package/.docs/course/03-agent-memory/05-updating-mastra-export.md

@@ -0,0 +1,18 @@
+# Updating Your Mastra Export
+
+Make sure to update your `src/mastra/index.ts` file to include your new memory agent:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { memoryAgent } from './agents'
+
+export const mastra: Mastra = new Mastra({
+  agents: {
+    memoryAgent,
+  },
+})
+```
+
+This step is essential for making your agent available in the Mastra playground. The `mastra` export is the main entry point for your Mastra application, and it needs to include all the agents you want to use.
+
+By adding your `memoryAgent` to the `agents` object in the Mastra configuration, you're registering it with the Mastra system, making it available for use in the playground and other parts of your application.

package/.docs/course/03-agent-memory/07-understanding-memory-threads.md

@@ -0,0 +1,49 @@
+# Managing Conversation History
+
+In this step, we'll learn how to configure conversation history and understand memory threads in Mastra. Conversation history allows your agent to remember recent interactions, which is essential for maintaining context in ongoing conversations.
+
+## Understanding Memory Threads
+
+Mastra organizes memory into threads, which are records that identify specific conversation histories. Each thread uses two important 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_alice`)
+
+These identifiers allow memory to work properly outside of the playground. They help Mastra distinguish between different conversations and users, ensuring that the right memory is associated with the right conversation.
+
+Without these identifiers, your agent would have no way to know which conversation history to retrieve when a user sends a message. The playground handles these identifiers automatically, but you'll need to manage them yourself when using memory in your own applications.
+
+## Thread ID and Resource ID Relationship
+
+**Important:** Each thread has an owner (its `resourceId`) that is set when the thread is created. Once created, a thread's owner cannot be changed.
+
+The relationship works like this:
+
+- **One thread → One owner** (each thread has exactly one `resourceId` that identifies its owner)
+- **One resource → Many threads** (a user can have multiple separate conversations)
+- **One thread → Messages with different resourceIds** (messages can have varying `resourceId` values for attribution and filtering purposes)
+
+### Common Pitfall: Thread ID Reuse
+
+If you create a thread with `threadId: "abc"` and `resourceId: "user-alice"`, you cannot later query or create another thread with `threadId: "abc"` but `resourceId: "user-bob"`. This will cause an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+This error means you're trying to access a thread with the wrong owner's ID. Thread IDs are database primary keys and must be globally unique - you cannot reuse the same thread ID for different thread owners.
+
+### Generating Thread IDs
+
+The safest approach is to use UUIDs to avoid accidentally reusing thread IDs:
+
+```typescript
+// Using UUIDs (recommended)
+const threadId = crypto.randomUUID() // "550e8400-e29b-41d4-a716-446655440000"
+
+// Or combine resource ID with a unique suffix
+const threadId = `${resourceId}_${Date.now()}` // "user_alice_1737907200000"
+```
+
+Avoid reusing simple identifiers like `"conversation_1"` for threads owned by different users, as this creates confusion about thread ownership.

package/.docs/course/03-agent-memory/08-configuring-conversation-history.md

@@ -0,0 +1,36 @@
+# Configuring Conversation History
+
+By default, the `Memory` instance includes the last 10 messages from the current memory thread in each new request. You can customize this by configuring the `lastMessages` option:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+// Create a memory instance with custom conversation history settings
+const memory = new Memory({
+  storage: new LibSQLStore({
+    url: 'file:../../memory.db',
+  }),
+  options: {
+    lastMessages: 20, // Include the last 20 messages in the context instead of the default 10
+  },
+})
+
+// Create an agent with the configured memory
+export const memoryAgent = new Agent({
+  name: 'MemoryAgent',
+  instructions: `
+    You are a helpful assistant with memory capabilities.
+    You can remember previous conversations and user preferences.
+    When a user shares information about themselves, acknowledge it and remember it for future reference.
+    If asked about something mentioned earlier in the conversation, recall it accurately.
+  `,
+  model: 'openai/gpt-5.4',
+  memory: memory,
+})
+```
+
+The `lastMessages` option controls how many of the most recent messages are included in the agent's context window. This is important because language models have a limited context window size, and including too many messages can push out other important information.
+
+You'll want to balance between having enough context for the agent to understand the conversation and not overwhelming the context window with too much history.

package/.docs/course/03-agent-memory/09-using-memory-in-application.md

@@ -0,0 +1,19 @@
+# Using Memory in Your Application
+
+When using memory in your own application (outside the playground), you need to provide the `resourceId` and `threadId` with each agent call:
+
+```typescript
+// Example of using memory in your application
+const response = await memoryAgent.stream('Hello, my name is Alice.', {
+  resourceId: 'user_alice',
+  threadId: 'conversation_123',
+})
+```
+
+**Important:** Without these IDs, your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add IDs yourself when using memory in your application.
+
+The `resourceId` should be a unique identifier for the user or entity that owns the conversation. This could be a user ID from your authentication system, an email address, or any other unique identifier.
+
+The `threadId` should be a unique identifier for the specific conversation. This allows a single user to have multiple separate conversations with your agent, each with its own memory thread.
+
+In a real application, you might generate these IDs when a user starts a new conversation and store them in your database or client-side storage to reuse in subsequent requests.

package/.docs/course/03-agent-memory/10-storage-configuration.md

@@ -0,0 +1,29 @@
+# Storage Configuration
+
+Conversation history relies on a storage adapter to persist messages. By default, Mastra uses a LibSQL store that saves messages to a local database. You can configure this or use other storage options:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  // Configure storage
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // Local database. Relative to the output folder
+  }),
+  options: {
+    lastMessages: 20,
+  },
+})
+```
+
+Mastra supports several storage options, including:
+
+- LibSQL (default, local SQLite)
+- PostgreSQL
+- Upstash (Redis)
+
+The storage adapter is responsible for persisting memory data, including conversation history and working memory. This allows your agent to remember conversations even after your application restarts.
+
+For development and testing, the default LibSQL store is usually sufficient. For production applications, you might want to use a more robust storage option like PostgreSQL or a cloud-based solution like Upstash.

package/.docs/course/03-agent-memory/12-handling-memory-frontend.md

@@ -0,0 +1,62 @@
+# Handling Memory in Frontend Applications
+
+When building a frontend application that uses Mastra memory, it's important to 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.
+
+Here's a simplified example of how to handle this in a React application:
+
+```tsx
+import { useState } from 'react'
+import { memoryAgent } from './agents'
+
+function ChatApp() {
+  const [messages, setMessages] = useState([])
+  const [input, setInput] = useState('')
+
+  const handleSendMessage = async () => {
+    // Add user message to UI
+    setMessages([...messages, { role: 'user', content: input }])
+
+    // Only send the newest message to the agent
+    const response = await memoryAgent.stream(input, {
+      resourceId: 'user_123',
+      threadId: 'conversation_456',
+    })
+
+    // Add agent response to UI
+    setMessages([...messages, { role: 'assistant', content: response }])
+    setInput('')
+  }
+
+  return (
+    <div>
+      {/* Display messages */}
+      <div>
+        {messages.map((msg, index) => (
+          <div key={index}>
+            <strong>{msg.role}:</strong> {msg.content}
+          </div>
+        ))}
+      </div>
+
+      {/* Input for new messages */}
+      <input
+        value={input}
+        onChange={e => setInput(e.target.value)}
+        onKeyPress={e => e.key === 'Enter' && handleSendMessage()}
+      />
+      <button onClick={handleSendMessage}>Send</button>
+    </div>
+  )
+}
+```
+
+This example demonstrates a common pattern for handling memory in a frontend application:
+
+1. Store the conversation messages in the UI state for display purposes
+2. When sending a message to the agent, only send the newest message
+3. Include the `resourceId` and `threadId` with each agent call
+4. Let Mastra handle retrieving and injecting the conversation history
+
+This approach ensures that your agent has access to the conversation history without duplicating messages in the context window.
+
+In the next step, we'll explore semantic recall, which allows your agent to remember information from older conversations that are no longer in the recent history.

package/.docs/course/03-agent-memory/13-vector-store-configuration.md

@@ -0,0 +1,29 @@
+# Vector Store Configuration
+
+In addition to the memory storage adapters, Mastra also provides vector store adapters useful for storing and retrieving vector embeddings. One of these is the `LibSQLVector` adapter, which provides a simple interface for storing and retrieving vector embeddings in a LibSQL vector database.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    id: 'learning-memory-vector',
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }),
+})
+```
+
+Mastra supports several vector store options, including:
+
+- LibSQL
+- Chroma
+- Pinecone
+- Qdrant
+- Postgres (with pgvector)
+
+The vector store is responsible for storing and retrieving the vector embeddings used for semantic search.

package/.docs/course/03-agent-memory/16-configuring-semantic-recall.md

@@ -0,0 +1,42 @@
+# Configuring Semantic Recall
+
+Let's update our agent with custom semantic recall settings:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+// Create a memory instance with semantic recall configuration
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }), // Storage for message history
+  vector: new LibSQLVector({
+    id: 'learning-memory-vector',
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }), // Vector database for semantic search
+  embedder: 'openai/text-embedding-3-small', // Embedder for message embeddings
+  options: {
+    lastMessages: 20, // Include the last 20 messages in the context
+    semanticRecall: true, // Enable semantic recall with default settings
+  },
+})
+
+// Create an agent with the configured memory
+export const memoryAgent = new Agent({
+  name: 'MemoryAgent',
+  instructions: `
+    You are a helpful assistant with advanced memory capabilities.
+    You can remember previous conversations and user preferences.
+    When a user shares information about themselves, acknowledge it and remember it for future reference.
+    If asked about something mentioned earlier in the conversation, recall it accurately.
+    You can also recall relevant information from older conversations when appropriate.
+  `,
+  model: 'openai/gpt-5.4',
+  memory: memory,
+})
+```
+
+For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any compatible embedding model for this. In this example, we're using OpenAI's `openai/text-embedding-3-small` model.