@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/course/01-first-agent/04-project-structure.md

@@ -0,0 +1,19 @@
+# Verifying Project Structure
+
+Let's check that your project has the correct structure. You should have:
+
+1. A `src/mastra` directory that contains:
+   - `index.ts` - The main entry point for your Mastra project
+   - `agents/` - Directory containing individual agent files
+   - `scorers/` - Directory containing individual scorer files
+   - `tools/` - Directory containing individual tool files
+   - `workflows/` - Directory containing individual workflow files
+
+If the CLI created your project, you should see files like:
+
+- `agents/weather-agent.ts` - Example weather agent
+- `scorers/weather-scorer.ts` - Example weather scorer
+- `tools/weather-tool.ts` - Example weather tool
+- `workflows/weather-workflow.ts` - Example weather workflow
+
+This structure is important because it follows the Mastra convention for organizing your code. The `index.ts` file is the main entry point for your Mastra project, while the `agents` and `tools` directories contain the definitions for your agents and tools, respectively.

package/.docs/course/01-first-agent/05-running-playground.md

@@ -0,0 +1,19 @@
+# Running Mastra Studio
+
+To test your agent as you build it, you'll need to run the Mastra Studio:
+
+```bash
+npm run dev
+```
+
+This will start the studio at `http://localhost:4111`, where you can interact with your agent and test its capabilities.
+
+The studio provides a user-friendly interface for testing your agent, allowing you to:
+
+- Send messages to your agent
+- See the agent's responses
+- View the agent's thought process
+- Test tools directly
+- Debug any issues that arise
+
+In the next step, we'll create our first agent with a simple system prompt and test it in the studio.

package/.docs/course/01-first-agent/07-creating-your-agent.md

@@ -0,0 +1,50 @@
+# Creating Your Agent
+
+Let's create a simple agent that will help users analyze financial transaction data. We'll create a new file called `agents/financial-agent.ts`.
+
+First, create the new agent file at src/mastra/agents/financial-agent.ts
+
+Now add the necessary imports at the top of your file:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+// We'll import our tool in a later step
+```
+
+Now, let's create our agent:
+
+```typescript
+export const financialAgent = new Agent({
+  name: 'Financial Assistant Agent',
+  instructions: `ROLE DEFINITION
+- You are a financial assistant that helps users analyze their transaction data.
+- Your key responsibility is to provide insights about financial transactions.
+- Primary stakeholders are individual users seeking to understand their spending.
+
+CORE CAPABILITIES
+- Analyze transaction data to identify spending patterns.
+- Answer questions about specific transactions or vendors.
+- Provide basic summaries of spending by category or time period.
+
+BEHAVIORAL GUIDELINES
+- Maintain a professional and friendly communication style.
+- Keep responses concise but informative.
+- Always clarify if you need more information to answer a question.
+- Format currency values appropriately.
+- Ensure user privacy and data security.
+
+CONSTRAINTS & BOUNDARIES
+- Do not provide financial investment advice.
+- Avoid discussing topics outside of the transaction data provided.
+- Never make assumptions about the user's financial situation beyond what's in the data.
+
+SUCCESS CRITERIA
+- Deliver accurate and helpful analysis of transaction data.
+- Achieve high user satisfaction through clear and helpful responses.
+- Maintain user trust by ensuring data privacy and security.`,
+  model: 'openai/gpt-4.1-mini',
+  tools: {}, // We'll add tools in a later step
+})
+```
+
+This creates a financial assistant agent with a well-defined system prompt that outlines its role, capabilities, behavioral guidelines, constraints, and success criteria.

package/.docs/course/01-first-agent/08-exporting-your-agent.md

@@ -0,0 +1,34 @@
+# Exporting Your Agent
+
+To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file.
+
+First, import the necessary dependencies and your agent:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+import { LibSQLStore } from '@mastra/libsql'
+import { financialAgent } from './agents/financial-agent'
+
+export const mastra = new Mastra({
+  agents: {
+    financialAgent,
+  },
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: ':memory:',
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+})
+```
+
+This creates a new Mastra instance that includes:
+
+- Your financial agent
+- In-memory storage for development
+- A logger for debugging and monitoring
+
+The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and configuring the core services like storage and logging.

