@mastra/mcp-docs-server 1.1.1-alpha.2 → 1.1.2-alpha.0

package/.docs/docs/workspace/sandbox.md

@@ -19,6 +19,7 @@ When you assign a workspace with a sandbox to an agent, Mastra automatically inc
 Available providers:
 
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) - Executes commands on the local machine
+- [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox) - Executes commands in isolated E2B cloud sandboxes
 
 ## Basic usage
 
@@ -57,5 +58,6 @@ When you configure a sandbox on a workspace, agents receive the `execute_command
 ## Related
 
 - [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)

package/.docs/guides/agent-frameworks/ai-sdk.md

@@ -83,9 +83,11 @@ const storage = new LibSQLStore({
 });
 await storage.init();
 
+const memoryStorage = await storage.getStore('memory');
+
 const model = withMastra(openai('gpt-4o'), {
   memory: {
-    storage,
+    storage: memoryStorage!,
     threadId: 'user-thread-123',
     resourceId: 'user-123',
     lastMessages: 10,
@@ -111,11 +113,13 @@ import { LibSQLStore } from '@mastra/libsql';
 const storage = new LibSQLStore({ id: 'my-app', url: 'file:./data.db' });
 await storage.init();
 
+const memoryStorage = await storage.getStore('memory');
+
 const model = withMastra(openai('gpt-4o'), {
   inputProcessors: [myGuardProcessor],
   outputProcessors: [myLoggingProcessor],
   memory: {
-    storage,
+    storage: memoryStorage!,
     threadId: 'thread-123',
     resourceId: 'user-123',
     lastMessages: 10,

package/.docs/guides/deployment/cloudflare.md

@@ -0,0 +1,99 @@
+# Deploy Mastra to Cloudflare
+
+Use `@mastra/deployer-cloudflare` to deploy your Mastra server to Cloudflare Workers. The deployer bundles your code and generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/), ready to deploy with no additional configuration.
+
+> **Info:** If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+
+## Before you begin
+
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Cloudflare](https://cloudflare.com/) account.
+
+Cloudflare Workers use an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
+
+## Installation
+
+Add the `@mastra/deployer-cloudflare` package to your project:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-cloudflare@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-cloudflare@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-cloudflare@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-cloudflare@latest
+```
+
+Import [`CloudflareDeployer`](https://mastra.ai/reference/deployer/cloudflare) and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: "your-project-name",
+    vars: {
+      NODE_ENV: "production",
+    },
+  }),
+});
+```
+
+In order to test your Cloudflare Worker locally, also install the [`wrangler` CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/):
+
+**npm**:
+
+```bash
+npm install -D wrangler
+```
+
+**pnpm**:
+
+```bash
+pnpm add -D wrangler
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev wrangler
+```
+
+**Bun**:
+
+```bash
+bun add --dev wrangler
+```
+
+## Usage
+
+After setting up your project, push it to your remote Git provider of choice (e.g. GitHub).
+
+1. Connect your repository to Cloudflare. On the "Workers & Pages" dashboard, select **Create application** and choose your Git provider in the next step. Continue with the setup process and select the repository you want to deploy.
+
+   > **Note:** Remember to set your environment variables needed to run your application (e.g. your [model provider](https://mastra.ai/models/providers) API key).
+
+2. Once you're ready, click the **Deploy** button and wait for the first deployment to complete.
+
+3. Try out your newly deployed function by going to `https://<your-project-name>.<slug>.workers.dev/api/agents`. You should get a JSON response listing all available agents.
+
+   Since the [Mastra server](https://mastra.ai/docs/server/mastra-server) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.
+
+4. You can now call your Mastra endpoints over HTTP.
+
+   > **Note:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.

package/.docs/guides/guide/code-review-bot.md

@@ -0,0 +1,221 @@
+# Building a Code Review Bot
+
+In this guide, you'll build a code review bot that automatically reviews pull requests using workspace skills. The bot loads coding standards from skill files and provides structured feedback. You'll learn how to create a workspace with a skills directory, define an [Agent Skill](https://agentskills.io) with review instructions and reference files, and connect it to an agent that performs automated reviews.
+
+## 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)
+
+## Create the workspace
+
+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. On the `Workspace` instance, configure the `skills` option to point to a skills directory. The `skills` directory will live inside the filesystem's `basePath`.
+
+```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'),
+  }),
+  skills: ['/skills'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+});
+```
+
+At the root of your project, create a new folder called `workspace`. Inside that, create a `skills` folder. This is where you'll define the code standards skill in the next step.
+
+## Create the code standards skill
+
+Skills are structured directories containing a `SKILL.md` file with instructions for the agent. The code standards skill defines the review process and references a style guide.
+
+Inside `workspace/skills`, create a new folder called `code-standards`. Create a file called `SKILL.md` and add the review instructions.
+
+```markdown
+---
+name: code-standards
+description: Automated code review standards and checks
+---
+
+# Code Review Standards
+
+Review code systematically using these steps:
+
+1. **Critical Issues**: Security vulnerabilities, memory leaks, logic bugs, missing error handling
+2. **Code Quality**: Functions over 50 lines, code duplication, confusing names, missing types
+3. **Style Guide**: Check references/style-guide.md for naming and organization
+4. **Linting**: Flag common issues like use of `var`, leftover `console.log` statements, and `debugger` statements
+
+Provide feedback in this format:
+
+**Summary**: One sentence overview
+
+**Critical Issues**: List with line numbers
+
+**Suggestions**: Improvements that would help
+
+**Positive Notes**: What the code does well
+```
+
+Inside `workspace/skills/code-standards`, create a `references` folder to hold reference materials for the skill. Author a style guide file that outlines the project's coding conventions with the file name `style-guide.md`.
+
+````markdown
+# Style Guide
+
+## Naming
+
+- Variables/Functions: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Files: `kebab-case.ts`
+- Booleans: Start with `is`, `has`, `should`
+
+## Code Organization
+
+```typescript
+// 1. Imports
+import { foo } from 'bar';
+
+// 2. Constants
+const MAX_SIZE = 100;
+
+// 3. Types
+interface User { id: string; }
+
+// 4. Functions
+function doSomething() {}
+
+// 5. Exports
+export { doSomething };
+```
+
+## Error Handling
+
+Always handle errors explicitly - never silently catch.
+
+## Comments
+
+Write "why" not "what".
+````
+
+## Create the review agent
+
+Now it's time to create the code review bot agent that uses the code-standards skill. Create a new file at `src/mastra/agents/code-reviewer.ts` and define the agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+
+export const codeReviewer = new Agent({
+  id: 'code-reviewer',
+  name: 'Code Review Bot',
+  instructions: `You are an automated code reviewer.
+
+When asked to review code:
+1. Activate the 'code-standards' skill
+2. Follow the review process from the skill
+3. Check against the style guide in skill references
+4. Be constructive and specific with line numbers`,
+  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 { codeReviewer } from './agents/code-reviewer';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: resolve(import.meta.dirname, '../../workspace'),
+  }),
+  skills: ['/skills'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+  agents: { codeReviewer },
+});
+```
+
+## Test the bot
+
+Start Mastra Studio and interact with the code review bot 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 code reviewer agent.
+
+Inside the chat input, provide a code snippet for review, such as:
+
+```text
+Review this code:
+
+function getData(id) {
+  var result = fetch('/api/data/' + id);
+  console.log(result);
+  return result;
+}
+```
+
+The bot should activate the `code-standards` skill and provide structured feedback. Since agent responses are non-deterministic, your output may vary, but you should see something similar to:
+
+```md
+**Summary**: Function has several issues with variable declaration,
+debugging statements, and missing error handling.
+
+**Critical Issues**:
+- Missing error handling for fetch (line 2)
+- No async/await for asynchronous operation (line 2)
+
+**Suggestions**:
+- Use const instead of var (line 2)
+- Remove console.log before committing (line 3)
+- Add TypeScript type for id parameter
+- Use template literals instead of concatenation
+
+**Positive Notes**:
+- Function name is clear and descriptive
+```
+
+## Next steps
+
+You can extend this bot to:
+
+- Add skills for different languages or frameworks
+- Create skills for security checks and performance reviews
+- Integrate with GitHub Actions for automatic PR reviews
+- Build a PR comment bot that leaves inline feedback
+
+Learn more:
+
+- [Agent Skills spec](https://agentskills.io)

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

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