@mastra/mcp-docs-server 1.2.15 → 1.2.16-alpha.3

package/.docs/guides/guide/docs-manager.md

@@ -1,240 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Building a docs manager
-
-In this guide, you'll build a documentation manager that maintains your project's docs. It creates well-structured markdown files and keeps documentation organized while preventing accidental overwrites. You'll set up a workspace filesystem and create an agent with document management instructions. Then you'll use conversational prompts to generate and update documentation.
-
-## 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)
-
-## Set up the workspace
-
-The workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your `src/mastra/index.ts` file, import the [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) and [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) classes.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { resolve } from 'node:path'
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: resolve(import.meta.dirname, '../../workspace'),
-  }),
-})
-
-export const mastra = new Mastra({
-  workspace,
-})
-```
-
-At the root of your project, create a new folder called `workspace`. This is where all documentation files will be stored and managed by the agent.
-
-## Add example documentation
-
-Inside the `workspace` directory, create the following folders:
-
-- `docs/guides/`: For how-to guides
-- `docs/api/`: For API reference documentation
-- `docs/tutorials/`: For step-by-step tutorials
-
-Create `workspace/docs/README.md` as the documentation index:
-
-```markdown
-# Project Documentation
-
-Welcome to the documentation!
-
-## Sections
-
-- [Guides](./guides/): How-to guides
-- [API](./api/): API reference
-- [Tutorials](./tutorials/): Step-by-step tutorials
-```
-
-Add a sample guide so the agent can see the existing documentation style:
-
-````markdown
-# Getting Started
-
-Quickstart guide for the project.
-
-## Installation
-
-```bash npm2yarn
-npm install example-package
-```
-
-## Quick example
-
-```typescript
-import { Example } from 'example-package'
-
-const example = new Example()
-example.run()
-```
-````
-
-## Create the docs manager
-
-Now it's time to create the documentation manager agent. This agent will have instructions for creating and updating markdown files in the workspace. Create a new file `src/mastra/agents/docs-manager.ts` and define the agent:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-
-export const docsManager = new Agent({
-  id: 'docs-manager',
-  name: 'Docs Manager',
-  instructions: `You are a documentation manager that creates and maintains markdown docs.
-
-When creating new docs:
-1. Ask for topic and target audience
-2. Create well-structured markdown with clear sections
-3. Include relevant code examples with syntax highlighting
-4. Save in the appropriate directory:
-   - /docs/guides/ for user guides and how-tos
-   - /docs/api/ for API reference
-   - /docs/tutorials/ for step-by-step tutorials
-
-When updating existing docs:
-1. ALWAYS read the file first
-2. Make targeted updates without removing unrelated content
-3. Preserve existing structure and formatting
-
-Use kebab-case naming for files (getting-started.md).
-Always explain what you're creating and why.`,
-  model: 'openai/gpt-5.6-sol',
-})
-```
-
-Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { resolve } from 'node:path'
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
-import { docsManager } from './agents/docs-manager'
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: resolve(import.meta.dirname, '../../workspace'),
-  }),
-})
-
-export const mastra = new Mastra({
-  workspace,
-  agents: { docsManager },
-})
-```
-
-## Test the docs manager
-
-Start [Studio](https://mastra.ai/docs/studio/overview) and interact with the agent to see it in action.
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Open [localhost:4111](http://localhost:4111) and navigate to the docs manager.
-
-### Create a new document
-
-Ask the agent to create a tutorial:
-
-```text
-Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.
-```
-
-The agent should create a file like `docs/tutorials/authentication-setup.md`. Since agent responses are non-deterministic, the exact content will vary, but you should see something similar to:
-
-````md
-# Authentication Setup
-
-Learn how to add authentication to your application.
-
-## Installation
-
-Install the auth package:
-
-```bash npm2yarn
-npm install @example/auth
-```
-
-## Configuration
-
-Create a config file:
-
-```typescript
-// auth.config.ts
-export const authConfig = {
-  provider: 'oauth',
-  clientId: process.env.AUTH_CLIENT_ID,
-  secret: process.env.AUTH_SECRET,
-}
-```
-
-## Basic example
-
-```typescript
-import { createAuth } from '@example/auth'
-import { authConfig } from './auth.config'
-
-const auth = createAuth(authConfig)
-
-app.get('/protected', auth.requireAuth(), (req, res) => {
-  res.json({ user: req.user })
-})
-```
-````
-
-### Update an existing document
-
-Try updating an existing document:
-
-```text
-Update the getting started guide to include a section on configuration after the Quick Example
-```
-
-The agent should read the existing `getting-started.md` file and find the right insertion point. It should add the new section without disrupting existing content.
-
-### Organize documentation
-
-Ask the agent to create an index:
-
-```text
-List all tutorial files and create an index page that links to all of them
-```
-
-The agent should create a file like `/docs/tutorials/index.md` that links to all available tutorials.
-
-## Next steps
-
-You can extend this manager to:
-
-- Add BM25 or vector search to find relevant documentation
-- Create skills for documentation templates
-- Build automated doc generation from source code
-- Integrate with GitHub to update docs on commits
-- Add validation to check links and formatting

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

@@ -1,238 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# 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 quick 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 quick 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-5.6-sol',
-})
-```
-
-### Test the agent locally
-
-Before deploying the workflow, you can test the agent in [Studio](https://mastra.ai/docs/studio/overview) 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 and checks out your code. It installs dependencies before running your workflow steps. The environment shuts down when the run completes. 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 `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 `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, customize the agent instructions or change the output languages. You can also 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