@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/guides/guide/github-actions-pr-description.md

@@ -0,0 +1,236 @@
+# Building a PR Description Agent for GitHub Actions
+
+In this guide, you'll build a [GitHub Action](https://docs.github.com/en/actions) that uses a Mastra agent to read pull request diffs, generate multi-language summaries, and write them directly to the PR description in the GitHub UI. The action runs whenever a pull request is created or updated and regenerates the description as the diff changes.
+
+This approach is similar to AI-powered PR tools like [CodeRabbit](https://coderabbit.ai/) and [Greptile](https://www.greptile.com/), but built using native GitHub Actions workflows and Mastra agents.
+
+The setup consists of three parts:
+
+- A Mastra agent that generates the description
+- A GitHub Actions workflow that triggers on pull requests
+- A Node.js script that connects the workflow to the agent
+
+The finished action writes a description with summaries in English, Spanish, and Japanese, each marked with a flag emoji for easy scanning. For example:
+
+```text
+🇬🇧 English
+This PR integrates Astro into the project, adding configuration files and updating scripts to support Astro development.
+
+🇪🇸 Español
+Este PR integra Astro en el proyecto, añadiendo archivos de configuración y actualizando scripts para soportar el desarrollo con Astro.
+
+🇯🇵 日本語
+このPRは、Astroをプロジェクトに統合し、Astro開発をサポートするための設定ファイルを追加し、スクリプトを更新します。
+```
+
+## Before you begin
+
+- A Mastra project (see [Quickstart](https://mastra.ai/guides/getting-started/quickstart))
+- An API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai)
+- Node.js `v22.13.0` or later
+
+### Set up repository secrets
+
+The workflow needs access to your model provider API key. Add it as a repository secret in GitHub:
+
+1. Go to your repository on GitHub
+
+2. Navigate to **Settings** > **Secrets and variables** > **Actions**
+
+3. Click **New repository secret**
+
+4. Add your API key with the name `OPENAI_API_KEY` (or the appropriate key for your provider)
+
+   ![Screenshot of repository secrets in GitHub UI](/assets/images/github-action-repository-secrets-4e97642b3aa65178a3459a5deebe6f79.jpg)
+
+The workflow references this secret as `${{ secrets.OPENAI_API_KEY }}` and makes it available to the Mastra agent at runtime.
+
+## Create the description agent
+
+The PR description agent is responsible for turning a git diff into a clear, reviewer-friendly pull request description.
+
+This agent receives the raw diff from a pull request. It generates descriptions in the configured languages and formats the output using emoji flags so each language section is easy to scan in the PR.
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const descriptionAgent = new Agent({
+  id: 'description-agent',
+  name: 'PR Description Agent',
+  instructions: `You are a helpful assistant that creates clear, concise PR descriptions.
+
+When given a git diff of changed files, you will:
+1. Analyze the changes to understand what was modified
+2. Write a brief summary and list of changes
+3. Output the same content in English, Spanish, and Japanese
+
+Guidelines:
+- Be concise but informative
+- Focus on the "what" and "why" of changes
+- Use technical terms appropriately
+- Keep bullet points short and scannable
+- Each language section should contain the same information, naturally translated
+
+Output format:
+
+### 🇬🇧 English
+
+[1-2 sentence summary]
+
+- [Change 1]
+- [Change 2]
+- [Change 3]
+
+---
+
+### 🇪🇸 Español
+
+[Same summary in Spanish]
+
+- [Same changes in Spanish]
+
+---
+
+### 🇯🇵 日本語
+
+[Same summary in Japanese]
+
+- [Same changes in Japanese]
+`,
+  model: 'openai/gpt-4o',
+})
+```
+
+### Test the agent locally
+
+Before deploying the workflow, you can test the agent in [Mastra Studio](https://mastra.ai/docs/getting-started/studio) to verify it generates descriptions correctly.
+
+1. Get a diff from any public GitHub PR by appending `.diff` to the PR URL:
+
+   ```text
+   https://github.com/owner/repo/pull/123.diff
+   ```
+
+2. Open the PR Description Agent in Studio and paste the diff content with this prompt:
+
+"Please create a PR description for the following changes. `<paste the diff content here>`"
+
+The agent will return a formatted description with sections in English, Spanish, and Japanese.
+
+## GitHub Actions
+
+GitHub Actions run your workflows in short-lived environments on GitHub's infrastructure. Each run starts with a clean virtual machine, checks out your code, installs dependencies, runs your workflow steps, and then shuts down. Nothing persists between runs unless you explicitly save it as an artifact or cache.
+
+### Create the workflow
+
+GitHub Actions workflows live in the `.github/workflows` directory. Create a `.github` directory at the root of your project, then create a `workflows` directory inside it. Add a file named `pr-description.yml`.
+
+This workflow runs whenever a pull request is opened or updated. It generates a diff for the PR, calls the Mastra agent to describe the changes, and writes the description directly into the PR in the GitHub UI.
+
+```yaml
+name: PR Description Generator
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  PR_DIFF_FILE: /tmp/pr_diff.txt
+  PR_DESCRIPTION_FILE: /tmp/pr_description.md
+
+jobs:
+  generate-description:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - id: pr
+        run: |
+          BASE_REF=$(gh pr view ${{ github.event.pull_request.number }} --json baseRefName -q '.baseRefName')
+          git fetch origin $BASE_REF
+          git diff origin/$BASE_REF...HEAD -- . ':!package-lock.json' > $PR_DIFF_FILE
+
+      - run: npx tsx .github/scripts/generate-description.ts
+
+      - run: gh pr edit ${{ github.event.pull_request.number }} --body-file $PR_DESCRIPTION_FILE
+```
+
+#### The workflow explained
+
+- **`on: pull_request`**: Runs when a pull request is opened or updated.
+- **`permissions: pull-requests: write`**: Allows the workflow to update the PR description.
+- **`env`**: Defines shared file paths used across steps and reads required values from repository secrets, including the model API key used by the Mastra agent.
+- **`actions/checkout@v4` + git commands**: Checks out the full repository history, fetches the PR base branch, and writes the PR diff to `/tmp/pr_diff.txt`.
+- **`actions/setup-node@v4`**: Sets up the Node.js runtime used by the workflow.
+- **`npm ci`**: Installs the repository's Node.js dependencies from the lockfile.
+- **`generate-description.ts`**: Reads `/tmp/pr_diff.txt`, calls the Mastra agent, and writes the generated description to `/tmp/pr_description.md`.
+- **`gh pr edit`**: Updates the pull request description using the contents of `/tmp/pr_description.md`.
+
+> **Note:** The workflow excludes `package-lock.json` when generating the diff. Lockfiles are often large and noisy, and including them can overwhelm the agent's context window and make the resulting description harder to reason about.
+
+### Create the workflow script
+
+Create a `scripts` directory inside `.github` and add a file named `generate-description.ts`.
+
+This script reads the PR diff from `PR_DIFF_FILE`, generates a description using the Mastra agent, and writes the result to `PR_DESCRIPTION_FILE` for the workflow to publish to the pull request.
+
+```typescript
+import { readFileSync, writeFileSync } from 'fs'
+import { mastra } from '../../src/mastra'
+
+const agent = mastra.getAgent('descriptionAgent')
+
+await agent.generate(
+  `Please create a PR description for the following changes.
+
+Git diff:
+\`\`\`diff
+${readFileSync(process.env.PR_DIFF_FILE!, 'utf-8')}
+\`\`\``,
+  {
+    onError: () => {
+      writeFileSync(
+        process.env.PR_DESCRIPTION_FILE!,
+        'This PR diff is too large to generate a description automatically.',
+      )
+    },
+    onFinish: result => {
+      writeFileSync(process.env.PR_DESCRIPTION_FILE!, result.text)
+    },
+  },
+)
+```
+
+#### The workflow script explained
+
+- **`mastra.getAgent("descriptionAgent")`**: Gets the Mastra agent that generates the PR description.
+- **`agent.generate(...)`**: Reads the pull request diff from `PR_DIFF_FILE` and asks the agent to write a PR description.
+- **`onError` callback**: Writes a fallback message to `PR_DESCRIPTION_FILE` when the diff is too large to process.
+- **`onFinish` callback**: Writes the generated PR description to `PR_DESCRIPTION_FILE`.
+
+## Next steps
+
+You now have a GitHub Action that generates multi-language PR descriptions using a Mastra agent. Once the workflow and supporting files are merged into your main branch, the agent will run automatically the next time a pull request is created or updated. You can monitor the run in the **Actions** tab of your repository.
+
+From here, you can customize the agent instructions, change the output languages, or extend the workflow to handle other events.
+
+To learn more:
+
+- Read the [agents](https://mastra.ai/docs/agents/overview) documentation
+- Give your agent [tools](https://mastra.ai/docs/agents/using-tools) to fetch additional context
+- Explore other [GitHub Actions triggers](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) like issue comments or releases

package/.docs/guides/guide/notes-mcp-server.md

@@ -0,0 +1,416 @@
+# Building a Notes MCP Server
+
+In this guide, you'll learn how to build a complete MCP (Model Context Protocol) server from scratch. This server will manage a collection of markdown notes and has these features:
+
+1. **List and Read Notes**: Allow clients to browse and view markdown files stored on the server
+2. **Write Notes**: Provide a tool for creating or updating notes
+3. **Offer Smart Prompts**: Generate contextual prompts, like creating a daily note template or summarizing existing content
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+
+## Adding necessary dependencies & files
+
+Before you can create an MCP server you first need to install additional dependencies and set up a boilerplate folder structure.
+
+1. Add `@mastra/mcp` to your project:
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/mcp@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/mcp@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/mcp@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/mcp@latest
+   ```
+
+2. After following the default [installation guide](https://mastra.ai/guides/getting-started/quickstart) your project will include files that are not relevant for this guide. You can safely remove them:
+
+   ```bash
+   rm -rf src/mastra/agents src/mastra/workflows src/mastra/tools/weather-tool.ts
+   ```
+
+   You should also change the `src/mastra/index.ts` file like so:
+
+   ```ts
+   import { Mastra } from '@mastra/core'
+   import { PinoLogger } from '@mastra/loggers'
+   import { LibSQLStore } from '@mastra/libsql'
+
+   export const mastra = new Mastra({
+     storage: new LibSQLStore({
+       id: 'mastra-storage',
+       // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
+       url: ':memory:',
+     }),
+     logger: new PinoLogger({
+       name: 'Mastra',
+       level: 'info',
+     }),
+   })
+   ```
+
+3. Create a dedicated directory for your MCP server's logic and a `notes` directory for your notes:
+
+   ```bash
+   mkdir notes src/mastra/mcp
+   ```
+
+   Create the following files:
+
+   ```bash
+   touch src/mastra/mcp/{server,resources,prompts}.ts
+   ```
+
+   - `server.ts`: Will contain the main MCP server configuration
+   - `resources.ts`: Will handle listing and reading note files
+   - `prompts.ts`: Will contain the logic for the smart prompts
+
+   The resulting directory structure should look like this:
+
+   ```text
+   <your-project-name>/
+   ├── notes/
+   └── src/
+       └── mastra/
+           ├── index.ts
+           ├── mcp/
+           │   ├── server.ts
+           │   ├── resources.ts
+           │   └── prompts.ts
+           └── tools/
+   ```
+
+## Creating the MCP Server
+
+Let's add the MCP server!
+
+1. In `src/mastra/mcp/server.ts`, define the MCP server instance:
+
+   ```typescript
+   import { MCPServer } from '@mastra/mcp'
+
+   export const notes = new MCPServer({
+     id: 'notes',
+     name: 'Notes Server',
+     version: '0.1.0',
+     tools: {},
+   })
+   ```
+
+   Register this MCP server in your Mastra instance at `src/mastra/index.ts`. The key `notes` is the public identifier for your MCP server:
+
+   ```typescript
+   import { Mastra } from '@mastra/core'
+   import { PinoLogger } from '@mastra/loggers'
+   import { LibSQLStore } from '@mastra/libsql'
+   import { notes } from './mcp/server'
+
+   export const mastra = new Mastra({
+     storage: new LibSQLStore({
+       id: 'mastra-storage',
+       // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
+       url: ':memory:',
+     }),
+     logger: new PinoLogger({
+       name: 'Mastra',
+       level: 'info',
+     }),
+     mcpServers: {
+       notes,
+     },
+   })
+   ```
+
+2. Resource handlers allow clients to discover and read the content your server manages. Implement handlers to work with markdown files in the `notes` directory. Add to the `src/mastra/mcp/resources.ts` file:
+
+   ```typescript
+   import fs from 'fs/promises'
+   import path from 'path'
+   import { fileURLToPath } from 'url'
+   import type { MCPServerResources, Resource } from '@mastra/mcp'
+
+   const __filename = fileURLToPath(import.meta.url)
+   const __dirname = path.dirname(__filename)
+   const NOTES_DIR = path.resolve(__dirname, '../../notes') // relative to the default output directory
+
+   const listNoteFiles = async (): Promise<Resource[]> => {
+     try {
+       await fs.mkdir(NOTES_DIR, { recursive: true })
+       const files = await fs.readdir(NOTES_DIR)
+       return files
+         .filter(file => file.endsWith('.md'))
+         .map(file => {
+           const title = file.replace('.md', '')
+           return {
+             uri: `notes://${title}`,
+             name: title,
+             description: `A note about ${title}`,
+             mime_type: 'text/markdown',
+           }
+         })
+     } catch (error) {
+       console.error('Error listing note resources:', error)
+       return []
+     }
+   }
+
+   const readNoteFile = async (uri: string): Promise<string | null> => {
+     const title = uri.replace('notes://', '')
+     const notePath = path.join(NOTES_DIR, `${title}.md`)
+     try {
+       return await fs.readFile(notePath, 'utf-8')
+     } catch (error) {
+       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+         console.error(`Error reading resource ${uri}:`, error)
+       }
+       return null
+     }
+   }
+
+   export const resourceHandlers: MCPServerResources = {
+     listResources: listNoteFiles,
+     getResourceContent: async ({ uri }: { uri: string }) => {
+       const content = await readNoteFile(uri)
+       if (content === null) return { text: '' }
+       return { text: content }
+     },
+   }
+   ```
+
+   Register these resource handlers in `src/mastra/mcp/server.ts`:
+
+   ```typescript
+   import { MCPServer } from '@mastra/mcp'
+   import { resourceHandlers } from './resources'
+
+   export const notes = new MCPServer({
+     id: 'notes',
+     name: 'Notes Server',
+     version: '0.1.0',
+     tools: {},
+     resources: resourceHandlers,
+   })
+   ```
+
+3. Tools are the actions your server can perform. Let's create a `write` tool. First, define the tool in `src/mastra/tools/write-note.ts`:
+
+   ```typescript
+   import { createTool } from '@mastra/core/tools'
+   import { z } from 'zod'
+   import { fileURLToPath } from 'url'
+   import path from 'node:path'
+   import fs from 'fs/promises'
+
+   const __filename = fileURLToPath(import.meta.url)
+   const __dirname = path.dirname(__filename)
+   const NOTES_DIR = path.resolve(__dirname, '../../../notes')
+
+   export const writeNoteTool = createTool({
+     id: 'write',
+     description: 'Write a new note or overwrite an existing one.',
+     inputSchema: z.object({
+       title: z.string().nonempty().describe('The title of the note. This will be the filename.'),
+       content: z.string().nonempty().describe('The markdown content of the note.'),
+     }),
+     outputSchema: z.string().nonempty(),
+     execute: async inputData => {
+       try {
+         const { title, content } = inputData
+         const filePath = path.join(NOTES_DIR, `${title}.md`)
+         await fs.mkdir(NOTES_DIR, { recursive: true })
+         await fs.writeFile(filePath, content, 'utf-8')
+         return `Successfully wrote to note \"${title}\".`
+       } catch (error: any) {
+         return `Error writing note: ${error.message}`
+       }
+     },
+   })
+   ```
+
+   Register this tool in `src/mastra/mcp/server.ts`:
+
+   ```typescript
+   import { MCPServer } from '@mastra/mcp'
+   import { resourceHandlers } from './resources'
+   import { writeNoteTool } from '../tools/write-note'
+
+   export const notes = new MCPServer({
+     id: 'notes',
+     name: 'Notes Server',
+     version: '0.1.0',
+     resources: resourceHandlers,
+     tools: {
+       write: writeNoteTool,
+     },
+   })
+   ```
+
+4. Prompt handlers provide ready-to-use prompts for clients. You'll add these three:
+
+   - Daily note
+   - Summarize a note
+   - Brainstorm ideas
+
+   This requires a few markdown-parsing libraries you need to install:
+
+   ```bash
+   npm install unified remark-parse gray-matter @types/unist
+   ```
+
+   Implement the prompts in `src/mastra/mcp/prompts.ts`:
+
+   ```typescript
+   import type { MCPServerPrompts } from '@mastra/mcp'
+   import { unified } from 'unified'
+   import remarkParse from 'remark-parse'
+   import matter from 'gray-matter'
+   import type { Node } from 'unist'
+
+   const prompts = [
+     {
+       name: 'new_daily_note',
+       description: 'Create a new daily note.',
+       version: '1.0.0',
+     },
+     {
+       name: 'summarize_note',
+       description: 'Give me a TL;DR of the note.',
+       version: '1.0.0',
+     },
+     {
+       name: 'brainstorm_ideas',
+       description: 'Brainstorm new ideas based on a note.',
+       version: '1.0.0',
+     },
+   ]
+
+   function stringifyNode(node: Node): string {
+     if ('value' in node && typeof node.value === 'string') return node.value
+     if ('children' in node && Array.isArray(node.children))
+       return node.children.map(stringifyNode).join('')
+     return ''
+   }
+
+   export async function analyzeMarkdown(md: string) {
+     const { content } = matter(md)
+     const tree = unified().use(remarkParse).parse(content)
+     const headings: string[] = []
+     const wordCounts: Record<string, number> = {}
+     let currentHeading = 'untitled'
+     wordCounts[currentHeading] = 0
+     tree.children.forEach(node => {
+       if (node.type === 'heading' && node.depth === 2) {
+         currentHeading = stringifyNode(node)
+         headings.push(currentHeading)
+         wordCounts[currentHeading] = 0
+       } else {
+         const textContent = stringifyNode(node)
+         if (textContent.trim()) {
+           wordCounts[currentHeading] =
+             (wordCounts[currentHeading] || 0) + textContent.split(/\\s+/).length
+         }
+       }
+     })
+     return { headings, wordCounts }
+   }
+
+   const getPromptMessages: MCPServerPrompts['getPromptMessages'] = async ({ name, args }) => {
+     switch (name) {
+       case 'new_daily_note':
+         const today = new Date().toISOString().split('T')[0]
+         return [
+           {
+             role: 'user',
+             content: {
+               type: 'text',
+               text: `Create a new note titled \"${today}\" with sections: \"## Tasks\", \"## Meetings\", \"## Notes\".`,
+             },
+           },
+         ]
+       case 'summarize_note':
+         if (!args?.noteContent) throw new Error('No content provided')
+         const metaSum = await analyzeMarkdown(args.noteContent as string)
+         return [
+           {
+             role: 'user',
+             content: {
+               type: 'text',
+               text: `Summarize each section in ≤ 3 bullets.\\n\\n### Outline\\n${metaSum.headings.map(h => `- ${h} (${metaSum.wordCounts[h] || 0} words)`).join('\\n')}`.trim(),
+             },
+           },
+         ]
+       case 'brainstorm_ideas':
+         if (!args?.noteContent) throw new Error('No content provided')
+         const metaBrain = await analyzeMarkdown(args.noteContent as string)
+         return [
+           {
+             role: 'user',
+             content: {
+               type: 'text',
+               text: `Brainstorm 3 ideas for underdeveloped sections below ${args?.topic ? `on ${args.topic}` : '.'}\\n\\nUnderdeveloped sections:\\n${metaBrain.headings.length ? metaBrain.headings.map(h => `- ${h}`).join('\\n') : '- (none, pick any)'}`,
+             },
+           },
+         ]
+       default:
+         throw new Error(`Prompt \"${name}\" not found`)
+     }
+   }
+
+   export const promptHandlers: MCPServerPrompts = {
+     listPrompts: async () => prompts,
+     getPromptMessages,
+   }
+   ```
+
+   Register these prompt handlers in `src/mastra/mcp/server.ts`:
+
+   ```typescript
+   import { MCPServer } from '@mastra/mcp'
+   import { resourceHandlers } from './resources'
+   import { writeNoteTool } from '../tools/write-note'
+   import { promptHandlers } from './prompts'
+
+   export const notes = new MCPServer({
+     id: 'notes',
+     name: 'Notes Server',
+     version: '0.1.0',
+     resources: resourceHandlers,
+     prompts: promptHandlers,
+     tools: {
+       write: writeNoteTool,
+     },
+   })
+   ```
+
+## Run the Server
+
+Great, you've authored your first MCP server! Now you can try it out by starting the Mastra dev server and opening [Studio](https://mastra.ai/docs/getting-started/studio):
+
+```bash
+npm run dev
+```
+
+Open [`http://localhost:4111`](http://localhost:4111) in your browser. In the left sidebar, select **MCP Servers**. Select the **notes** MCP server.
+
+You'll now be presented with instructions on how to add the MCP server to your IDE. You're able to use this MCP server with any MCP Client. On the right side under **Available Tools** you can also select the **write** tool.
+
+Inside the **write** tool, try it out by providing `test` as a name and `this is a test` for the markdown content. After clicking on **Submit** you'll have a new `test.md` file inside `notes`.