@mastra/mcp-docs-server 1.1.32-alpha.4 → 1.1.32-alpha.5
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/server/server-adapters.md +91 -8
- package/.docs/docs/workspace/search.md +39 -0
- package/.docs/guides/getting-started/nestjs.md +238 -0
- package/.docs/reference/datasets/startExperiment.md +28 -2
- package/.docs/reference/index.md +1 -0
- package/.docs/reference/server/nestjs-adapter.md +169 -0
- package/.docs/reference/workspace/workspace-class.md +1 -1
- package/CHANGELOG.md +7 -0
- package/package.json +4 -4
|
@@ -20,6 +20,7 @@ Mastra currently provides these official server adapters:
|
|
|
20
20
|
- [@mastra/hono](https://mastra.ai/reference/server/hono-adapter)
|
|
21
21
|
- [@mastra/fastify](https://mastra.ai/reference/server/fastify-adapter)
|
|
22
22
|
- [@mastra/koa](https://mastra.ai/reference/server/koa-adapter)
|
|
23
|
+
- [@mastra/nestjs](https://mastra.ai/reference/server/nestjs-adapter)
|
|
23
24
|
|
|
24
25
|
You can build your own adapter, read [custom adapters](https://mastra.ai/docs/server/custom-adapters) for details.
|
|
25
26
|
|
|
@@ -71,7 +72,7 @@ pnpm add @mastra/express@latest
|
|
|
71
72
|
yarn add @mastra/express@latest
|
|
72
73
|
```
|
|
73
74
|
|
|
74
|
-
**
|
|
75
|
+
**NestJS**:
|
|
75
76
|
|
|
76
77
|
```bash
|
|
77
78
|
bun add @mastra/express@latest
|
|
@@ -227,6 +228,56 @@ yarn add @mastra/koa@latest
|
|
|
227
228
|
bun add @mastra/koa@latest
|
|
228
229
|
```
|
|
229
230
|
|
|
231
|
+
**Tab 21**:
|
|
232
|
+
|
|
233
|
+
**npm**:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
npm install @mastra/nestjs@latest
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
**pnpm**:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
pnpm add @mastra/nestjs@latest
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**Yarn**:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
yarn add @mastra/nestjs@latest
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
**Bun**:
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
bun add @mastra/nestjs@latest
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
**Tab 22**:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npm install @mastra/nestjs@latest
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
**Tab 23**:
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
pnpm add @mastra/nestjs@latest
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**Tab 24**:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
yarn add @mastra/nestjs@latest
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
**Tab 25**:
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
bun add @mastra/nestjs@latest
|
|
279
|
+
```
|
|
280
|
+
|
|
230
281
|
## Configuration
|
|
231
282
|
|
|
232
283
|
Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
|
|
@@ -336,6 +387,37 @@ app.listen(port, () => {
|
|
|
336
387
|
|
|
337
388
|
> **Info:** See the [Koa Adapter](https://mastra.ai/reference/server/koa-adapter) documentation for full configuration options.
|
|
338
389
|
|
|
390
|
+
**NestJS**:
|
|
391
|
+
|
|
392
|
+
```typescript
|
|
393
|
+
import { Module } from '@nestjs/common'
|
|
394
|
+
import { MastraModule } from '@mastra/nestjs'
|
|
395
|
+
import { mastra } from './mastra'
|
|
396
|
+
|
|
397
|
+
@Module({
|
|
398
|
+
imports: [
|
|
399
|
+
MastraModule.register({
|
|
400
|
+
mastra,
|
|
401
|
+
}),
|
|
402
|
+
],
|
|
403
|
+
})
|
|
404
|
+
export class AppModule {}
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
import { NestFactory } from '@nestjs/core'
|
|
409
|
+
import { AppModule } from './app.module'
|
|
410
|
+
|
|
411
|
+
async function bootstrap() {
|
|
412
|
+
const app = await NestFactory.create(AppModule)
|
|
413
|
+
await app.listen(3000)
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
bootstrap()
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
> **Info:** See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) documentation for full configuration options.
|
|
420
|
+
|
|
339
421
|
## Initialization flow
|
|
340
422
|
|
|
341
423
|
Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
|
|
@@ -553,10 +635,11 @@ See [MCP](https://mastra.ai/docs/mcp/overview) for configuration details and how
|
|
|
553
635
|
|
|
554
636
|
## Related
|
|
555
637
|
|
|
556
|
-
- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter)
|
|
557
|
-
- [Express Adapter](https://mastra.ai/reference/server/express-adapter)
|
|
558
|
-
- [
|
|
559
|
-
- [
|
|
560
|
-
- [
|
|
561
|
-
- [
|
|
562
|
-
- [
|
|
638
|
+
- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter) - Hono-specific setup
|
|
639
|
+
- [Express Adapter](https://mastra.ai/reference/server/express-adapter) - Express-specific setup
|
|
640
|
+
- [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) - NestJS-specific setup
|
|
641
|
+
- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters) - Building adapters for other frameworks
|
|
642
|
+
- [Server Configuration](https://mastra.ai/docs/server/mastra-server) - Using `mastra build` instead
|
|
643
|
+
- [Authentication](https://mastra.ai/docs/server/auth) - Configuring auth for your server
|
|
644
|
+
- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
|
|
645
|
+
- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes
|
|
@@ -83,6 +83,45 @@ const workspace = new Workspace({
|
|
|
83
83
|
})
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
+
### Batch embedding
|
|
87
|
+
|
|
88
|
+
The embedder above takes one text at a time. Indexing a workspace with hundreds of files calls the provider hundreds of times, which is slow and expensive.
|
|
89
|
+
|
|
90
|
+
When the provider supports batching (for example, OpenAI's `embedMany`), pass an embedder that takes an array of texts and accepts many embeddings back in one call. To opt in, set a `batch: true` property on the function. Mastra checks for that property at runtime and switches to the batched path.
|
|
91
|
+
|
|
92
|
+
The following example replaces the single-text embedder with a batched one. The embedder function takes an array, returns an array of embeddings in the same order, and carries two extra properties:
|
|
93
|
+
|
|
94
|
+
- `batch: true`: marks the function as batch-capable. Without this property, Mastra calls it one text at a time.
|
|
95
|
+
- `maxBatchSize`: the largest array the provider accepts in one call. Mastra splits larger requests into chunks of this size and sends them in parallel. Set this to your provider's documented limit (for example, 2048 for OpenAI, 96 for Cohere, 128 for Voyage). Omit it to send every pending text in one request.
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
|
|
99
|
+
import { PineconeVector } from '@mastra/pinecone'
|
|
100
|
+
import { embedMany } from 'ai'
|
|
101
|
+
import { openai } from '@ai-sdk/openai'
|
|
102
|
+
|
|
103
|
+
const model = openai.embedding('text-embedding-3-small')
|
|
104
|
+
|
|
105
|
+
const workspace = new Workspace({
|
|
106
|
+
filesystem: new LocalFilesystem({ basePath: './workspace' }),
|
|
107
|
+
vectorStore: new PineconeVector({
|
|
108
|
+
apiKey: process.env.PINECONE_API_KEY,
|
|
109
|
+
index: 'workspace-index',
|
|
110
|
+
}),
|
|
111
|
+
embedder: Object.assign(
|
|
112
|
+
async (texts: string[]) => {
|
|
113
|
+
const { embeddings } = await embedMany({ model, values: texts })
|
|
114
|
+
return embeddings
|
|
115
|
+
},
|
|
116
|
+
{ batch: true as const, maxBatchSize: 2048 },
|
|
117
|
+
),
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`Object.assign` adds the `batch` and `maxBatchSize` properties to the embedder function. Mastra reads them as metadata and never passes them to the provider.
|
|
122
|
+
|
|
123
|
+
Single-text embedders still work. The function signature `(text: string) => Promise<number[]>` is unchanged, so existing code keeps running without modification.
|
|
124
|
+
|
|
86
125
|
## Hybrid search
|
|
87
126
|
|
|
88
127
|
Configure both BM25 and vector search to enable hybrid mode, which combines keyword matching with semantic understanding.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Integrate Mastra in Your NestJS Project
|
|
2
|
+
|
|
3
|
+
In this guide, you'll build a tool-calling AI agent using Mastra and NestJS. The [NestJS server adapter](https://mastra.ai/reference/server/nestjs-adapter) registers Mastra's agent and workflow routes as a NestJS module, so they run inside your existing NestJS application.
|
|
4
|
+
|
|
5
|
+
## Before you begin
|
|
6
|
+
|
|
7
|
+
- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
|
|
8
|
+
- Install Node.js `v22.13.0` or later
|
|
9
|
+
- Use the NestJS Express platform (`@nestjs/platform-express`)
|
|
10
|
+
|
|
11
|
+
## Create a new NestJS app (optional)
|
|
12
|
+
|
|
13
|
+
If you already have a NestJS app, skip to the next step.
|
|
14
|
+
|
|
15
|
+
Run the following command to create a new NestJS app:
|
|
16
|
+
|
|
17
|
+
**npm**:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx @nestjs/cli new mastra-nest
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**pnpm**:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pnpm dlx @nestjs/cli new mastra-nest
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Yarn**:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
yarn dlx @nestjs/cli new mastra-nest
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Bun**:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
bun x @nestjs/cli new mastra-nest
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
This creates a project called `mastra-nest`, but you can replace it with any name you want.
|
|
42
|
+
|
|
43
|
+
## Initialize Mastra
|
|
44
|
+
|
|
45
|
+
Navigate to your NestJS project directory:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
cd mastra-nest
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
|
|
52
|
+
|
|
53
|
+
**npm**:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx mastra@latest init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**pnpm**:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pnpm dlx mastra@latest init
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Yarn**:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
yarn dlx mastra@latest init
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Bun**:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
bun x mastra@latest init
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
This creates a `src/mastra` folder with an example weather agent and the following files:
|
|
78
|
+
|
|
79
|
+
- `index.ts` - Mastra config, including memory
|
|
80
|
+
- `tools/weather-tool.ts` - a tool to fetch weather for a given location
|
|
81
|
+
- `agents/weather-agent.ts` - a weather agent with a prompt that uses the tool
|
|
82
|
+
|
|
83
|
+
You'll pass the `src/mastra/index.ts` file to the NestJS adapter in the next step.
|
|
84
|
+
|
|
85
|
+
## Add server adapter
|
|
86
|
+
|
|
87
|
+
Install the NestJS server adapter package:
|
|
88
|
+
|
|
89
|
+
**npm**:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm install @mastra/nestjs@latest
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**pnpm**:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pnpm add @mastra/nestjs@latest
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**Yarn**:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
yarn add @mastra/nestjs@latest
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
**Bun**:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
bun add @mastra/nestjs@latest
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Open `src/app.module.ts` and register `MastraModule`:
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
import { Module } from '@nestjs/common'
|
|
117
|
+
import { MastraModule } from '@mastra/nestjs'
|
|
118
|
+
import { mastra } from './mastra'
|
|
119
|
+
|
|
120
|
+
@Module({
|
|
121
|
+
imports: [
|
|
122
|
+
MastraModule.register({
|
|
123
|
+
mastra,
|
|
124
|
+
}),
|
|
125
|
+
],
|
|
126
|
+
})
|
|
127
|
+
export class AppModule {}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
|
|
131
|
+
|
|
132
|
+
## Test your agent
|
|
133
|
+
|
|
134
|
+
By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
|
|
135
|
+
|
|
136
|
+
Start your NestJS server:
|
|
137
|
+
|
|
138
|
+
**npm**:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npm run start
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**pnpm**:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
pnpm run start
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**Yarn**:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
yarn run start
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
**Bun**:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
bun run start
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
In a separate terminal window, use `curl` to ask the weather agent:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## Use Mastra in Your Own Services
|
|
169
|
+
|
|
170
|
+
The module exports two ways to access Mastra from your NestJS services: the `MastraService` wrapper and the `MASTRA` injection token.
|
|
171
|
+
|
|
172
|
+
### MastraService
|
|
173
|
+
|
|
174
|
+
`MastraService` is an injectable wrapper with convenience methods for common operations:
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
import { Injectable } from '@nestjs/common'
|
|
178
|
+
import { MastraService } from '@mastra/nestjs'
|
|
179
|
+
|
|
180
|
+
@Injectable()
|
|
181
|
+
export class AgentService {
|
|
182
|
+
constructor(private readonly mastraService: MastraService) {}
|
|
183
|
+
|
|
184
|
+
async chat(agentId: string, message: string) {
|
|
185
|
+
const agent = this.mastraService.getAgent(agentId)
|
|
186
|
+
return agent.generate({
|
|
187
|
+
messages: [{ role: 'user', content: message }],
|
|
188
|
+
})
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
async runWorkflow(workflowId: string, input: Record<string, unknown>) {
|
|
192
|
+
const workflow = this.mastraService.getWorkflow(workflowId)
|
|
193
|
+
return workflow.start({ inputData: input })
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`MastraService` exposes:
|
|
199
|
+
|
|
200
|
+
- `getMastra()` — returns the underlying `Mastra` instance
|
|
201
|
+
- `getAgent(id)` — shorthand for `mastra.getAgent(id)`
|
|
202
|
+
- `getWorkflow(id)` — shorthand for `mastra.getWorkflow(id)`
|
|
203
|
+
- `getOptions()` — returns the module configuration
|
|
204
|
+
- `isShuttingDown` — `true` after graceful shutdown begins
|
|
205
|
+
|
|
206
|
+
### MASTRA token
|
|
207
|
+
|
|
208
|
+
If you need the `Mastra` instance directly (e.g., to access storage, memory, or other core APIs), inject it with the `MASTRA` token:
|
|
209
|
+
|
|
210
|
+
```typescript
|
|
211
|
+
import { Injectable, Inject } from '@nestjs/common'
|
|
212
|
+
import { MASTRA } from '@mastra/nestjs'
|
|
213
|
+
import type { Mastra } from '@mastra/core/mastra'
|
|
214
|
+
|
|
215
|
+
@Injectable()
|
|
216
|
+
export class MemoryService {
|
|
217
|
+
constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
|
|
218
|
+
|
|
219
|
+
async getThreadMessages(threadId: string) {
|
|
220
|
+
const memory = this.mastra.getMemory()
|
|
221
|
+
return memory?.getMessages({ threadId })
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Both approaches use the same singleton `Mastra` instance registered by `MastraModule`.
|
|
227
|
+
|
|
228
|
+
## Next steps
|
|
229
|
+
|
|
230
|
+
You now have a working Mastra agent running inside NestJS. To extend the project:
|
|
231
|
+
|
|
232
|
+
- [Agents overview](https://mastra.ai/docs/agents/overview)
|
|
233
|
+
- [Using tools](https://mastra.ai/docs/agents/using-tools)
|
|
234
|
+
- [Agent memory](https://mastra.ai/docs/memory/overview)
|
|
235
|
+
|
|
236
|
+
For details on the NestJS integration:
|
|
237
|
+
|
|
238
|
+
- [NestJS Adapter reference](https://mastra.ai/reference/server/nestjs-adapter)
|
|
@@ -15,7 +15,7 @@ const mastra = new Mastra({
|
|
|
15
15
|
|
|
16
16
|
const dataset = await mastra.datasets.get({ id: 'dataset-id' })
|
|
17
17
|
|
|
18
|
-
// Run against a registered agent with
|
|
18
|
+
// Run against a registered agent with a flat scorer list
|
|
19
19
|
const summary = await dataset.startExperiment({
|
|
20
20
|
targetType: 'agent',
|
|
21
21
|
targetId: 'my-agent',
|
|
@@ -23,8 +23,34 @@ const summary = await dataset.startExperiment({
|
|
|
23
23
|
maxConcurrency: 10,
|
|
24
24
|
})
|
|
25
25
|
|
|
26
|
+
// Or pass the same categorised shape accepted by runEvals
|
|
27
|
+
const summary2 = await dataset.startExperiment({
|
|
28
|
+
targetType: 'agent',
|
|
29
|
+
targetId: 'my-agent',
|
|
30
|
+
scorers: {
|
|
31
|
+
agent: [accuracyScorer],
|
|
32
|
+
trajectory: [toolOrderScorer],
|
|
33
|
+
},
|
|
34
|
+
})
|
|
35
|
+
|
|
36
|
+
// For workflow targets, score individual steps with their own scorers
|
|
37
|
+
const summary3 = await dataset.startExperiment({
|
|
38
|
+
targetType: 'workflow',
|
|
39
|
+
targetId: 'my-workflow',
|
|
40
|
+
scorers: {
|
|
41
|
+
workflow: [overallScorer],
|
|
42
|
+
steps: {
|
|
43
|
+
'fetch-data': [fetchScorer],
|
|
44
|
+
transform: [transformScorer],
|
|
45
|
+
},
|
|
46
|
+
trajectory: [executionPathScorer],
|
|
47
|
+
},
|
|
48
|
+
})
|
|
49
|
+
|
|
26
50
|
console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
|
|
27
51
|
console.log(`Status: ${summary.status}`)
|
|
52
|
+
console.log(`${summary2.succeededCount}/${summary2.totalItems} succeeded`)
|
|
53
|
+
console.log(`Status: ${summary2.status}`)
|
|
28
54
|
```
|
|
29
55
|
|
|
30
56
|
## Parameters
|
|
@@ -33,7 +59,7 @@ console.log(`Status: ${summary.status}`)
|
|
|
33
59
|
|
|
34
60
|
**targetId** (`string`): ID of the registered target. Use with \`targetType\`.
|
|
35
61
|
|
|
36
|
-
**scorers** (`(MastraScorer | string)[]`): Scorers to evaluate each result.
|
|
62
|
+
**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to evaluate each result. Accepts a flat array of \`MastraScorer\` instances or registered scorer IDs, or the same categorised config shape used by \`runEvals\` (\`AgentScorerConfig\` / \`WorkflowScorerConfig\`). Trajectory scorers (\`type: "trajectory"\`) automatically receive a pre-extracted \`Trajectory\` as their output regardless of which form is used. For workflow targets, per-step scorers can be passed via \`scorers: { steps: { stepId: \[...] } }\` and run against each step's output; their results carry the originating \`stepId\` and keep \`targetScope: "span"\` (matching \`runEvals\`).
|
|
37
63
|
|
|
38
64
|
**name** (`string`): Display name for the experiment.
|
|
39
65
|
|
package/.docs/reference/index.md
CHANGED
|
@@ -191,6 +191,7 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
191
191
|
- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter)
|
|
192
192
|
- [Koa Adapter](https://mastra.ai/reference/server/koa-adapter)
|
|
193
193
|
- [MastraServer](https://mastra.ai/reference/server/mastra-server)
|
|
194
|
+
- [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter)
|
|
194
195
|
- [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
|
|
195
196
|
- [Server Routes](https://mastra.ai/reference/server/routes)
|
|
196
197
|
- [Overview](https://mastra.ai/reference/storage/overview)
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# NestJS Adapter
|
|
2
|
+
|
|
3
|
+
The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.
|
|
4
|
+
|
|
5
|
+
It is intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
|
|
6
|
+
|
|
7
|
+
> **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Install the NestJS adapter and ensure your app uses the Express platform:
|
|
12
|
+
|
|
13
|
+
**npm**:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @mastra/nestjs@latest
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
**pnpm**:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @mastra/nestjs@latest
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**Yarn**:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
yarn add @mastra/nestjs@latest
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Bun**:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
bun add @mastra/nestjs@latest
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Usage example
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { Module } from '@nestjs/common'
|
|
41
|
+
import { MastraModule } from '@mastra/nestjs'
|
|
42
|
+
import { mastra } from './mastra'
|
|
43
|
+
|
|
44
|
+
@Module({
|
|
45
|
+
imports: [
|
|
46
|
+
MastraModule.register({
|
|
47
|
+
mastra,
|
|
48
|
+
}),
|
|
49
|
+
],
|
|
50
|
+
})
|
|
51
|
+
export class AppModule {}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { NestFactory } from '@nestjs/core'
|
|
58
|
+
import { AppModule } from './app.module'
|
|
59
|
+
|
|
60
|
+
async function bootstrap() {
|
|
61
|
+
const app = await NestFactory.create(AppModule)
|
|
62
|
+
await app.listen(3000)
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
bootstrap()
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
By default, Mastra routes mount under `/api`. Use `prefix` to change it.
|
|
69
|
+
|
|
70
|
+
## Module options
|
|
71
|
+
|
|
72
|
+
**mastra** (`Mastra`): Mastra instance
|
|
73
|
+
|
|
74
|
+
**prefix** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `` `/api` ``)
|
|
75
|
+
|
|
76
|
+
**rateLimitOptions** (`{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }`): Rate limiting config (enabled by default)
|
|
77
|
+
|
|
78
|
+
**shutdownOptions** (`{ timeoutMs?: number; notifyClients?: boolean }`): Graceful shutdown configuration
|
|
79
|
+
|
|
80
|
+
**bodyLimitOptions** (`{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }`): Request body size limits
|
|
81
|
+
|
|
82
|
+
**streamOptions** (`{ redact?: boolean; heartbeatMs?: number }`): Streaming configuration
|
|
83
|
+
|
|
84
|
+
**tracingOptions** (`{ enabled?: boolean; serviceName?: string }`): OpenTelemetry tracing configuration
|
|
85
|
+
|
|
86
|
+
**contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): Request context parsing config
|
|
87
|
+
|
|
88
|
+
**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\`.
|
|
89
|
+
|
|
90
|
+
**tools** (`Record<string, Tool>`): Registered tools for the server
|
|
91
|
+
|
|
92
|
+
**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
|
|
93
|
+
|
|
94
|
+
**mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP transport options
|
|
95
|
+
|
|
96
|
+
**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Enable Mastra token auth. Disabled by default — most NestJS apps use their own auth guards. Query-string \`apiKey\` auth is opt-in for backward compatibility. (Default: `` `{ enabled: false }` ``)
|
|
97
|
+
|
|
98
|
+
## Async registration
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
import { Module } from '@nestjs/common'
|
|
102
|
+
import { ConfigModule, ConfigService } from '@nestjs/config'
|
|
103
|
+
import { MastraModule } from '@mastra/nestjs'
|
|
104
|
+
import { Mastra } from '@mastra/core/mastra'
|
|
105
|
+
|
|
106
|
+
@Module({
|
|
107
|
+
imports: [
|
|
108
|
+
ConfigModule.forRoot(),
|
|
109
|
+
MastraModule.registerAsync({
|
|
110
|
+
imports: [ConfigModule],
|
|
111
|
+
useFactory: (config: ConfigService) => ({
|
|
112
|
+
mastra: new Mastra({
|
|
113
|
+
agents: {
|
|
114
|
+
greeter: {
|
|
115
|
+
name: 'greeter',
|
|
116
|
+
description: 'Greets the user',
|
|
117
|
+
model: config.get('MASTRA_MODEL', 'openai/gpt-4o-mini'),
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
}),
|
|
121
|
+
prefix: config.get('MASTRA_PREFIX', '/api'),
|
|
122
|
+
}),
|
|
123
|
+
inject: [ConfigService],
|
|
124
|
+
}),
|
|
125
|
+
],
|
|
126
|
+
})
|
|
127
|
+
export class AppModule {}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Accessing Mastra
|
|
131
|
+
|
|
132
|
+
Use the `MASTRA` token or `MastraService` in your services:
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
import { Injectable, Inject } from '@nestjs/common'
|
|
136
|
+
import { MASTRA, MastraService } from '@mastra/nestjs'
|
|
137
|
+
import type { Mastra } from '@mastra/core/mastra'
|
|
138
|
+
|
|
139
|
+
@Injectable()
|
|
140
|
+
export class AgentService {
|
|
141
|
+
constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
@Injectable()
|
|
145
|
+
export class WorkflowService {
|
|
146
|
+
constructor(private readonly mastraService: MastraService) {}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## MCP routes
|
|
151
|
+
|
|
152
|
+
MCP endpoints are exposed under the API prefix:
|
|
153
|
+
|
|
154
|
+
- `POST /api/mcp/:serverId/mcp`
|
|
155
|
+
- `GET /api/mcp/:serverId/sse`
|
|
156
|
+
- `POST /api/mcp/:serverId/messages`
|
|
157
|
+
|
|
158
|
+
## Health routes
|
|
159
|
+
|
|
160
|
+
Operational endpoints stay unprefixed on purpose for infrastructure compatibility:
|
|
161
|
+
|
|
162
|
+
- `GET /health`
|
|
163
|
+
- `GET /ready`
|
|
164
|
+
- `GET /info`
|
|
165
|
+
|
|
166
|
+
## Related
|
|
167
|
+
|
|
168
|
+
- [Server Adapters](https://mastra.ai/docs/server/server-adapters)
|
|
169
|
+
- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server)
|
|
@@ -37,7 +37,7 @@ const workspace = new Workspace({
|
|
|
37
37
|
|
|
38
38
|
**vectorStore** (`MastraVector`): Vector store for semantic search
|
|
39
39
|
|
|
40
|
-
**embedder** (`(text: string) => Promise
|
|
40
|
+
**embedder** (`Embedder`): Function that turns text into vectors. Required when \`vectorStore\` is set. Accepts either a single-text function \`(text: string) => Promise\<number\[]>\` or a batch-capable function \`(texts: string\[]) => Promise\<number\[]\[]>\` that has a \`batch: true\` property and an optional \`maxBatchSize\`. See \[Batch embedding]\(/docs/workspace/search#batch-embedding).
|
|
41
41
|
|
|
42
42
|
**autoIndexPaths** (`string[]`): Paths or glob patterns to auto-index on init(). Supports glob patterns like '\*\*/\*.md' for selective indexing.
|
|
43
43
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.1.32-alpha.5
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006), [`04151c7`](https://github.com/mastra-ai/mastra/commit/04151c7dcea934b4fe9076708a23fac161195414), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006)]:
|
|
8
|
+
- @mastra/core@1.31.0-alpha.4
|
|
9
|
+
|
|
3
10
|
## 1.1.32-alpha.4
|
|
4
11
|
|
|
5
12
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.1.32-alpha.
|
|
3
|
+
"version": "1.1.32-alpha.5",
|
|
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": "^4.3.6",
|
|
32
|
-
"@mastra/
|
|
33
|
-
"@mastra/
|
|
32
|
+
"@mastra/mcp": "^1.6.0",
|
|
33
|
+
"@mastra/core": "1.31.0-alpha.4"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"@hono/node-server": "^1.19.11",
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"vitest": "4.1.5",
|
|
49
49
|
"@internal/lint": "0.0.89",
|
|
50
50
|
"@internal/types-builder": "0.0.64",
|
|
51
|
-
"@mastra/core": "1.31.0-alpha.
|
|
51
|
+
"@mastra/core": "1.31.0-alpha.4"
|
|
52
52
|
},
|
|
53
53
|
"homepage": "https://mastra.ai",
|
|
54
54
|
"repository": {
|