@mastra/mcp-docs-server 1.1.1-alpha.2 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Building a Code Review Bot
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Node.js `v22.13.0` or later installed
|
|
8
|
+
- An API key from a supported [Model Provider](https://mastra.ai/models)
|
|
9
|
+
- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
|
|
10
|
+
|
|
11
|
+
## Create the workspace
|
|
12
|
+
|
|
13
|
+
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`.
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { Mastra } from '@mastra/core';
|
|
17
|
+
import { resolve } from 'node:path';
|
|
18
|
+
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
|
|
19
|
+
|
|
20
|
+
const workspace = new Workspace({
|
|
21
|
+
filesystem: new LocalFilesystem({
|
|
22
|
+
basePath: resolve(import.meta.dirname, '../../workspace'),
|
|
23
|
+
}),
|
|
24
|
+
skills: ['/skills'],
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
export const mastra = new Mastra({
|
|
28
|
+
workspace,
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
## Create the code standards skill
|
|
35
|
+
|
|
36
|
+
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.
|
|
37
|
+
|
|
38
|
+
Inside `workspace/skills`, create a new folder called `code-standards`. Create a file called `SKILL.md` and add the review instructions.
|
|
39
|
+
|
|
40
|
+
```markdown
|
|
41
|
+
---
|
|
42
|
+
name: code-standards
|
|
43
|
+
description: Automated code review standards and checks
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
# Code Review Standards
|
|
47
|
+
|
|
48
|
+
Review code systematically using these steps:
|
|
49
|
+
|
|
50
|
+
1. **Critical Issues**: Security vulnerabilities, memory leaks, logic bugs, missing error handling
|
|
51
|
+
2. **Code Quality**: Functions over 50 lines, code duplication, confusing names, missing types
|
|
52
|
+
3. **Style Guide**: Check references/style-guide.md for naming and organization
|
|
53
|
+
4. **Linting**: Flag common issues like use of `var`, leftover `console.log` statements, and `debugger` statements
|
|
54
|
+
|
|
55
|
+
Provide feedback in this format:
|
|
56
|
+
|
|
57
|
+
**Summary**: One sentence overview
|
|
58
|
+
|
|
59
|
+
**Critical Issues**: List with line numbers
|
|
60
|
+
|
|
61
|
+
**Suggestions**: Improvements that would help
|
|
62
|
+
|
|
63
|
+
**Positive Notes**: What the code does well
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
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`.
|
|
67
|
+
|
|
68
|
+
````markdown
|
|
69
|
+
# Style Guide
|
|
70
|
+
|
|
71
|
+
## Naming
|
|
72
|
+
|
|
73
|
+
- Variables/Functions: `camelCase`
|
|
74
|
+
- Constants: `UPPER_SNAKE_CASE`
|
|
75
|
+
- Files: `kebab-case.ts`
|
|
76
|
+
- Booleans: Start with `is`, `has`, `should`
|
|
77
|
+
|
|
78
|
+
## Code Organization
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
// 1. Imports
|
|
82
|
+
import { foo } from 'bar';
|
|
83
|
+
|
|
84
|
+
// 2. Constants
|
|
85
|
+
const MAX_SIZE = 100;
|
|
86
|
+
|
|
87
|
+
// 3. Types
|
|
88
|
+
interface User { id: string; }
|
|
89
|
+
|
|
90
|
+
// 4. Functions
|
|
91
|
+
function doSomething() {}
|
|
92
|
+
|
|
93
|
+
// 5. Exports
|
|
94
|
+
export { doSomething };
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Error Handling
|
|
98
|
+
|
|
99
|
+
Always handle errors explicitly - never silently catch.
|
|
100
|
+
|
|
101
|
+
## Comments
|
|
102
|
+
|
|
103
|
+
Write "why" not "what".
|
|
104
|
+
````
|
|
105
|
+
|
|
106
|
+
## Create the review agent
|
|
107
|
+
|
|
108
|
+
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:
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
import { Agent } from '@mastra/core/agent';
|
|
112
|
+
|
|
113
|
+
export const codeReviewer = new Agent({
|
|
114
|
+
id: 'code-reviewer',
|
|
115
|
+
name: 'Code Review Bot',
|
|
116
|
+
instructions: `You are an automated code reviewer.
|
|
117
|
+
|
|
118
|
+
When asked to review code:
|
|
119
|
+
1. Activate the 'code-standards' skill
|
|
120
|
+
2. Follow the review process from the skill
|
|
121
|
+
3. Check against the style guide in skill references
|
|
122
|
+
4. Be constructive and specific with line numbers`,
|
|
123
|
+
model: 'openai/gpt-4o',
|
|
124
|
+
});
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
import { Mastra } from '@mastra/core';
|
|
131
|
+
import { resolve } from 'node:path';
|
|
132
|
+
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
|
|
133
|
+
import { codeReviewer } from './agents/code-reviewer';
|
|
134
|
+
|
|
135
|
+
const workspace = new Workspace({
|
|
136
|
+
filesystem: new LocalFilesystem({
|
|
137
|
+
basePath: resolve(import.meta.dirname, '../../workspace'),
|
|
138
|
+
}),
|
|
139
|
+
skills: ['/skills'],
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
export const mastra = new Mastra({
|
|
143
|
+
workspace,
|
|
144
|
+
agents: { codeReviewer },
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Test the bot
|
|
149
|
+
|
|
150
|
+
Start Mastra Studio and interact with the code review bot to see it in action.
|
|
151
|
+
|
|
152
|
+
**npm**:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
npm run dev
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**pnpm**:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
pnpm run dev
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**Yarn**:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
yarn dev
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**Bun**:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
bun run dev
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Open [localhost:4111](http://localhost:4111) and navigate to the code reviewer agent.
|
|
177
|
+
|
|
178
|
+
Inside the chat input, provide a code snippet for review, such as:
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
Review this code:
|
|
182
|
+
|
|
183
|
+
function getData(id) {
|
|
184
|
+
var result = fetch('/api/data/' + id);
|
|
185
|
+
console.log(result);
|
|
186
|
+
return result;
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
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:
|
|
191
|
+
|
|
192
|
+
```md
|
|
193
|
+
**Summary**: Function has several issues with variable declaration,
|
|
194
|
+
debugging statements, and missing error handling.
|
|
195
|
+
|
|
196
|
+
**Critical Issues**:
|
|
197
|
+
- Missing error handling for fetch (line 2)
|
|
198
|
+
- No async/await for asynchronous operation (line 2)
|
|
199
|
+
|
|
200
|
+
**Suggestions**:
|
|
201
|
+
- Use const instead of var (line 2)
|
|
202
|
+
- Remove console.log before committing (line 3)
|
|
203
|
+
- Add TypeScript type for id parameter
|
|
204
|
+
- Use template literals instead of concatenation
|
|
205
|
+
|
|
206
|
+
**Positive Notes**:
|
|
207
|
+
- Function name is clear and descriptive
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## Next steps
|
|
211
|
+
|
|
212
|
+
You can extend this bot to:
|
|
213
|
+
|
|
214
|
+
- Add skills for different languages or frameworks
|
|
215
|
+
- Create skills for security checks and performance reviews
|
|
216
|
+
- Integrate with GitHub Actions for automatic PR reviews
|
|
217
|
+
- Build a PR comment bot that leaves inline feedback
|
|
218
|
+
|
|
219
|
+
Learn more:
|
|
220
|
+
|
|
221
|
+
- [Agent Skills spec](https://agentskills.io)
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
# Building a Dev Assistant
|
|
2
|
+
|
|
3
|
+
In this guide, you'll build a complete development assistant that combines all workspace features:
|
|
4
|
+
|
|
5
|
+
- [Filesystem](https://mastra.ai/docs/workspace/filesystem) for file management
|
|
6
|
+
- [Sandbox](https://mastra.ai/docs/workspace/sandbox) for code execution
|
|
7
|
+
- [Skills](https://mastra.ai/docs/workspace/skills) for coding standards
|
|
8
|
+
- [Search](https://mastra.ai/docs/workspace/search) for finding examples
|
|
9
|
+
|
|
10
|
+
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.
|
|
11
|
+
|
|
12
|
+
## Prerequisites
|
|
13
|
+
|
|
14
|
+
- Node.js `v22.13.0` or later installed
|
|
15
|
+
- An API key from a supported [Model Provider](https://mastra.ai/models)
|
|
16
|
+
- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
|
|
17
|
+
|
|
18
|
+
### Install vitest
|
|
19
|
+
|
|
20
|
+
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:
|
|
21
|
+
|
|
22
|
+
**npm**:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install -D vitest
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**pnpm**:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pnpm add -D vitest
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**Yarn**:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
yarn add --dev vitest
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Bun**:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
bun add --dev vitest
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Set up the workspace
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
Additionally, enable BM25 search indexing and load skills from the `skills` directory.
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { Mastra } from '@mastra/core';
|
|
54
|
+
import { resolve } from 'node:path';
|
|
55
|
+
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
|
|
56
|
+
|
|
57
|
+
const workspace = new Workspace({
|
|
58
|
+
filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
|
|
59
|
+
sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
|
|
60
|
+
skills: ['/skills'],
|
|
61
|
+
bm25: true,
|
|
62
|
+
autoIndexPaths: ['/docs', '/src'],
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
export const mastra = new Mastra({
|
|
66
|
+
workspace,
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
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.
|
|
71
|
+
|
|
72
|
+
## Add sample project files
|
|
73
|
+
|
|
74
|
+
The workspace uses the following folder structure:
|
|
75
|
+
|
|
76
|
+
- `workspace/src/`: Source code for the sample project
|
|
77
|
+
- `workspace/tests/`: Test files
|
|
78
|
+
- `workspace/docs/`: Project documentation
|
|
79
|
+
- `workspace/skills/`: Coding standards and guidelines as [Agent Skills](https://agentskills.io)
|
|
80
|
+
|
|
81
|
+
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`.
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
export function capitalize(str: string): string {
|
|
85
|
+
if (!str) return str;
|
|
86
|
+
return str.charAt(0).toUpperCase() + str.slice(1);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export function slugify(str: string): string {
|
|
90
|
+
return str
|
|
91
|
+
.toLowerCase()
|
|
92
|
+
.replace(/[^\w\s-]/g, '')
|
|
93
|
+
.replace(/\s+/g, '-');
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
import { describe, it, expect } from 'vitest';
|
|
99
|
+
import { capitalize, slugify } from '../src/utils/string-helpers';
|
|
100
|
+
|
|
101
|
+
describe('String Helpers', () => {
|
|
102
|
+
describe('capitalize', () => {
|
|
103
|
+
it('capitalizes first letter', () => {
|
|
104
|
+
expect(capitalize('hello')).toBe('Hello');
|
|
105
|
+
});
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
describe('slugify', () => {
|
|
109
|
+
it('converts to lowercase and replaces spaces', () => {
|
|
110
|
+
expect(slugify('Hello World')).toBe('hello-world');
|
|
111
|
+
});
|
|
112
|
+
});
|
|
113
|
+
});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Create a skill definition at `workspace/skills/coding-standards/SKILL.md`. This tells the agent how to write and test code:
|
|
117
|
+
|
|
118
|
+
```markdown
|
|
119
|
+
---
|
|
120
|
+
name: coding-standards
|
|
121
|
+
description: Project coding standards and testing guidelines
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
# Coding Standards
|
|
125
|
+
|
|
126
|
+
## Code Quality
|
|
127
|
+
- Functions under 50 lines
|
|
128
|
+
- Use descriptive variable names
|
|
129
|
+
- Always add TypeScript types
|
|
130
|
+
|
|
131
|
+
## Testing
|
|
132
|
+
- Test all exported functions
|
|
133
|
+
- Use AAA pattern: Arrange, Act, Assert
|
|
134
|
+
- Cover happy paths and edge cases
|
|
135
|
+
|
|
136
|
+
## Before Committing
|
|
137
|
+
1. Write implementation
|
|
138
|
+
2. Write comprehensive tests
|
|
139
|
+
3. Run tests: `npm test`
|
|
140
|
+
4. All tests must pass
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Create a reference file at `workspace/skills/coding-standards/references/testing-guide.md` with detailed testing patterns:
|
|
144
|
+
|
|
145
|
+
````markdown
|
|
146
|
+
# Testing Guide
|
|
147
|
+
|
|
148
|
+
## AAA Pattern
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
it('descriptive test name', () => {
|
|
152
|
+
// Arrange: Set up test data
|
|
153
|
+
const input = 'test';
|
|
154
|
+
|
|
155
|
+
// Act: Execute the function
|
|
156
|
+
const result = doSomething(input);
|
|
157
|
+
|
|
158
|
+
// Assert: Verify the result
|
|
159
|
+
expect(result).toBe('expected');
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## What to Test
|
|
164
|
+
|
|
165
|
+
- Happy paths (normal inputs)
|
|
166
|
+
- Edge cases (empty, null, boundary values)
|
|
167
|
+
- Error cases (invalid inputs, exceptions)
|
|
168
|
+
````
|
|
169
|
+
|
|
170
|
+
## Create the dev assistant
|
|
171
|
+
|
|
172
|
+
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).
|
|
173
|
+
|
|
174
|
+
Create a new file `src/mastra/agents/dev-assistant.ts` and define the agent:
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
import { Agent } from '@mastra/core/agent';
|
|
178
|
+
|
|
179
|
+
export const devAssistant = new Agent({
|
|
180
|
+
id: 'dev-assistant',
|
|
181
|
+
name: 'Dev Assistant',
|
|
182
|
+
instructions: `You are a development assistant.
|
|
183
|
+
|
|
184
|
+
When adding features:
|
|
185
|
+
1. Activate 'coding-standards' skill
|
|
186
|
+
2. Search workspace for similar code examples
|
|
187
|
+
3. Write the implementation following standards
|
|
188
|
+
4. Write comprehensive tests. Leave existing tests in place, only add your new tests
|
|
189
|
+
5. Execute the command \`npx vitest run\` to validate that all tests pass
|
|
190
|
+
6. Update documentation if needed
|
|
191
|
+
|
|
192
|
+
For every new feature: Write code → Write tests → Run tests → Update docs
|
|
193
|
+
|
|
194
|
+
Always explain your reasoning and steps.`,
|
|
195
|
+
model: 'openai/gpt-4o',
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
import { Mastra } from '@mastra/core';
|
|
203
|
+
import { resolve } from 'node:path';
|
|
204
|
+
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
|
|
205
|
+
import { devAssistant } from './agents/dev-assistant';
|
|
206
|
+
|
|
207
|
+
const workspace = new Workspace({
|
|
208
|
+
filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
|
|
209
|
+
sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
|
|
210
|
+
skills: ['/skills'],
|
|
211
|
+
bm25: true,
|
|
212
|
+
autoIndexPaths: ['/docs', '/src'],
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
export const mastra = new Mastra({
|
|
216
|
+
workspace,
|
|
217
|
+
agents: { devAssistant },
|
|
218
|
+
});
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Test the assistant
|
|
222
|
+
|
|
223
|
+
Start Mastra Studio and interact with the agent to see it in action.
|
|
224
|
+
|
|
225
|
+
**npm**:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
npm run dev
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
**pnpm**:
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
pnpm run dev
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
**Yarn**:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
yarn dev
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
**Bun**:
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
bun run dev
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Open [localhost:4111](http://localhost:4111) and navigate to the dev assistant.
|
|
250
|
+
|
|
251
|
+
Try asking the agent to add a new function using TDD:
|
|
252
|
+
|
|
253
|
+
```text
|
|
254
|
+
Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.
|
|
255
|
+
|
|
256
|
+
Follow TDD: write tests first, then implementation.
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Since agent responses are non-deterministic, the exact output will vary. However, you should see the agent follow a process similar to this:
|
|
260
|
+
|
|
261
|
+
1. Activate the coding-standards skill
|
|
262
|
+
|
|
263
|
+
2. Search the workspace for similar code patterns
|
|
264
|
+
|
|
265
|
+
3. Write tests first, for example:
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
describe('truncate', () => {
|
|
269
|
+
it('truncates long strings', () => {
|
|
270
|
+
expect(truncate('Hello World', 5)).toBe('He...');
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
it('keeps short strings unchanged', () => {
|
|
274
|
+
expect(truncate('Hi', 10)).toBe('Hi');
|
|
275
|
+
});
|
|
276
|
+
|
|
277
|
+
it('handles edge cases', () => {
|
|
278
|
+
expect(truncate('', 5)).toBe('');
|
|
279
|
+
});
|
|
280
|
+
});
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
4. Write the implementation, for example:
|
|
284
|
+
|
|
285
|
+
```typescript
|
|
286
|
+
export function truncate(str: string, maxLength: number): string {
|
|
287
|
+
if (!str || maxLength < 0) return str;
|
|
288
|
+
if (str.length <= maxLength) return str;
|
|
289
|
+
if (maxLength === 0) return '...';
|
|
290
|
+
return str.slice(0, maxLength - 3) + '...';
|
|
291
|
+
}
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
5. Run tests and verify they pass
|
|
295
|
+
|
|
296
|
+
## Next steps
|
|
297
|
+
|
|
298
|
+
You can extend this assistant to:
|
|
299
|
+
|
|
300
|
+
- Add more skills for different languages or frameworks
|
|
301
|
+
- Create specialized agents for backend, frontend, or DevOps
|
|
302
|
+
- Integrate with GitHub for automated PR reviews
|
|
303
|
+
- Build CI/CD automation
|
|
304
|
+
- Add multi-agent workflows
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Building a Docs Manager
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Node.js `v22.13.0` or later installed
|
|
8
|
+
- An API key from a supported [Model Provider](https://mastra.ai/models)
|
|
9
|
+
- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
|
|
10
|
+
|
|
11
|
+
## Set up the workspace
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { Mastra } from '@mastra/core';
|
|
17
|
+
import { resolve } from 'node:path';
|
|
18
|
+
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
|
|
19
|
+
|
|
20
|
+
const workspace = new Workspace({
|
|
21
|
+
filesystem: new LocalFilesystem({
|
|
22
|
+
basePath: resolve(import.meta.dirname, '../../workspace'),
|
|
23
|
+
}),
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
export const mastra = new Mastra({
|
|
27
|
+
workspace,
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
## Add example documentation
|
|
34
|
+
|
|
35
|
+
Inside the `workspace` directory, create the following folders:
|
|
36
|
+
|
|
37
|
+
- `docs/guides/`: For how-to guides
|
|
38
|
+
- `docs/api/`: For API reference documentation
|
|
39
|
+
- `docs/tutorials/`: For step-by-step tutorials
|
|
40
|
+
|
|
41
|
+
Create a `workspace/docs/README.md` file that serves as the documentation index:
|
|
42
|
+
|
|
43
|
+
```markdown
|
|
44
|
+
# Project Documentation
|
|
45
|
+
|
|
46
|
+
Welcome to the documentation!
|
|
47
|
+
|
|
48
|
+
## Sections
|
|
49
|
+
|
|
50
|
+
- [Guides](./guides/): How-to guides
|
|
51
|
+
- [API](./api/): API reference
|
|
52
|
+
- [Tutorials](./tutorials/): Step-by-step tutorials
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Add a sample guide so the agent can see the existing documentation style:
|
|
56
|
+
|
|
57
|
+
````markdown
|
|
58
|
+
# Getting Started
|
|
59
|
+
|
|
60
|
+
Quick start guide for the project.
|
|
61
|
+
|
|
62
|
+
## Installation
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npm install example-package
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Quick Example
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
import { Example } from 'example-package';
|
|
72
|
+
|
|
73
|
+
const example = new Example();
|
|
74
|
+
example.run();
|
|
75
|
+
```
|
|
76
|
+
````
|
|
77
|
+
|
|
78
|
+
## Create the docs manager
|
|
79
|
+
|
|
80
|
+
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:
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { Agent } from '@mastra/core/agent';
|
|
84
|
+
|
|
85
|
+
export const docsManager = new Agent({
|
|
86
|
+
id: 'docs-manager',
|
|
87
|
+
name: 'Docs Manager',
|
|
88
|
+
instructions: `You are a documentation manager that creates and maintains markdown docs.
|
|
89
|
+
|
|
90
|
+
When creating new docs:
|
|
91
|
+
1. Ask for topic and target audience
|
|
92
|
+
2. Create well-structured markdown with clear sections
|
|
93
|
+
3. Include relevant code examples with syntax highlighting
|
|
94
|
+
4. Save in the appropriate directory:
|
|
95
|
+
- /docs/guides/ for user guides and how-tos
|
|
96
|
+
- /docs/api/ for API reference
|
|
97
|
+
- /docs/tutorials/ for step-by-step tutorials
|
|
98
|
+
|
|
99
|
+
When updating existing docs:
|
|
100
|
+
1. ALWAYS read the file first
|
|
101
|
+
2. Make targeted updates without removing unrelated content
|
|
102
|
+
3. Preserve existing structure and formatting
|
|
103
|
+
|
|
104
|
+
Use kebab-case naming for files (getting-started.md).
|
|
105
|
+
Always explain what you're creating and why.`,
|
|
106
|
+
model: 'openai/gpt-4o',
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
import { Mastra } from '@mastra/core';
|
|
114
|
+
import { resolve } from 'node:path';
|
|
115
|
+
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
|
|
116
|
+
import { docsManager } from './agents/docs-manager';
|
|
117
|
+
|
|
118
|
+
const workspace = new Workspace({
|
|
119
|
+
filesystem: new LocalFilesystem({
|
|
120
|
+
basePath: resolve(import.meta.dirname, '../../workspace'),
|
|
121
|
+
}),
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
export const mastra = new Mastra({
|
|
125
|
+
workspace,
|
|
126
|
+
agents: { docsManager },
|
|
127
|
+
});
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Test the docs manager
|
|
131
|
+
|
|
132
|
+
Start Mastra Studio and interact with the agent to see it in action.
|
|
133
|
+
|
|
134
|
+
**npm**:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
npm run dev
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**pnpm**:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pnpm run dev
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
**Yarn**:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
yarn dev
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**Bun**:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
bun run dev
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Open [localhost:4111](http://localhost:4111) and navigate to the docs manager.
|
|
159
|
+
|
|
160
|
+
### Create a new document
|
|
161
|
+
|
|
162
|
+
Ask the agent to create a tutorial:
|
|
163
|
+
|
|
164
|
+
```text
|
|
165
|
+
Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
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:
|
|
169
|
+
|
|
170
|
+
````md
|
|
171
|
+
# Authentication Setup
|
|
172
|
+
|
|
173
|
+
Learn how to add authentication to your application.
|
|
174
|
+
|
|
175
|
+
## Installation
|
|
176
|
+
|
|
177
|
+
Install the auth package:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
npm install @example/auth
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Configuration
|
|
184
|
+
|
|
185
|
+
Create a config file:
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
// auth.config.ts
|
|
189
|
+
export const authConfig = {
|
|
190
|
+
provider: 'oauth',
|
|
191
|
+
clientId: process.env.AUTH_CLIENT_ID,
|
|
192
|
+
secret: process.env.AUTH_SECRET,
|
|
193
|
+
};
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Basic Example
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
import { createAuth } from '@example/auth';
|
|
200
|
+
import { authConfig } from './auth.config';
|
|
201
|
+
|
|
202
|
+
const auth = createAuth(authConfig);
|
|
203
|
+
|
|
204
|
+
app.get('/protected', auth.requireAuth(), (req, res) => {
|
|
205
|
+
res.json({ user: req.user });
|
|
206
|
+
});
|
|
207
|
+
```
|
|
208
|
+
````
|
|
209
|
+
|
|
210
|
+
### Update an existing document
|
|
211
|
+
|
|
212
|
+
Try updating an existing document:
|
|
213
|
+
|
|
214
|
+
```text
|
|
215
|
+
Update the getting started guide to include a section on configuration after the Quick Example
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The agent should read the existing `getting-started.md` file, find the right insertion point, and add the new section without disrupting existing content.
|
|
219
|
+
|
|
220
|
+
### Organize documentation
|
|
221
|
+
|
|
222
|
+
Ask the agent to create an index:
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
List all tutorial files and create an index page that links to all of them
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
The agent should create a file like `/docs/tutorials/index.md` that links to all available tutorials.
|
|
229
|
+
|
|
230
|
+
## Next steps
|
|
231
|
+
|
|
232
|
+
You can extend this manager to:
|
|
233
|
+
|
|
234
|
+
- Add BM25 or vector search to find relevant documentation
|
|
235
|
+
- Create skills for documentation templates
|
|
236
|
+
- Build automated doc generation from source code
|
|
237
|
+
- Integrate with GitHub to update docs on commits
|
|
238
|
+
- Add validation to check links and formatting
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`717ffab`](https://github.com/mastra-ai/mastra/commit/717ffab42cfd58ff723b5c19ada4939997773004), [`b31c922`](https://github.com/mastra-ai/mastra/commit/b31c922215b513791d98feaea1b98784aa00803a), [`e4b6dab`](https://github.com/mastra-ai/mastra/commit/e4b6dab171c5960e340b3ea3ea6da8d64d2b8672), [`5719fa8`](https://github.com/mastra-ai/mastra/commit/5719fa8880e86e8affe698ec4b3807c7e0e0a06f), [`83cda45`](https://github.com/mastra-ai/mastra/commit/83cda4523e588558466892bff8f80f631a36945a), [`11804ad`](https://github.com/mastra-ai/mastra/commit/11804adf1d6be46ebe216be40a43b39bb8b397d7), [`aa95f95`](https://github.com/mastra-ai/mastra/commit/aa95f958b186ae5c9f4219c88e268f5565c277a2), [`90f7894`](https://github.com/mastra-ai/mastra/commit/90f7894568dc9481f40a4d29672234fae23090bb), [`f5501ae`](https://github.com/mastra-ai/mastra/commit/f5501aedb0a11106c7db7e480d6eaf3971b7bda8), [`44573af`](https://github.com/mastra-ai/mastra/commit/44573afad0a4bc86f627d6cbc0207961cdcb3bc3), [`00e3861`](https://github.com/mastra-ai/mastra/commit/00e3861863fbfee78faeb1ebbdc7c0223aae13ff), [`8109aee`](https://github.com/mastra-ai/mastra/commit/8109aeeab758e16cd4255a6c36f044b70eefc6a6), [`7bfbc52`](https://github.com/mastra-ai/mastra/commit/7bfbc52a8604feb0fff2c0a082c13c0c2a3df1a2), [`1445994`](https://github.com/mastra-ai/mastra/commit/1445994aee19c9334a6a101cf7bd80ca7ed4d186), [`61f44a2`](https://github.com/mastra-ai/mastra/commit/61f44a26861c89e364f367ff40825bdb7f19df55), [`37145d2`](https://github.com/mastra-ai/mastra/commit/37145d25f99dc31f1a9105576e5452609843ce32), [`fdad759`](https://github.com/mastra-ai/mastra/commit/fdad75939ff008b27625f5ec0ce9c6915d99d9ec), [`e4569c5`](https://github.com/mastra-ai/mastra/commit/e4569c589e00c4061a686c9eb85afe1b7050b0a8), [`7309a85`](https://github.com/mastra-ai/mastra/commit/7309a85427281a8be23f4fb80ca52e18eaffd596), [`99424f6`](https://github.com/mastra-ai/mastra/commit/99424f6862ffb679c4ec6765501486034754a4c2), [`44eb452`](https://github.com/mastra-ai/mastra/commit/44eb4529b10603c279688318bebf3048543a1d61), [`6c40593`](https://github.com/mastra-ai/mastra/commit/6c40593d6d2b1b68b0c45d1a3a4c6ac5ecac3937), [`8c1135d`](https://github.com/mastra-ai/mastra/commit/8c1135dfb91b057283eae7ee11f9ec28753cc64f), [`dd39e54`](https://github.com/mastra-ai/mastra/commit/dd39e54ea34532c995b33bee6e0e808bf41a7341), [`b6fad9a`](https://github.com/mastra-ai/mastra/commit/b6fad9a602182b1cc0df47cd8c55004fa829ad61), [`2d2decc`](https://github.com/mastra-ai/mastra/commit/2d2decc9c62743b23a064cd599871639a61867a0), [`4129c07`](https://github.com/mastra-ai/mastra/commit/4129c073349b5a66643fd8136ebfe9d7097cf793), [`5b930ab`](https://github.com/mastra-ai/mastra/commit/5b930aba1834d9898e8460a49d15106f31ac7c8d), [`4be93d0`](https://github.com/mastra-ai/mastra/commit/4be93d09d68e20aaf0ea3f210749422719618b5f), [`047635c`](https://github.com/mastra-ai/mastra/commit/047635ccd7861d726c62d135560c0022a5490aec), [`8c90ff4`](https://github.com/mastra-ai/mastra/commit/8c90ff4d3414e7f2a2d216ea91274644f7b29133), [`ed232d1`](https://github.com/mastra-ai/mastra/commit/ed232d1583f403925dc5ae45f7bee948cf2a182b), [`3891795`](https://github.com/mastra-ai/mastra/commit/38917953518eb4154a984ee36e6ededdcfe80f72), [`4f955b2`](https://github.com/mastra-ai/mastra/commit/4f955b20c7f66ed282ee1fd8709696fa64c4f19d), [`55a4c90`](https://github.com/mastra-ai/mastra/commit/55a4c9044ac7454349b9f6aeba0bbab5ee65d10f)]:
|
|
8
|
+
- @mastra/core@1.3.0
|
|
9
|
+
- @mastra/mcp@1.0.1
|
|
10
|
+
|
|
3
11
|
## 1.1.1-alpha.2
|
|
4
12
|
|
|
5
13
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.1.1
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -29,8 +29,8 @@
|
|
|
29
29
|
"jsdom": "^26.1.0",
|
|
30
30
|
"local-pkg": "^1.1.2",
|
|
31
31
|
"zod": "^3.25.76",
|
|
32
|
-
"@mastra/core": "1.3.0
|
|
33
|
-
"@mastra/mcp": "^1.0.1
|
|
32
|
+
"@mastra/core": "1.3.0",
|
|
33
|
+
"@mastra/mcp": "^1.0.1"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"@hono/node-server": "^1.19.9",
|
|
@@ -46,9 +46,9 @@
|
|
|
46
46
|
"tsx": "^4.21.0",
|
|
47
47
|
"typescript": "^5.9.3",
|
|
48
48
|
"vitest": "4.0.16",
|
|
49
|
-
"@internal/
|
|
50
|
-
"@
|
|
51
|
-
"@
|
|
49
|
+
"@internal/lint": "0.0.58",
|
|
50
|
+
"@internal/types-builder": "0.0.33",
|
|
51
|
+
"@mastra/core": "1.3.0"
|
|
52
52
|
},
|
|
53
53
|
"homepage": "https://mastra.ai",
|
|
54
54
|
"repository": {
|