package/.docs/course/01-first-agent/09-testing-your-agent.md

@@ -0,0 +1,12 @@
+# Testing Your Agent
+
+Now let's test our agent in Mastra Studio:
+
+1. Make sure your development server is running with `npm run dev`
+2. Open the studio at http://localhost:4111/
+3. You should see your "Financial Assistant Agent" in the list of agents
+4. Try sending a message like "Hello, can you help me analyze my spending?"
+
+At this point, your agent can respond to basic questions but doesn't have access to any transaction data. In the next step, we'll create a custom tool to fetch transaction data from a Google Sheet.
+
+Testing your agent in the studio is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.

package/.docs/course/01-first-agent/11-creating-transactions-tool.md

@@ -0,0 +1,41 @@
+# Creating the getTransactions Tool
+
+Let's create a tool that fetches transaction data from a Google Sheet. We'll create a new file called `tools/get-transactions-tool.ts`.
+
+First, create the new tool file at src/mastra/tools/get-transactions-tool.ts
+
+Now add the necessary imports:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+```
+
+Now, let's create our tool:
+
+```typescript
+export const getTransactionsTool = createTool({
+  id: 'get-transactions',
+  description: 'Get transaction data from Google Sheets',
+  inputSchema: z.object({}), // No input parameters needed
+  outputSchema: z.object({
+    csvData: z.string(),
+  }),
+  execute: async () => {
+    return await getTransactions()
+  },
+})
+
+const getTransactions = async () => {
+  // This URL points to a public Google Sheet with transaction data
+  const url =
+    'https://docs.google.com/spreadsheets/d/e/2PACX-1vTQWaCzJAFsF4owWRHQRLo4G0-ERv31c74OOZFnqLiTLaP7NweoiX7IXvzQud2H6bdUPnIqZEA485Ux/pub?gid=0&single=true&output=csv'
+  const response = await fetch(url)
+  const data = await response.text()
+  return {
+    csvData: data,
+  }
+}
+```
+
+This tool fetches transaction data from a public Google Sheet and returns it as a string. The `createTool` function from Mastra makes it easy to define the tool's ID, description, input and output schemas, and execution logic.

package/.docs/course/01-first-agent/12-connecting-tool-to-agent.md

@@ -0,0 +1,29 @@
+# Connecting the Tool to Your Agent
+
+Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/financial-agent.ts` file and update it:
+
+1. Import the tool:
+
+```typescript
+import { getTransactionsTool } from '../tools/get-transactions-tool'
+```
+
+2. Add the tool to your agent:
+
+```typescript
+export const financialAgent = new Agent({
+  name: 'Financial Assistant Agent',
+  instructions: `ROLE DEFINITION
+  // ... existing instructions ...
+  
+  TOOLS
+  - Use the getTransactions tool to fetch financial transaction data.
+  - Analyze the transaction data to answer user questions about their spending.`,
+  model: 'openai/gpt-4.1-mini',
+  tools: { getTransactionsTool }, // Add our tool here
+})
+```
+
+By adding the tool to your agent's configuration, you're making it available for the agent to use. The agent will now be able to call the `getTransactions` tool when it needs to access transaction data.
+
+It's also important to update the agent's instructions to include information about the tool. This helps the agent understand when and how to use the tool to fulfill user requests.

package/.docs/course/01-first-agent/13-testing-your-tool.md

@@ -0,0 +1,15 @@
+# Testing Your Tool
+
+Let's test our tool and agent in Mastra Studio:
+
+1. Make sure your development server is running with `npm run dev`
+2. Open the studio at http://localhost:4111/
+3. You can test the tool directly in the Tools tab to make sure it's working
+4. Then, try asking your agent questions like:
+   - "Can you show me my recent transactions?"
+   - "How much did I spend on Amazon?"
+   - "What was my largest transaction this month?"
+
+Your agent should now be able to fetch the transaction data and answer questions about it. However, it doesn't yet have memory, so it won't remember previous conversations. We'll add that in the next step.
+
+Testing your tool directly in the studio is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.

