@mastra/mcp-docs-server 1.2.3-alpha.12 → 1.2.3-alpha.15
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/agents/file-based-agents.md +286 -0
- package/.docs/docs/getting-started/project-structure.md +18 -14
- package/.docs/reference/coding-agent/build-base-prompt.md +75 -0
- package/.docs/reference/coding-agent/create-coding-agent.md +97 -0
- package/.docs/reference/index.md +2 -0
- package/CHANGELOG.md +14 -0
- package/package.json +4 -4
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
# File-based agents
|
|
2
|
+
|
|
3
|
+
**Added in:** `@mastra/core@1.48.0`
|
|
4
|
+
|
|
5
|
+
> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
|
|
6
|
+
|
|
7
|
+
You can define an agent by file convention instead of constructing it in code. Mastra discovers a directory under `src/mastra/agents/<name>/`, assembles an [`Agent`](https://mastra.ai/reference/agents/agent), and registers it on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
|
|
8
|
+
|
|
9
|
+
## When to use file-based agents
|
|
10
|
+
|
|
11
|
+
Use file-based agents when you want one directory per agent, with configuration, instructions, tools, skills, workspace files, and subagents grouped together.
|
|
12
|
+
|
|
13
|
+
Keep using [`new Agent()`](https://mastra.ai/reference/agents/agent) in code when you need dynamic configuration, programmatic registration, or a shared agent instance across modules. Both approaches can coexist: code-registered agents are always present, and the bundler adds file-based agents when you run through the Mastra CLI.
|
|
14
|
+
|
|
15
|
+
## Quickstart
|
|
16
|
+
|
|
17
|
+
Create a directory for the agent and add a `config.ts`. Use `agentConfig` so the partial config is typed while sibling files supply the rest.
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { agentConfig } from '@mastra/core/agent'
|
|
21
|
+
|
|
22
|
+
export default agentConfig({
|
|
23
|
+
model: 'openai/gpt-5.5',
|
|
24
|
+
// instructions omitted -> taken from instructions.md
|
|
25
|
+
// tools omitted -> taken from tools/*.ts
|
|
26
|
+
})
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Add the agent instructions:
|
|
30
|
+
|
|
31
|
+
```markdown
|
|
32
|
+
You are a helpful weather assistant. Answer questions about current conditions and forecasts.
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Add a tool. The filename becomes the tool key, so this file is exposed as `get_weather`.
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { createTool } from '@mastra/core/tools'
|
|
39
|
+
import { z } from 'zod'
|
|
40
|
+
|
|
41
|
+
export default createTool({
|
|
42
|
+
id: 'get_weather',
|
|
43
|
+
description: 'Get the current weather for a city',
|
|
44
|
+
inputSchema: z.object({ city: z.string() }),
|
|
45
|
+
execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
|
|
46
|
+
})
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Your `src/mastra/index.ts` stays the same. The discovered agent is registered automatically when you run the app through `mastra dev` or `mastra build`.
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { Mastra } from '@mastra/core'
|
|
53
|
+
import { Agent } from '@mastra/core/agent'
|
|
54
|
+
|
|
55
|
+
const supportAgent = new Agent({
|
|
56
|
+
id: 'support',
|
|
57
|
+
name: 'support',
|
|
58
|
+
instructions: 'You are a support agent.',
|
|
59
|
+
model: 'openai/gpt-5.5',
|
|
60
|
+
})
|
|
61
|
+
|
|
62
|
+
// `support` is registered in code; `weather` is discovered from the filesystem.
|
|
63
|
+
export const mastra = new Mastra({
|
|
64
|
+
agents: { support: supportAgent },
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Start the app through the Mastra CLI:
|
|
69
|
+
|
|
70
|
+
**npm**:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx mastra dev
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**pnpm**:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pnpm dlx mastra dev
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Yarn**:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
yarn dlx mastra dev
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Bun**:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
bun x mastra dev
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Folder structure
|
|
95
|
+
|
|
96
|
+
The following table shows the supported file-based agent surface:
|
|
97
|
+
|
|
98
|
+
| File / directory | Maps to |
|
|
99
|
+
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
100
|
+
| `agents/<name>/config.ts` | Default export merged into the agent config. `id` and `name` default to `<name>`. |
|
|
101
|
+
| `agents/<name>/instructions.md` | The agent `instructions`. The file contents are inlined into generated code. |
|
|
102
|
+
| `agents/<name>/tools/*.ts` | Each default-exported [`createTool()`](https://mastra.ai/reference/tools/create-tool). The tool key defaults to the filename. |
|
|
103
|
+
| `agents/<name>/skills/*.ts` | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`. |
|
|
104
|
+
| `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
|
|
105
|
+
| `agents/<name>/skills/<skill>.md` | A flat skill. The filename is the skill name and the body is the instructions. |
|
|
106
|
+
| `agents/<name>/memory.ts` | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`. |
|
|
107
|
+
| `agents/<name>/workspace.ts` | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent. |
|
|
108
|
+
| `agents/<name>/workspace/` | Seed files mirrored into the agent's default workspace at build time. |
|
|
109
|
+
| `agents/<name>/subagents/<childId>/` | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`. |
|
|
110
|
+
|
|
111
|
+
Test files named `*.test.ts`, `*.spec.ts`, `*.test.js`, and `*.spec.js` are ignored during tool and skill discovery.
|
|
112
|
+
|
|
113
|
+
## Add skills
|
|
114
|
+
|
|
115
|
+
Add skills to a file-based agent by placing them under `agents/<name>/skills/`. Three layouts are supported, and they're inlined into the bundle at build time so the deployed agent doesn't read them from disk at runtime.
|
|
116
|
+
|
|
117
|
+
- A `.ts` file can default-export `createSkill()`:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
import { createSkill } from '@mastra/core/skills'
|
|
121
|
+
|
|
122
|
+
export default createSkill({
|
|
123
|
+
name: 'forecasting',
|
|
124
|
+
description: 'Use when the user asks about multi-day forecasts.',
|
|
125
|
+
instructions: 'Summarize the forecast day by day and call out precipitation.',
|
|
126
|
+
})
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
|
|
130
|
+
|
|
131
|
+
- A packaged `SKILL.md` directory uses frontmatter for the name and description. Files under `references/` are inlined with the skill.
|
|
132
|
+
|
|
133
|
+
```markdown
|
|
134
|
+
---
|
|
135
|
+
name: severe-weather
|
|
136
|
+
description: Use when conditions include storms, flooding, or other hazards.
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
Lead with the active alert, then give safety guidance.
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- A flat `<skill>.md` file uses the filename as the skill name:
|
|
143
|
+
|
|
144
|
+
```markdown
|
|
145
|
+
Always report temperatures in both Celsius and Fahrenheit.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Discovered skills merge with any `skills` in `config.ts`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning because they can't be statically merged.
|
|
149
|
+
|
|
150
|
+
## Add memory
|
|
151
|
+
|
|
152
|
+
Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
import { Memory } from '@mastra/memory'
|
|
156
|
+
|
|
157
|
+
export default new Memory()
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
|
|
161
|
+
|
|
162
|
+
## Add a workspace
|
|
163
|
+
|
|
164
|
+
When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
|
|
165
|
+
|
|
166
|
+
To customize it, add a `workspace.ts` that default-exports a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class):
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
|
|
170
|
+
|
|
171
|
+
export default new Workspace({
|
|
172
|
+
name: 'weather-workspace',
|
|
173
|
+
filesystem: new LocalFilesystem({ basePath: './data/weather' }),
|
|
174
|
+
sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
|
|
175
|
+
})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
You can also set `workspace` directly in `config.ts`. `config.workspace` wins over `workspace.ts`, and `workspace.ts` wins over the default workspace.
|
|
179
|
+
|
|
180
|
+
### Seed files
|
|
181
|
+
|
|
182
|
+
Add a `workspace/` directory to ship files with the agent. Mastra mirrors every file under it into the agent's default workspace at build time, so the agent starts with those files on disk:
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
src/mastra/agents/weather/
|
|
186
|
+
config.ts
|
|
187
|
+
workspace/
|
|
188
|
+
README.md
|
|
189
|
+
data/cities.json
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Seed files are copied into the bundle next to the running server. Commit the starting files alongside the agent that uses them.
|
|
193
|
+
|
|
194
|
+
## Add subagents
|
|
195
|
+
|
|
196
|
+
A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
src/mastra/agents/
|
|
200
|
+
supervisor/
|
|
201
|
+
config.ts
|
|
202
|
+
instructions.md
|
|
203
|
+
subagents/
|
|
204
|
+
researcher/
|
|
205
|
+
config.ts
|
|
206
|
+
instructions.md
|
|
207
|
+
tools/
|
|
208
|
+
search.ts
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Each subagent is assembled as its own agent and wired into the parent's `agents` map. The agent loop lowers it into a model-visible delegation tool. The tool name is the bare directory name, so the example above exposes `researcher` to the supervisor.
|
|
212
|
+
|
|
213
|
+
A subagent's `config.ts` must set a non-empty `description`. The description is what the model sees when deciding whether to delegate, so the build fails if it's missing.
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
import { agentConfig } from '@mastra/core/agent'
|
|
217
|
+
|
|
218
|
+
export default agentConfig({
|
|
219
|
+
model: 'openai/gpt-5.5',
|
|
220
|
+
description: 'Researches a topic and returns cited findings.',
|
|
221
|
+
})
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
|
|
225
|
+
|
|
226
|
+
Subagents are one level deep. A `subagents/` directory nested inside a subagent is ignored with a warning.
|
|
227
|
+
|
|
228
|
+
Naming rules:
|
|
229
|
+
|
|
230
|
+
- A subagent id that collides with one of the parent's tool keys is a build error.
|
|
231
|
+
- A duplicate subagent id under the same parent is a build error.
|
|
232
|
+
- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
|
|
233
|
+
- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
|
|
234
|
+
|
|
235
|
+
## Precedence rules
|
|
236
|
+
|
|
237
|
+
File-based and code-based agents coexist with deterministic rules:
|
|
238
|
+
|
|
239
|
+
- **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
|
|
240
|
+
- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
|
|
241
|
+
- **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
|
|
242
|
+
- **Model:** A missing `model` fails the build and names the agent directory.
|
|
243
|
+
- **Tools:** Tools from `tools/*.ts` merge with `config.tools`. On a key collision, `config.tools` wins and a warning is logged. If `config.tools` is a function, discovered tools are ignored with a warning.
|
|
244
|
+
- **Skills:** Skills from `skills/` merge with `config.skills`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning.
|
|
245
|
+
- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
|
|
246
|
+
- **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
|
|
247
|
+
- **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
|
|
248
|
+
|
|
249
|
+
## What happens at build time
|
|
250
|
+
|
|
251
|
+
File-based agents are discovered by the Mastra **bundler**, the step that runs under `mastra dev` and `mastra build`.
|
|
252
|
+
|
|
253
|
+
File-based agents are registered only when your app runs through the Mastra CLI. If you import your `mastra` instance directly, `agents/<name>/` directories aren't discovered.
|
|
254
|
+
|
|
255
|
+
When you consume Mastra as a library, register those agents in code instead of relying on file discovery:
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
import { Mastra } from '@mastra/core'
|
|
259
|
+
import { Agent } from '@mastra/core/agent'
|
|
260
|
+
|
|
261
|
+
const weather = new Agent({
|
|
262
|
+
id: 'weather',
|
|
263
|
+
name: 'weather',
|
|
264
|
+
instructions: 'You are a helpful weather assistant.',
|
|
265
|
+
model: 'openai/gpt-5.5',
|
|
266
|
+
})
|
|
267
|
+
|
|
268
|
+
export const mastra = new Mastra({
|
|
269
|
+
agents: { weather },
|
|
270
|
+
})
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Related
|
|
274
|
+
|
|
275
|
+
- [Agents overview](https://mastra.ai/docs/agents/overview)
|
|
276
|
+
- [Tools](https://mastra.ai/docs/agents/using-tools)
|
|
277
|
+
- [Skills](https://mastra.ai/docs/agents/skills)
|
|
278
|
+
- [Memory](https://mastra.ai/docs/memory/overview)
|
|
279
|
+
- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
|
|
280
|
+
- [Workspace](https://mastra.ai/docs/workspace/overview)
|
|
281
|
+
- [Studio overview](https://mastra.ai/docs/studio/overview)
|
|
282
|
+
- [`Agent` reference](https://mastra.ai/reference/agents/agent)
|
|
283
|
+
- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
|
|
284
|
+
- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
|
|
285
|
+
- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
|
|
286
|
+
- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)
|
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
Your new Mastra project, created with the `create mastra` command, comes with a predefined set of files and folders to help you get started.
|
|
4
4
|
|
|
5
|
-
Mastra is a framework, but it's **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
|
|
5
|
+
Mastra is a framework, but it's mostly **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
|
|
6
6
|
|
|
7
7
|
## Default project structure
|
|
8
8
|
|
|
9
9
|
A project created with the `create mastra` command looks like this:
|
|
10
10
|
|
|
11
|
-
```
|
|
11
|
+
```bash
|
|
12
12
|
src/
|
|
13
13
|
├── mastra/
|
|
14
14
|
│ ├── agents/
|
|
@@ -25,21 +25,25 @@ src/
|
|
|
25
25
|
└── tsconfig.json
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
|
|
29
29
|
|
|
30
30
|
### Folders
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
| Folder | Description
|
|
35
|
-
| ---------------------- |
|
|
36
|
-
| `src/mastra` | Entry point for all Mastra-related code and configuration.
|
|
37
|
-
| `src/mastra/agents` | Define and configure your agents - their behavior, goals, and tools.
|
|
38
|
-
| `src/mastra/workflows` | Define multi-step workflows that orchestrate agents and tools together.
|
|
39
|
-
| `src/mastra/tools` | Create reusable tools that your agents can call
|
|
40
|
-
| `src/mastra/mcp` |
|
|
41
|
-
| `src/mastra/scorers` |
|
|
42
|
-
|
|
32
|
+
Mastra recommends organizing your code into the following folders:
|
|
33
|
+
|
|
34
|
+
| Folder | Description |
|
|
35
|
+
| ---------------------- | ----------------------------------------------------------------------- |
|
|
36
|
+
| `src/mastra` | Entry point for all Mastra-related code and configuration. |
|
|
37
|
+
| `src/mastra/agents` | Define and configure your agents - their behavior, goals, and tools. |
|
|
38
|
+
| `src/mastra/workflows` | Define multi-step workflows that orchestrate agents and tools together. |
|
|
39
|
+
| `src/mastra/tools` | Create reusable tools that your agents can call |
|
|
40
|
+
| `src/mastra/mcp` | Implement custom MCP servers to share your tools with external agents |
|
|
41
|
+
| `src/mastra/scorers` | Define scorers for evaluating agent performance over time |
|
|
42
|
+
|
|
43
|
+
There are two special folder conventions in Mastra:
|
|
44
|
+
|
|
45
|
+
- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
|
|
46
|
+
- `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
|
|
43
47
|
|
|
44
48
|
### Top-level files
|
|
45
49
|
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# buildBasePrompt()
|
|
2
|
+
|
|
3
|
+
`buildBasePrompt()` builds the shared base system prompt for a coding agent — the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
|
|
4
|
+
|
|
5
|
+
Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. They default to `"Mastra Code"` / `"noreply@mastra.ai"`, so existing callers keep identical output.
|
|
6
|
+
|
|
7
|
+
Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build dynamic instructions for the agent.
|
|
8
|
+
|
|
9
|
+
## Usage example
|
|
10
|
+
|
|
11
|
+
Build the base prompt from a `PromptContext`:
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { buildBasePrompt } from '@mastra/core/coding-agent'
|
|
15
|
+
|
|
16
|
+
const prompt = buildBasePrompt({
|
|
17
|
+
projectPath: process.cwd(),
|
|
18
|
+
projectName: 'my-app',
|
|
19
|
+
gitBranch: 'main',
|
|
20
|
+
platform: process.platform,
|
|
21
|
+
date: new Date().toDateString(),
|
|
22
|
+
mode: 'build',
|
|
23
|
+
modelId: 'openai/gpt-5',
|
|
24
|
+
toolGuidance: '',
|
|
25
|
+
})
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
To rebrand the prompt, pass the product and co-author fields:
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
const prompt = buildBasePrompt({
|
|
32
|
+
// ...environment fields
|
|
33
|
+
productName: 'Acme Coder',
|
|
34
|
+
coAuthorName: 'Acme Bot',
|
|
35
|
+
coAuthorEmail: 'bot@acme.dev',
|
|
36
|
+
})
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Parameters
|
|
40
|
+
|
|
41
|
+
`buildBasePrompt()` takes a single `PromptContext` object.
|
|
42
|
+
|
|
43
|
+
**projectPath** (`string`): Absolute path to the project root.
|
|
44
|
+
|
|
45
|
+
**projectName** (`string`): Display name of the project.
|
|
46
|
+
|
|
47
|
+
**gitBranch** (`string`): Current git branch, if the project is a git repository.
|
|
48
|
+
|
|
49
|
+
**platform** (`string`): Operating system platform (for example, the value of process.platform).
|
|
50
|
+
|
|
51
|
+
**commonBinaries** (`{ name: string; path: string | null }[]`): Common binaries detected on the system, each with a name and resolved path (or null when not found).
|
|
52
|
+
|
|
53
|
+
**date** (`string`): Current date string injected into the prompt.
|
|
54
|
+
|
|
55
|
+
**mode** (`string`): Active agent mode (for example, "build" or "plan").
|
|
56
|
+
|
|
57
|
+
**modelId** (`string`): Identifier of the active model, included in the commit Co-Authored-By line when provided.
|
|
58
|
+
|
|
59
|
+
**activePlan** (`{ title: string; plan: string; approvedAt: string } | null`): The currently approved plan, if any.
|
|
60
|
+
|
|
61
|
+
**toolGuidance** (`string`): Tool-usage guidance section appended to the prompt.
|
|
62
|
+
|
|
63
|
+
**productName** (`string`): Display name used in the prompt header. (Default: `Mastra Code`)
|
|
64
|
+
|
|
65
|
+
**coAuthorName** (`string`): Name used in the commit Co-Authored-By line. (Default: `Mastra Code`)
|
|
66
|
+
|
|
67
|
+
**coAuthorEmail** (`string`): Email used in the commit Co-Authored-By line. (Default: `noreply@mastra.ai`)
|
|
68
|
+
|
|
69
|
+
## Returns
|
|
70
|
+
|
|
71
|
+
**prompt** (`string`): The base system prompt for the coding agent.
|
|
72
|
+
|
|
73
|
+
## Related
|
|
74
|
+
|
|
75
|
+
- [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent)
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# createCodingAgent()
|
|
2
|
+
|
|
3
|
+
`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
|
|
4
|
+
|
|
5
|
+
The returned value is a standard `Agent`, so it works anywhere an `Agent` does — including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
|
|
6
|
+
|
|
7
|
+
## Usage example
|
|
8
|
+
|
|
9
|
+
Pass a model, instructions, and tools. The factory fills in the workspace, task signal, error processors, and goal prompt:
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
import { createCodingAgent } from '@mastra/core/coding-agent'
|
|
13
|
+
|
|
14
|
+
const agent = createCodingAgent({
|
|
15
|
+
id: 'my-coding-agent',
|
|
16
|
+
name: 'My Coding Agent',
|
|
17
|
+
model: 'openai/gpt-5',
|
|
18
|
+
instructions: 'You are a helpful coding assistant.',
|
|
19
|
+
tools: {},
|
|
20
|
+
})
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Parameters
|
|
24
|
+
|
|
25
|
+
`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide always take precedence over the factory defaults.
|
|
26
|
+
|
|
27
|
+
**model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): The language model the agent uses. Passed straight through to Agent.
|
|
28
|
+
|
|
29
|
+
**instructions** (`string | DynamicArgument<string>`): System instructions for the agent. Passed straight through to Agent.
|
|
30
|
+
|
|
31
|
+
**tools** (`ToolsInput | DynamicArgument<ToolsInput>`): Tools available to the agent. Passed straight through to Agent.
|
|
32
|
+
|
|
33
|
+
**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, the factory builds no default — opt out when the workspace is wired elsewhere (for example at the AgentController level).
|
|
34
|
+
|
|
35
|
+
**basePath** (`string`): Base path for the default workspace built when workspace is omitted. (Default: `process.cwd()`)
|
|
36
|
+
|
|
37
|
+
**signals** (`SignalProvider[]`): Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.
|
|
38
|
+
|
|
39
|
+
**errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to the ECONNRESET/bad-request retry stack plus PrefillErrorHandler and ProviderHistoryCompat.
|
|
40
|
+
|
|
41
|
+
**goal** (`AgentGoalConfig`): Goal configuration. When provided without a prompt, the prompt defaults to DEFAULT\_GOAL\_JUDGE\_PROMPT.
|
|
42
|
+
|
|
43
|
+
## Returns
|
|
44
|
+
|
|
45
|
+
**agent** (`Agent`): A coding agent with the resolved workspace, signals, error processors, and goal applied.
|
|
46
|
+
|
|
47
|
+
## Defaults
|
|
48
|
+
|
|
49
|
+
The factory only fills a default when you do not provide the corresponding field. Caller-provided values always win.
|
|
50
|
+
|
|
51
|
+
| Field | Default when omitted |
|
|
52
|
+
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `workspace` | A [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) backed by `LocalFilesystem` and `LocalSandbox` rooted at the base path. |
|
|
54
|
+
| `signals` | A single [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider). |
|
|
55
|
+
| `errorProcessors` | ECONNRESET and bad-request retry processors plus `PrefillErrorHandler` and `ProviderHistoryCompat`. |
|
|
56
|
+
| `goal.prompt` | `DEFAULT_GOAL_JUDGE_PROMPT` (only when a `goal` is configured). |
|
|
57
|
+
|
|
58
|
+
### Workspace
|
|
59
|
+
|
|
60
|
+
When the `workspace` key is omitted, the factory builds a local workspace rooted at `basePath` (default `process.cwd()`):
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
|
|
64
|
+
|
|
65
|
+
new Workspace({
|
|
66
|
+
filesystem: new LocalFilesystem({ basePath }),
|
|
67
|
+
sandbox: new LocalSandbox({ workingDirectory: basePath }),
|
|
68
|
+
})
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
To opt out — for example when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level — pass `workspace: undefined` explicitly:
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
const agent = createCodingAgent({
|
|
75
|
+
id: 'my-coding-agent',
|
|
76
|
+
name: 'My Coding Agent',
|
|
77
|
+
model: 'openai/gpt-5',
|
|
78
|
+
instructions: 'You are a helpful coding assistant.',
|
|
79
|
+
tools: {},
|
|
80
|
+
workspace: undefined, // opt out of the default workspace
|
|
81
|
+
})
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Error processors
|
|
85
|
+
|
|
86
|
+
The default error processors apply a retry policy for transient failures:
|
|
87
|
+
|
|
88
|
+
- Network resets (`ECONNRESET` / `socket hang up`) retry up to twice with exponential backoff (`1000ms * 2^retryCount`, capped at `30000ms`).
|
|
89
|
+
- Bad-request errors retry once after `2000ms`.
|
|
90
|
+
|
|
91
|
+
`PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
|
|
92
|
+
|
|
93
|
+
## Related
|
|
94
|
+
|
|
95
|
+
- [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt)
|
|
96
|
+
- [`Agent`](https://mastra.ai/reference/agents/agent)
|
|
97
|
+
- [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class)
|
package/.docs/reference/index.md
CHANGED
|
@@ -74,6 +74,8 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
74
74
|
- [Tools API](https://mastra.ai/reference/client-js/tools)
|
|
75
75
|
- [Vectors API](https://mastra.ai/reference/client-js/vectors)
|
|
76
76
|
- [Workflows API](https://mastra.ai/reference/client-js/workflows)
|
|
77
|
+
- [buildBasePrompt()](https://mastra.ai/reference/coding-agent/build-base-prompt)
|
|
78
|
+
- [createCodingAgent()](https://mastra.ai/reference/coding-agent/create-coding-agent)
|
|
77
79
|
- [Mastra Class](https://mastra.ai/reference/core/mastra-class)
|
|
78
80
|
- [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
|
|
79
81
|
- [.addGateway()](https://mastra.ai/reference/core/addGateway)
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.2.3-alpha.14
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`0ac14ce`](https://github.com/mastra-ai/mastra/commit/0ac14cea48e1b0a7857782153c78f7242fdf7e1a), [`c2f0b7f`](https://github.com/mastra-ai/mastra/commit/c2f0b7f1370f4428d165f51f0d1d9a48331cc257)]:
|
|
8
|
+
- @mastra/core@1.48.0-alpha.8
|
|
9
|
+
|
|
10
|
+
## 1.2.3-alpha.13
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [[`8be63b0`](https://github.com/mastra-ai/mastra/commit/8be63b015fb8d72cea1220f05e7dc3bb997cc249), [`345eecc`](https://github.com/mastra-ai/mastra/commit/345eecce6ba519b5d987f0e10b5de4c8e5734580), [`ee14cae`](https://github.com/mastra-ai/mastra/commit/ee14cae244805783bde518a6142de28b744b169c)]:
|
|
15
|
+
- @mastra/core@1.48.0-alpha.7
|
|
16
|
+
|
|
3
17
|
## 1.2.3-alpha.12
|
|
4
18
|
|
|
5
19
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.3-alpha.
|
|
3
|
+
"version": "1.2.3-alpha.15",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
"jsdom": "^26.1.0",
|
|
29
29
|
"local-pkg": "^1.1.2",
|
|
30
30
|
"zod": "^4.4.3",
|
|
31
|
-
"@mastra/
|
|
32
|
-
"@mastra/
|
|
31
|
+
"@mastra/core": "1.48.0-alpha.8",
|
|
32
|
+
"@mastra/mcp": "^1.12.1-alpha.0"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
35
|
"@hono/node-server": "^1.19.11",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
"vitest": "4.1.8",
|
|
48
48
|
"@internal/lint": "0.0.109",
|
|
49
49
|
"@internal/types-builder": "0.0.84",
|
|
50
|
-
"@mastra/core": "1.48.0-alpha.
|
|
50
|
+
"@mastra/core": "1.48.0-alpha.8"
|
|
51
51
|
},
|
|
52
52
|
"homepage": "https://mastra.ai",
|
|
53
53
|
"repository": {
|