@mastra/mcp-docs-server 1.1.4 → 1.1.5

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

@@ -1,304 +0,0 @@
-# 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

@@ -1,238 +0,0 @@
-# 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