@mastra/mcp-docs-server 1.1.1-alpha.1 → 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.
- package/.docs/docs/memory/observational-memory.md +9 -78
- package/.docs/guides/guide/code-review-bot.md +221 -0
- package/.docs/guides/guide/dev-assistant.md +304 -0
- package/.docs/guides/guide/docs-manager.md +238 -0
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/cortecs.md +6 -1
- package/.docs/models/providers/firmware.md +6 -2
- package/.docs/models/providers/openai.md +13 -13
- package/.docs/models/providers/opencode.md +9 -9
- package/.docs/reference/memory/observational-memory.md +7 -316
- package/CHANGELOG.md +15 -0
- package/package.json +6 -6
|
@@ -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/.docs/models/index.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Model Providers
|
|
2
2
|
|
|
3
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
3
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 2173 models from 78 providers through a single API.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Cortecs
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 21 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Cortecs documentation](https://cortecs.ai).
|
|
6
6
|
|
|
@@ -40,12 +40,17 @@ for await (const chunk of stream) {
|
|
|
40
40
|
| `cortecs/devstral-2512` | 262K | | | | | | — | — |
|
|
41
41
|
| `cortecs/devstral-small-2512` | 262K | | | | | | — | — |
|
|
42
42
|
| `cortecs/gemini-2.5-pro` | 1.0M | | | | | | $2 | $11 |
|
|
43
|
+
| `cortecs/glm-4p5` | 131K | | | | | | $0.67 | $2 |
|
|
44
|
+
| `cortecs/glm-4p5-air` | 131K | | | | | | $0.22 | $1 |
|
|
45
|
+
| `cortecs/glm-4p7` | 198K | | | | | | $0.45 | $2 |
|
|
43
46
|
| `cortecs/gpt-4.1` | 1.0M | | | | | | $2 | $9 |
|
|
44
47
|
| `cortecs/gpt-oss-120b` | 128K | | | | | | — | — |
|
|
45
48
|
| `cortecs/intellect-3` | 128K | | | | | | $0.22 | $1 |
|
|
46
49
|
| `cortecs/kimi-k2-instruct` | 131K | | | | | | $0.55 | $3 |
|
|
47
50
|
| `cortecs/kimi-k2-thinking` | 262K | | | | | | $0.66 | $3 |
|
|
48
51
|
| `cortecs/llama-3.1-405b-instruct` | 128K | | | | | | — | — |
|
|
52
|
+
| `cortecs/minimax-m2` | 400K | | | | | | $0.39 | $2 |
|
|
53
|
+
| `cortecs/minimax-m2p1` | 196K | | | | | | $0.34 | $1 |
|
|
49
54
|
| `cortecs/nova-pro-v1` | 300K | | | | | | $1 | $4 |
|
|
50
55
|
| `cortecs/qwen3-32b` | 16K | | | | | | $0.10 | $0.33 |
|
|
51
56
|
| `cortecs/qwen3-coder-480b-a35b-instruct` | 262K | | | | | | $0.44 | $2 |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Firmware
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 20 Firmware models through Mastra's model router. Authentication is handled automatically using the `FIRMWARE_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Firmware documentation](https://docs.firmware.ai).
|
|
6
6
|
|
|
@@ -50,6 +50,10 @@ for await (const chunk of stream) {
|
|
|
50
50
|
| `firmware/gpt-5.2` | 400K | | | | | | $2 | $14 |
|
|
51
51
|
| `firmware/gpt-oss-120b` | 131K | | | | | | $0.15 | $0.60 |
|
|
52
52
|
| `firmware/gpt-oss-20b` | 131K | | | | | | $0.07 | $0.20 |
|
|
53
|
+
| `firmware/kimi-k2-thinking` | 262K | | | | | | $0.60 | $3 |
|
|
54
|
+
| `firmware/kimi-k2.5` | 256K | | | | | | $0.60 | $3 |
|
|
55
|
+
| `firmware/zai-glm-4.7` | 131K | | | | | | $0.60 | $2 |
|
|
56
|
+
| `firmware/zai-glm-4.7-flash` | 131K | | | | | | $0.07 | $0.40 |
|
|
53
57
|
|
|
54
58
|
## Advanced Configuration
|
|
55
59
|
|
|
@@ -79,7 +83,7 @@ const agent = new Agent({
|
|
|
79
83
|
model: ({ requestContext }) => {
|
|
80
84
|
const useAdvanced = requestContext.task === "complex";
|
|
81
85
|
return useAdvanced
|
|
82
|
-
? "firmware/
|
|
86
|
+
? "firmware/zai-glm-4.7-flash"
|
|
83
87
|
: "firmware/claude-haiku-4-5";
|
|
84
88
|
}
|
|
85
89
|
});
|
|
@@ -44,22 +44,22 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `openai/gpt-4o-2024-08-06` | 128K | | | | | | $3 | $10 |
|
|
45
45
|
| `openai/gpt-4o-2024-11-20` | 128K | | | | | | $3 | $10 |
|
|
46
46
|
| `openai/gpt-4o-mini` | 128K | | | | | | $0.15 | $0.60 |
|
|
47
|
-
| `openai/gpt-5` |
|
|
48
|
-
| `openai/gpt-5-chat-latest` |
|
|
49
|
-
| `openai/gpt-5-codex` |
|
|
50
|
-
| `openai/gpt-5-mini` |
|
|
51
|
-
| `openai/gpt-5-nano` |
|
|
47
|
+
| `openai/gpt-5` | 272K | | | | | | $1 | $10 |
|
|
48
|
+
| `openai/gpt-5-chat-latest` | 272K | | | | | | $1 | $10 |
|
|
49
|
+
| `openai/gpt-5-codex` | 272K | | | | | | $1 | $10 |
|
|
50
|
+
| `openai/gpt-5-mini` | 272K | | | | | | $0.25 | $2 |
|
|
51
|
+
| `openai/gpt-5-nano` | 272K | | | | | | $0.05 | $0.40 |
|
|
52
52
|
| `openai/gpt-5-pro` | 400K | | | | | | $15 | $120 |
|
|
53
|
-
| `openai/gpt-5.1` |
|
|
53
|
+
| `openai/gpt-5.1` | 272K | | | | | | $1 | $10 |
|
|
54
54
|
| `openai/gpt-5.1-chat-latest` | 128K | | | | | | $1 | $10 |
|
|
55
|
-
| `openai/gpt-5.1-codex` |
|
|
56
|
-
| `openai/gpt-5.1-codex-max` |
|
|
57
|
-
| `openai/gpt-5.1-codex-mini` |
|
|
58
|
-
| `openai/gpt-5.2` |
|
|
55
|
+
| `openai/gpt-5.1-codex` | 272K | | | | | | $1 | $10 |
|
|
56
|
+
| `openai/gpt-5.1-codex-max` | 272K | | | | | | $1 | $10 |
|
|
57
|
+
| `openai/gpt-5.1-codex-mini` | 272K | | | | | | $0.25 | $2 |
|
|
58
|
+
| `openai/gpt-5.2` | 272K | | | | | | $2 | $14 |
|
|
59
59
|
| `openai/gpt-5.2-chat-latest` | 128K | | | | | | $2 | $14 |
|
|
60
|
-
| `openai/gpt-5.2-codex` |
|
|
61
|
-
| `openai/gpt-5.2-pro` |
|
|
62
|
-
| `openai/gpt-5.3-codex` |
|
|
60
|
+
| `openai/gpt-5.2-codex` | 272K | | | | | | $2 | $14 |
|
|
61
|
+
| `openai/gpt-5.2-pro` | 272K | | | | | | $21 | $168 |
|
|
62
|
+
| `openai/gpt-5.3-codex` | 272K | | | | | | $2 | $14 |
|
|
63
63
|
| `openai/o1` | 200K | | | | | | $15 | $60 |
|
|
64
64
|
| `openai/o1-mini` | 128K | | | | | | $1 | $4 |
|
|
65
65
|
| `openai/o1-preview` | 128K | | | | | | $15 | $60 |
|
|
@@ -46,15 +46,15 @@ for await (const chunk of stream) {
|
|
|
46
46
|
| `opencode/gemini-3-pro` | 1.0M | | | | | | $2 | $12 |
|
|
47
47
|
| `opencode/glm-4.6` | 205K | | | | | | $0.60 | $2 |
|
|
48
48
|
| `opencode/glm-4.7` | 205K | | | | | | $0.60 | $2 |
|
|
49
|
-
| `opencode/gpt-5` |
|
|
50
|
-
| `opencode/gpt-5-codex` |
|
|
51
|
-
| `opencode/gpt-5-nano` |
|
|
52
|
-
| `opencode/gpt-5.1` |
|
|
53
|
-
| `opencode/gpt-5.1-codex` |
|
|
54
|
-
| `opencode/gpt-5.1-codex-max` |
|
|
55
|
-
| `opencode/gpt-5.1-codex-mini` |
|
|
56
|
-
| `opencode/gpt-5.2` |
|
|
57
|
-
| `opencode/gpt-5.2-codex` |
|
|
49
|
+
| `opencode/gpt-5` | 272K | | | | | | $1 | $9 |
|
|
50
|
+
| `opencode/gpt-5-codex` | 272K | | | | | | $1 | $9 |
|
|
51
|
+
| `opencode/gpt-5-nano` | 272K | | | | | | — | — |
|
|
52
|
+
| `opencode/gpt-5.1` | 272K | | | | | | $1 | $9 |
|
|
53
|
+
| `opencode/gpt-5.1-codex` | 272K | | | | | | $1 | $9 |
|
|
54
|
+
| `opencode/gpt-5.1-codex-max` | 272K | | | | | | $1 | $10 |
|
|
55
|
+
| `opencode/gpt-5.1-codex-mini` | 272K | | | | | | $0.25 | $2 |
|
|
56
|
+
| `opencode/gpt-5.2` | 272K | | | | | | $2 | $14 |
|
|
57
|
+
| `opencode/gpt-5.2-codex` | 272K | | | | | | $2 | $14 |
|
|
58
58
|
| `opencode/kimi-k2` | 262K | | | | | | $0.40 | $3 |
|
|
59
59
|
| `opencode/kimi-k2-thinking` | 262K | | | | | | $0.40 | $3 |
|
|
60
60
|
| `opencode/kimi-k2.5` | 262K | | | | | | $0.60 | $3 |
|