@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/guides/guide/dev-assistant.md

@@ -0,0 +1,307 @@
+# Building a Dev Assistant
+
+In this guide, you'll build a complete development assistant that combines all workspace features:
+
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) for file management
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox) for code execution
+- [Skills](https://mastra.ai/docs/workspace/skills) for coding standards
+- [Search](https://mastra.ai/docs/workspace/search) for finding examples
+
+You'll set up a workspace with a sample project, add coding standards as a skill, and create an agent that writes code following TDD practices. By the end, you'll have an agent that can read existing code, write new implementations, run tests in a sandbox, and iterate based on results.
+
+## 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)
+
+### Install vitest
+
+The dev assistant will use [Vitest](https://vitest.dev/) to run tests inside the workspace sandbox. Install it as a dev dependency in your project:
+
+**npm**:
+
+```bash
+npm install -D vitest
+```
+
+**pnpm**:
+
+```bash
+pnpm add -D vitest
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev vitest
+```
+
+**Bun**:
+
+```bash
+bun add --dev vitest
+```
+
+## 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), [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) classes.
+
+Additionally, enable BM25 search indexing and load skills from the `skills` directory.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { resolve } from 'node:path'
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
+  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
+  skills: ['/skills'],
+  bm25: true,
+  autoIndexPaths: ['/docs', '/src'],
+})
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+At the root of your project, create a new folder called `workspace`. This is where all files will be stored and managed by the agent.
+
+## Add sample project files
+
+The workspace uses the following folder structure:
+
+- `workspace/src/`: Source code for the sample project
+- `workspace/tests/`: Test files
+- `workspace/docs/`: Project documentation
+- `workspace/skills/`: Coding standards and guidelines as [Agent Skills](https://agentskills.io)
+
+Get started by creating a `workspace/src/utils/string-helpers.ts` file with some utility functions, and a corresponding test file in `workspace/tests/string-helpers.test.ts`.
+
+```typescript
+export function capitalize(str: string): string {
+  if (!str) return str
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+}
+```
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { capitalize, slugify } from '../src/utils/string-helpers'
+
+describe('String Helpers', () => {
+  describe('capitalize', () => {
+    it('capitalizes first letter', () => {
+      expect(capitalize('hello')).toBe('Hello')
+    })
+  })
+
+  describe('slugify', () => {
+    it('converts to lowercase and replaces spaces', () => {
+      expect(slugify('Hello World')).toBe('hello-world')
+    })
+  })
+})
+```
+
+Create a skill definition at `workspace/skills/coding-standards/SKILL.md`. This tells the agent how to write and test code:
+
+```markdown
+---
+name: coding-standards
+description: Project coding standards and testing guidelines
+---
+
+# Coding Standards
+
+## Code Quality
+
+- Functions under 50 lines
+- Use descriptive variable names
+- Always add TypeScript types
+
+## Testing
+
+- Test all exported functions
+- Use AAA pattern: Arrange, Act, Assert
+- Cover happy paths and edge cases
+
+## Before Committing
+
+1. Write implementation
+2. Write comprehensive tests
+3. Run tests: `npm test`
+4. All tests must pass
+```
+
+Create a reference file at `workspace/skills/coding-standards/references/testing-guide.md` with detailed testing patterns:
+
+````markdown
+# Testing Guide
+
+## AAA Pattern
+
+```typescript
+it('descriptive test name', () => {
+  // Arrange: Set up test data
+  const input = 'test'
+
+  // Act: Execute the function
+  const result = doSomething(input)
+
+  // Assert: Verify the result
+  expect(result).toBe('expected')
+})
+```
+
+## What to Test
+
+- Happy paths (normal inputs)
+- Edge cases (empty, null, boundary values)
+- Error cases (invalid inputs, exceptions)
+````
+
+## Create the dev assistant
+
+With the workspace set up, it's time to create the development assistant agent. This agent will have instructions for adding new features using test-driven development (TDD).
+
+Create a new file `src/mastra/agents/dev-assistant.ts` and define the agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const devAssistant = new Agent({
+  id: 'dev-assistant',
+  name: 'Dev Assistant',
+  instructions: `You are a development assistant.
+
+When adding features:
+1. Activate 'coding-standards' skill
+2. Search workspace for similar code examples
+3. Write the implementation following standards
+4. Write comprehensive tests. Leave existing tests in place, only add your new tests
+5. Execute the command \`npx vitest run\` to validate that all tests pass
+6. Update documentation if needed
+
+For every new feature: Write code → Write tests → Run tests → Update docs
+
+Always explain your reasoning and steps.`,
+  model: 'openai/gpt-4o',
+})
+```
+
+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, LocalSandbox } from '@mastra/core/workspace'
+import { devAssistant } from './agents/dev-assistant'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
+  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
+  skills: ['/skills'],
+  bm25: true,
+  autoIndexPaths: ['/docs', '/src'],
+})
+
+export const mastra = new Mastra({
+  workspace,
+  agents: { devAssistant },
+})
+```
+
+## Test the assistant
+
+Start Mastra Studio 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 dev assistant.
+
+Try asking the agent to add a new function using TDD:
+
+```text
+Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.
+
+Follow TDD: write tests first, then implementation.
+```
+
+Since agent responses are non-deterministic, the exact output will vary. However, you should see the agent follow a process similar to this:
+
+1. Activate the coding-standards skill
+
+2. Search the workspace for similar code patterns
+
+3. Write tests first, for example:
+
+   ```typescript
+   describe('truncate', () => {
+     it('truncates long strings', () => {
+       expect(truncate('Hello World', 5)).toBe('He...')
+     })
+
+     it('keeps short strings unchanged', () => {
+       expect(truncate('Hi', 10)).toBe('Hi')
+     })
+
+     it('handles edge cases', () => {
+       expect(truncate('', 5)).toBe('')
+     })
+   })
+   ```
+
+4. Write the implementation, for example:
+
+   ```typescript
+   export function truncate(str: string, maxLength: number): string {
+     if (!str || maxLength < 0) return str
+     if (str.length <= maxLength) return str
+     if (maxLength === 0) return '...'
+     return str.slice(0, maxLength - 3) + '...'
+   }
+   ```
+
+5. Run tests and verify they pass
+
+## Next steps
+
+You can extend this assistant to:
+
+- Add more skills for different languages or frameworks
+- Create specialized agents for backend, frontend, or DevOps
+- Integrate with GitHub for automated PR reviews
+- Build CI/CD automation
+- Add multi-agent workflows

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

@@ -0,0 +1,238 @@
+# 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, keeps documentation organized, and prevents accidental overwrites. You'll learn how to set up a workspace filesystem, create an agent with document management instructions, and use it to generate and update documentation through conversational prompts.
+
+## 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 a `workspace/docs/README.md` file that serves 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
+
+Quick start guide for the project.
+
+## Installation
+
+```bash
+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-4o',
+})
+```
+
+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 Mastra Studio 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
+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, find the right insertion point, and 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