package/.docs/course/01-first-agent/15-installing-memory.md

@@ -0,0 +1,13 @@
+# Installing Memory
+
+First, we need to install the Mastra memory package to add memory capabilities to our agent. We also install a storage adapter to persist the memory data. We will use the `libsql` storage adapter. Run the following command in your terminal:
+
+```bash
+npm install @mastra/memory@latest @mastra/libsql@latest
+```
+
+The `@mastra/memory` package provides a simple yet powerful memory system for your Mastra agents. It allows your agent to remember previous conversations and maintain context across multiple interactions.
+
+The `@mastra/libsql` package is one of many storage adapters that persists the memory data to an `SQLite` database.
+
+These packages are separate from the core Mastra package to keep the framework modular and allow you to only include the features you need in your project.

package/.docs/course/01-first-agent/16-adding-memory-to-agent.md

@@ -0,0 +1,33 @@
+# Adding Memory to Your Agent
+
+Now, let's update our agent to include memory. Open your `agents/index.ts` file and make the following changes:
+
+1. Import the Memory and LibSQLStore classes:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+import { getTransactionsTool } from '../tools'
+```
+
+2. Add memory to your agent configured by a storage instance:
+
+```typescript
+export const financialAgent = new Agent({
+  name: 'Financial Assistant Agent',
+  instructions: `ROLE DEFINITION
+  // ... existing instructions ...
+  `,
+  model: 'openai/gpt-4.1-mini',
+  tools: { getTransactionsTool },
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'learning-memory-storage',
+      url: 'file:../../memory.db', // local file-system database. Location is relative to the output directory `.mastra/output`
+    }),
+  }), // Add memory here
+})
+```
+
+By adding the `memory` property to your agent configuration, you're enabling it to remember previous conversations. The `Memory` class from the `@mastra/memory` package provides a simple way to add memory capabilities to your agent. The `LibSQLStore` class from `@mastra/libsql` persists the memory data to a `SQLite` database.

package/.docs/course/01-first-agent/17-testing-memory.md

@@ -0,0 +1,15 @@
+# Testing Your Agent with Memory
+
+Let's test our agent's memory capabilities in Mastra Studio:
+
+1. Make sure your development server is running with `npm run dev`
+2. Open the studio at http://localhost:4111/
+3. Start a conversation with your agent by asking about transactions
+4. Then, ask a follow-up question that references the previous conversation, like:
+   - "What was that largest transaction again?"
+   - "Can you categorize those Amazon purchases we talked about?"
+   - "How does my spending this month compare to what you showed me earlier?"
+
+Your agent should now be able to remember previous conversations and provide more contextual responses.
+
+With memory enabled, your agent can now maintain context across multiple interactions, creating a more natural and helpful user experience. This is especially important for financial assistants, where users may want to refer back to previous information or build on earlier conversations.

package/.docs/course/02-agent-tools-mcp/03-setting-up-mcp-configuration.md

@@ -0,0 +1,21 @@
+# Setting Up MCP Configuration
+
+Now, let's create a basic MCP configuration in your agent file. Open your `src/mastra/agents/index.ts` file and add the following imports:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+```
+
+Then, create a basic MCP configuration object:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    // We'll add servers in the next steps
+  },
+})
+```
+
+This configuration object will be used to specify which MCP servers your agent should connect to. The `servers` property is an object where each key is a unique identifier for a server, and the value contains the configuration for that server.
+
+In the upcoming steps, we'll add various MCP servers to this configuration, giving your agent access to a wide range of tools and services.

package/.docs/course/02-agent-tools-mcp/04-initializing-mcp-tools.md

@@ -0,0 +1,11 @@
+# Initializing MCP Tools
+
+Once you have the configuration set up, you need to initialize the MCP tools:
+
+```typescript
+const mcpTools = await mcp.listTools()
+```
+
+This asynchronous call fetches all the available tools from the configured MCP servers. The `listTools()` method connects to each server specified in your configuration, retrieves the available tools, and returns them in a format that can be used by your Mastra agent.
+
+The `mcpTools` object will contain all the tools provided by the MCP servers you've configured. We'll add these tools to our agent in the next step.

package/.docs/course/02-agent-tools-mcp/05-updating-your-agent.md

@@ -0,0 +1,20 @@
+# Updating Your Agent
+
+Let's update your agent to use the MCP tools. Modify your agent definition to include the MCP tools:
+
+```typescript
+export const personalAssistantAgent = new Agent({
+  name: 'Personal Assistant',
+  instructions: `
+    You are a helpful personal assistant that can help with various tasks.
+    
+    Keep your responses concise and friendly.
+  `,
+  model: 'openai/gpt-4.1-mini',
+  tools: { ...mcpTools }, // Add MCP tools to your agent
+})
+```
+
+By spreading the `mcpTools` object into your agent's `tools` property, you're making all the tools from your configured MCP servers available to your agent. This allows your agent to access and use these tools when responding to user requests.
+
+As we add more MCP servers in the upcoming steps, the `mcpTools` object will automatically include tools from those servers as well, giving your agent an expanding set of capabilities.

package/.docs/course/02-agent-tools-mcp/07-what-is-zapier-mcp.md

@@ -0,0 +1,23 @@
+# Adding the Zapier MCP Server
+
+In this step, you'll add the Zapier MCP server to your agent, giving it access to email, social media, and many other integrations available through Zapier.
+
+## What is Zapier MCP?
+
+Zapier MCP is a server that provides access to thousands of apps and services through the Zapier platform. This includes:
+
+- Email services (Gmail, Outlook, etc.)
+- Social media platforms (Twitter/X, LinkedIn, etc.)
+- Project management tools (Trello, Asana, etc.)
+- And many more
+
+By integrating the Zapier MCP server with your Mastra agent, you can give it access to all these services without having to write custom tool functions for each one. This significantly expands your agent's capabilities and makes it more useful for a wide range of tasks.
+
+## Authentication
+
+Zapier MCP requires authentication to connect. You will need two things from Zapier:
+
+1. **MCP Server URL**: The endpoint your agent connects to
+2. **API Key**: A secret key sent with every request to prove your identity
+
+The next step walks through getting both of these from the Zapier dashboard.

package/.docs/course/02-agent-tools-mcp/08-getting-zapier-mcp-url.md

@@ -0,0 +1,21 @@
+# Getting a Zapier MCP URL and API key
+
+First, you'll need to get a Zapier MCP URL and API key. This requires:
+
+1. Creating a Zapier account at [zapier.com](https://zapier.com) if you don't have one
+2. Going to [mcp.zapier.com](https://mcp.zapier.com) and selecting **+ New MCP Server**
+3. Choosing **OpenAI API** as the client type: This provides API Key authentication, which works well with custom MCP clients like Mastra
+4. Adding tools to your server (e.g., search for "Gmail" and add "Find Email" and "Send Email")
+5. Selecting the **Connect** tab to find your **MCP Server URL** and **API Key** (select **Rotate token** to generate one if needed)
+
+**Important:** Copy your API key immediately when it is shown. Zapier only displays it once. If you lose it, generate a new one by selecting **Rotate token**.
+
+Add both values to your `.env` file:
+
+```bash
+# Add these to your .env file
+ZAPIER_MCP_URL=https://mcp.zapier.com/api/v1/connect
+ZAPIER_MCP_API_KEY=your-api-key-here
+```
+
+Using environment variables keeps your credentials out of your source code. Ensure `.env` is listed in your `.gitignore` file.

package/.docs/course/02-agent-tools-mcp/09-updating-mcp-config-zapier.md

@@ -0,0 +1,29 @@
+# Updating Your MCP Configuration
+
+Now, let's update your MCP configuration in `src/mastra/agents/index.ts` to include the Zapier 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}`,
+        },
+      },
+    },
+  },
+})
+```
+
+This configuration tells your agent how to connect to the Zapier MCP server. Here is what each part does:
+
+- **`zapier`**: A unique identifier for this server in your configuration
+- **`url`**: The Zapier MCP server endpoint, read from your `.env` file
+- **`requestInit.headers`**: HTTP headers sent with every request to the server
+- **`Authorization: Bearer ...`**: Your API key, sent as a Bearer token to authenticate with Zapier
+
+The `new URL()` constructor creates a URL object from the string provided by the environment variable. The `|| ""` part provides a default empty string in case the environment variable is not set, which prevents your application from crashing if the environment variable is missing.
+
+The `requestInit` option lets you customize HTTP requests to the MCP server. Zapier requires an `Authorization` header with your API key in `Bearer {apiKey}` format to verify your identity on every request.

package/.docs/course/02-agent-tools-mcp/10-updating-agent-instructions-zapier.md

@@ -0,0 +1,29 @@
+# Updating Your Agent's Instructions
+
+Next, let's update your agent's instructions to include information about the Zapier 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 
+    and scheduling social media posts.
+    
+    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
+    
+    Keep your responses concise and friendly.
+  `,
+  model: 'openai/gpt-4.1-mini',
+  tools: { ...mcpTools },
+  memory,
+})
+```
+
+Updating your agent's instructions is crucial for helping it understand when and how to use the tools available to it. By explicitly mentioning the Gmail tools in the instructions, you're giving your agent context about what these tools do and when to use them.
+
+This helps the agent make better decisions about which tools to use when responding to user requests, resulting in more helpful and accurate responses.

package/.docs/course/02-agent-tools-mcp/12-troubleshooting-zapier.md

@@ -0,0 +1,19 @@
+# Troubleshooting
+
+If your agent can't access the Zapier tools, check:
+
+1. That your `.env` file has both `ZAPIER_MCP_URL` and `ZAPIER_MCP_API_KEY` set
+2. That your MCP config includes `requestInit.headers` with the `Authorization: Bearer` header
+3. That you've added actions to your Zapier MCP server at [mcp.zapier.com](https://mcp.zapier.com)
+4. That the tools are properly loaded by checking the Tools tab in the playground
+
+Common issues include:
+
+- **401 "Missing OAuth authorization header"**: Your config is missing the `requestInit.headers` block. Zapier MCP requires an `Authorization` header on every request.
+- **401 "Invalid OAuth token"**: Your API key is incorrect or expired. Copy it again from the Zapier MCP dashboard (**Connect** tab), or select **Rotate token** to generate a new one.
+- **No tools besides `zapier_get_configuration_url`**: You haven't added actions (e.g., Gmail) to your MCP server on the Zapier dashboard, or you haven't connected your app accounts.
+- **Environment variables not loading**: Restart your development server after changing `.env` values. Environment variables are read at startup.
+
+If you're having trouble, check the terminal output when running `npm run dev` for error messages. The MCPClient logs connection errors with details about what went wrong.
+
+In the next step, you'll add the GitHub MCP server to give your agent the ability to monitor and interact with GitHub repositories.

package/.docs/course/02-agent-tools-mcp/13-what-is-github-mcp.md

@@ -0,0 +1,14 @@
+# Adding the GitHub MCP Server
+
+In this step, we'll add the official GitHub MCP server to our agent, which will give it the ability to monitor and interact with GitHub repositories.
+
+## What is the GitHub MCP Server?
+
+The GitHub MCP server provides tools for interacting with GitHub repositories, including:
+
+- Monitoring repository activity
+- Checking pull requests and issues
+- Viewing commit history
+- Summarizing development patterns
+
+By integrating the GitHub MCP server with your Mastra agent, you can create an assistant that helps you stay on top of your GitHub repositories, track important changes, and get insights into development activity. This is particularly useful for developers and teams who want to monitor their projects without constantly checking GitHub manually.

package/.docs/course/02-agent-tools-mcp/14-getting-github-mcp-url.md

@@ -0,0 +1,40 @@
+# Setting Up the GitHub MCP Server
+
+To connect your agent to GitHub, we'll use the [official GitHub MCP server](https://github.com/github/github-mcp-server). GitHub hosts this server remotely at `https://api.githubcopilot.com/mcp/`, and authentication is done with a GitHub Personal Access Token passed in the request headers.
+
+## Creating a GitHub Personal Access Token
+
+You'll need a GitHub Personal Access Token (PAT) to authenticate with the server.
+
+1. Go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
+2. Give it a descriptive name (e.g., "Mastra Agent")
+3. Select the repositories you want your agent to access
+4. Under **Repository permissions**, grant at minimum:
+   - **Issues**: Read
+   - **Pull requests**: Read
+   - **Contents**: Read
+   - **Metadata**: Read (selected by default)
+5. Click **Generate token** and copy it
+
+Add the token to your `.env` file:
+
+```bash
+# Add this to your .env file
+GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token
+```
+
+Using an environment variable keeps your token secure and prevents it from being committed to your repository.
+
+:::note
+If you prefer to run the GitHub MCP server locally instead of using the hosted endpoint, you can use `npx` as a stdio transport:
+
+```typescript
+github: {
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-github'],
+  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PERSONAL_ACCESS_TOKEN },
+}
+```
+
+This does not require access to `api.githubcopilot.com` and works the same way as the hosted option.
+:::

package/.docs/course/02-agent-tools-mcp/15-updating-mcp-config-github.md

@@ -0,0 +1,36 @@
+# Updating Your MCP Configuration
+
+Now, let's update your MCP configuration in `src/mastra/agents/index.ts` to include the GitHub 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}`,
+        },
+      },
+    },
+  },
+})
+```
+
+This configuration adds the GitHub MCP server alongside the Zapier server we added in the previous step. The `github` key is a unique identifier for this server in your configuration.
+
+**How it works:**
+
+- The `url` property points to GitHub's hosted remote MCP server
+- The `requestInit.headers` property passes your Personal Access Token for authentication
+- The server uses Streamable HTTP transport, the same protocol used by the Zapier server
+
+By adding multiple servers to your MCP configuration, you're building a more versatile agent that can access a wider range of tools and services. Each server adds its own set of capabilities to your agent.

package/.docs/course/02-agent-tools-mcp/16-updating-agent-instructions-github.md

@@ -0,0 +1,33 @@
+# Updating Your Agent's Instructions
+
+Next, let's update your agent's instructions to include information about the GitHub 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, and scheduling social media posts.
+    
+    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
+    
+    Keep your responses concise and friendly.
+  `,
+  model: 'openai/gpt-4.1-mini',
+  tools: { ...mcpTools },
+  memory,
+})
+```
+
+By updating your agent's instructions to include information about the GitHub tools, you're helping it understand when and how to use these tools. The instructions provide context about what the GitHub tools can do, such as monitoring repository activity, checking pull requests and issues, and summarizing development patterns.
+
+This context helps your agent make better decisions about when to use the GitHub tools and how to interpret the results they provide.

package/.docs/course/02-agent-tools-mcp/18-troubleshooting-github.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+If your agent can't access the GitHub tools, check:
+
+1. That your `GITHUB_PERSONAL_ACCESS_TOKEN` is set correctly in your `.env` file
+2. That your token has the required repository permissions (Issues, Pull requests, Contents, Metadata)
+3. That the tools are properly loaded by checking the Tools tab in the playground
+
+Common issues include:
+
+- Missing or expired Personal Access Token — generate a new one at [GitHub Settings](https://github.com/settings/personal-access-tokens)
+- Insufficient token permissions — ensure your token has read access to the repositories you're targeting
+- Network issues preventing the connection to `api.githubcopilot.com`
+
+If you're having trouble, try checking the console logs for any error messages related to the GitHub MCP server. These can provide valuable clues about what might be going wrong.
+
+In the next step, we'll add the Hacker News MCP server to give your agent access to tech news and discussions.