@mastra/mcp-docs-server 1.2.10-alpha.8 → 1.2.10
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/message-history.md +18 -0
- package/.docs/docs/server/auth/fga.md +3 -0
- package/.docs/models/embeddings.md +1 -0
- package/.docs/models/gateways/openrouter.md +1 -4
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/ambient.md +3 -3
- package/.docs/models/providers/fireworks-ai.md +1 -3
- package/.docs/reference/agents/inngest-agent.md +31 -2
- package/.docs/reference/auth/fga.md +140 -0
- package/.docs/reference/client-js/memory.md +14 -0
- package/.docs/reference/index.md +1 -0
- package/.docs/reference/memory/recall.md +28 -3
- package/.docs/reference/streaming/agents/stream.md +2 -0
- package/CHANGELOG.md +14 -0
- package/package.json +5 -5
|
@@ -263,6 +263,24 @@ const { messages } = await memory.recall({
|
|
|
263
263
|
})
|
|
264
264
|
```
|
|
265
265
|
|
|
266
|
+
Filter by shallow message metadata:
|
|
267
|
+
|
|
268
|
+
```typescript
|
|
269
|
+
const { messages } = await memory.recall({
|
|
270
|
+
threadId: 'thread-123',
|
|
271
|
+
filter: {
|
|
272
|
+
metadata: {
|
|
273
|
+
category: 'billing',
|
|
274
|
+
escalated: true,
|
|
275
|
+
priority: 2,
|
|
276
|
+
archivedAt: null,
|
|
277
|
+
},
|
|
278
|
+
},
|
|
279
|
+
})
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. All specified metadata keys must match with AND semantics, and `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the storage backend. Some backends can push parts of the filter into the database, while others scan candidate messages after thread, resource, and date constraints are applied but before pagination.
|
|
283
|
+
|
|
266
284
|
Fetch a single message by ID:
|
|
267
285
|
|
|
268
286
|
```typescript
|
|
@@ -254,6 +254,8 @@ class MyFGAProvider implements IFGAProvider {
|
|
|
254
254
|
}
|
|
255
255
|
```
|
|
256
256
|
|
|
257
|
+
> **Note:** See the [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga) for every method, parameter, and the `ActorSignal` type.
|
|
258
|
+
|
|
257
259
|
## System actors
|
|
258
260
|
|
|
259
261
|
Autonomous and scheduled agents run without an end user. Mark these calls with an actor signal so FGA can tell them apart from user requests:
|
|
@@ -296,5 +298,6 @@ The actor signal is trusted input, so construct it server-side:
|
|
|
296
298
|
|
|
297
299
|
## Related
|
|
298
300
|
|
|
301
|
+
- [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
|
|
299
302
|
- [Authentication overview](https://mastra.ai/docs/server/auth)
|
|
300
303
|
- [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)
|
|
@@ -96,6 +96,7 @@ const customModel = voyageEmbedding({
|
|
|
96
96
|
model: "voyage-3.5",
|
|
97
97
|
inputType: "query", // or 'document'
|
|
98
98
|
outputDimension: 512, // 256, 512, 1024, or 2048
|
|
99
|
+
baseUrl: "https://ai.mongodb.com/v1", // Optional: custom endpoint (e.g. MongoDB-hosted Voyage)
|
|
99
100
|
});
|
|
100
101
|
|
|
101
102
|
const { embeddings: customEmbeddings } = await customModel.doEmbed({
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# OpenRouter
|
|
4
4
|
|
|
5
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 340 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
8
8
|
|
|
@@ -139,8 +139,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
139
139
|
| `inclusionai/ling-2.6-flash` |
|
|
140
140
|
| `inclusionai/ling-3.0-flash:free` |
|
|
141
141
|
| `inclusionai/ring-2.6-1t` |
|
|
142
|
-
| `inflection/inflection-3-pi` |
|
|
143
|
-
| `inflection/inflection-3-productivity` |
|
|
144
142
|
| `kwaipilot/kat-coder-air-v2.5` |
|
|
145
143
|
| `kwaipilot/kat-coder-pro-v2` |
|
|
146
144
|
| `kwaipilot/kat-coder-pro-v2.5` |
|
|
@@ -224,7 +222,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
224
222
|
| `openai/gpt-4o-2024-11-20` |
|
|
225
223
|
| `openai/gpt-4o-mini` |
|
|
226
224
|
| `openai/gpt-4o-mini-2024-07-18` |
|
|
227
|
-
| `openai/gpt-4o-mini-search-preview` |
|
|
228
225
|
| `openai/gpt-4o-search-preview` |
|
|
229
226
|
| `openai/gpt-5` |
|
|
230
227
|
| `openai/gpt-5-chat` |
|
package/.docs/models/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Model Providers
|
|
4
4
|
|
|
5
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
5
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4937 models from 161 providers through a single API.
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
@@ -36,13 +36,13 @@ for await (const chunk of stream) {
|
|
|
36
36
|
|
|
37
37
|
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
38
38
|
| ------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
39
|
-
| `ambient/ambient/large` | 101K | | | | | | $
|
|
39
|
+
| `ambient/ambient/large` | 101K | | | | | | $0.76 | $2 |
|
|
40
40
|
| `ambient/deepseek/deepseek-v4-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
41
41
|
| `ambient/moonshotai/kimi-k2.6` | 262K | | | | | | $0.95 | $4 |
|
|
42
|
-
| `ambient/moonshotai/kimi-k2.7-code` | 262K | | | | | | $0.
|
|
42
|
+
| `ambient/moonshotai/kimi-k2.7-code` | 262K | | | | | | $0.73 | $4 |
|
|
43
43
|
| `ambient/stepfun/step-3.7-flash` | 262K | | | | | | $0.19 | $1 |
|
|
44
44
|
| `ambient/xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.40 | $2 |
|
|
45
|
-
| `ambient/z-ai/glm-5.2` | 101K | | | | | | $
|
|
45
|
+
| `ambient/z-ai/glm-5.2` | 101K | | | | | | $0.76 | $2 |
|
|
46
46
|
| `ambient/zai-org/GLM-5.1-FP8` | 203K | | | | | | $1 | $4 |
|
|
47
47
|
| `ambient/zai-org/GLM-5.2-FP8` | 203K | | | | | | $1 | $4 |
|
|
48
48
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Fireworks AI
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 14 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Fireworks AI documentation](https://fireworks.ai/docs/).
|
|
8
8
|
|
|
@@ -38,7 +38,6 @@ for await (const chunk of stream) {
|
|
|
38
38
|
| ------------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
39
39
|
| `fireworks-ai/accounts/fireworks/models/deepseek-v4-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
40
40
|
| `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro` | 1.0M | | | | | | $2 | $3 |
|
|
41
|
-
| `fireworks-ai/accounts/fireworks/models/glm-5p1` | 203K | | | | | | $1 | $4 |
|
|
42
41
|
| `fireworks-ai/accounts/fireworks/models/glm-5p2` | 1.0M | | | | | | $1 | $4 |
|
|
43
42
|
| `fireworks-ai/accounts/fireworks/models/gpt-oss-120b` | 131K | | | | | | $0.15 | $0.60 |
|
|
44
43
|
| `fireworks-ai/accounts/fireworks/models/gpt-oss-20b` | 131K | | | | | | $0.07 | $0.30 |
|
|
@@ -47,7 +46,6 @@ for await (const chunk of stream) {
|
|
|
47
46
|
| `fireworks-ai/accounts/fireworks/models/minimax-m2p7` | 197K | | | | | | $0.30 | $1 |
|
|
48
47
|
| `fireworks-ai/accounts/fireworks/models/minimax-m3` | 512K | | | | | | $0.30 | $1 |
|
|
49
48
|
| `fireworks-ai/accounts/fireworks/models/qwen3p7-plus` | 262K | | | | | | $0.40 | $2 |
|
|
50
|
-
| `fireworks-ai/accounts/fireworks/routers/glm-5p1-fast` | 203K | | | | | | $3 | $9 |
|
|
51
49
|
| `fireworks-ai/accounts/fireworks/routers/glm-5p2-fast` | 1.0M | | | | | | $2 | $7 |
|
|
52
50
|
| `fireworks-ai/accounts/fireworks/routers/kimi-k2p6-fast` | 262K | | | | | | $2 | $8 |
|
|
53
51
|
| `fireworks-ai/accounts/fireworks/routers/kimi-k2p6-turbo` | 262K | | | | | | $2 | $8 |
|
|
@@ -65,7 +65,7 @@ Returns: [`InngestAgent`](#inngestagent-interface)
|
|
|
65
65
|
|
|
66
66
|
### Parameters
|
|
67
67
|
|
|
68
|
-
**agent** (`Agent`): The Agent to wrap with Inngest durable execution.
|
|
68
|
+
**agent** (`Agent`): The Agent to wrap with Inngest durable execution. Methods not implemented by InngestAgent (e.g., listTools() and getMemory()) delegate to this agent via a Proxy.
|
|
69
69
|
|
|
70
70
|
**inngest** (`Inngest`): The Inngest client instance. Used to send workflow events and, in SDK v4, publish realtime stream events.
|
|
71
71
|
|
|
@@ -81,7 +81,7 @@ Returns: [`InngestAgent`](#inngestagent-interface)
|
|
|
81
81
|
|
|
82
82
|
## `InngestAgent` interface
|
|
83
83
|
|
|
84
|
-
The object returned by `createInngestAgent()`. It
|
|
84
|
+
The object returned by `createInngestAgent()`. It provides the durable execution methods below. Any property or method not explicitly defined (e.g., `listTools()` and `getMemory()`) is forwarded to the underlying agent via a Proxy.
|
|
85
85
|
|
|
86
86
|
### Properties
|
|
87
87
|
|
|
@@ -152,6 +152,35 @@ The third argument accepts `threadId` and `resourceId` in addition to the lifecy
|
|
|
152
152
|
|
|
153
153
|
Returns: [`Promise<InngestAgentStreamResult>`](#inngestagentstreamresult)
|
|
154
154
|
|
|
155
|
+
#### `generate(messages, options?)`
|
|
156
|
+
|
|
157
|
+
Runs a response on Inngest's durable execution engine and resolves with a single `FullOutput`. If the run suspends, `generate()` resolves with `finishReason: 'suspended'`. The `runId` option is optional. If you omit it, `generate()` creates a run ID and returns it in `result.runId`. Continue the run with [`resumeGenerate()`](#resumegeneraterunid-resumedata-options). Use [`stream()`](#streammessages-options) with `onSuspended` when the caller needs a suspension callback.
|
|
158
|
+
|
|
159
|
+
```typescript
|
|
160
|
+
const result = await durableAgent.generate('Delete the old records', {
|
|
161
|
+
requireToolApproval: true,
|
|
162
|
+
})
|
|
163
|
+
|
|
164
|
+
result.runId // Generated automatically
|
|
165
|
+
result.finishReason // 'suspended' when approval is required
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Returns: `Promise<FullOutput<TOutput>>`
|
|
169
|
+
|
|
170
|
+
#### `resumeGenerate(runId, resumeData, options?)`
|
|
171
|
+
|
|
172
|
+
Resumes a suspended `generate()` run and resolves with a single `FullOutput`.
|
|
173
|
+
|
|
174
|
+
```typescript
|
|
175
|
+
if (!result.runId) {
|
|
176
|
+
throw new Error('Run ID is missing')
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
const resumedResult = await durableAgent.resumeGenerate(result.runId, { approved: true })
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Returns: `Promise<FullOutput<TOutput>>`
|
|
183
|
+
|
|
155
184
|
#### `observe(runId, options?)`
|
|
156
185
|
|
|
157
186
|
Reconnects to an existing run, replaying cached events before delivering live ones. Use this after a network disconnection. Pass `offset` to start replay from a known position.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# IFGAProvider
|
|
4
|
+
|
|
5
|
+
The `IFGAProvider` interface defines a fine-grained authorization (FGA) provider. Mastra calls it to decide whether a user or a system actor may perform a permission on a specific resource. Implement it to connect Mastra to an FGA backend, such as WorkOS Authorization.
|
|
6
|
+
|
|
7
|
+
For concepts, configuration, and the lifecycle points where Mastra enforces FGA, see [Fine-grained authorization](https://mastra.ai/docs/server/auth/fga).
|
|
8
|
+
|
|
9
|
+
## Usage example
|
|
10
|
+
|
|
11
|
+
The following example implements a minimal provider. `require` throws to deny, and `check` returns a boolean.
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { FGADeniedError } from '@mastra/core/auth/ee'
|
|
15
|
+
import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'
|
|
16
|
+
|
|
17
|
+
class MyFGAProvider implements IFGAProvider {
|
|
18
|
+
async check(user: any, params: FGACheckParams): Promise<boolean> {
|
|
19
|
+
// Your authorization logic.
|
|
20
|
+
return true
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
async require(user: any, params: FGACheckParams): Promise<void> {
|
|
24
|
+
if (!(await this.check(user, params))) {
|
|
25
|
+
throw new FGADeniedError(user, params.resource, params.permission)
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
async filterAccessible<T extends { id: string }>(
|
|
30
|
+
user: any,
|
|
31
|
+
resources: T[],
|
|
32
|
+
resourceType: string,
|
|
33
|
+
permission: MastraFGAPermissionInput,
|
|
34
|
+
): Promise<T[]> {
|
|
35
|
+
return resources
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Methods
|
|
41
|
+
|
|
42
|
+
### `check(user, params)`
|
|
43
|
+
|
|
44
|
+
Returns whether `user` has the permission on the resource. Use it for non-throwing checks, such as filtering or conditional UI.
|
|
45
|
+
|
|
46
|
+
Returns: `Promise<boolean>`
|
|
47
|
+
|
|
48
|
+
### `require(user, params)`
|
|
49
|
+
|
|
50
|
+
Throws `FGADeniedError` when `user` lacks the permission. Mastra calls this at its [enforcement points](https://mastra.ai/docs/server/auth/fga).
|
|
51
|
+
|
|
52
|
+
Returns: `Promise<void>`
|
|
53
|
+
|
|
54
|
+
### `filterAccessible(user, resources, resourceType, permission)`
|
|
55
|
+
|
|
56
|
+
Returns the subset of `resources` that `user` can access with `permission`.
|
|
57
|
+
|
|
58
|
+
Returns: `Promise<T[]>`
|
|
59
|
+
|
|
60
|
+
### `requireActor(actor, params)`
|
|
61
|
+
|
|
62
|
+
Authorizes a non-user system actor, such as an autonomous or scheduled agent. Optional.
|
|
63
|
+
|
|
64
|
+
System actors skip the user-centric `require()` path, so implement `requireActor` to enforce per-agent least privilege for them. Throw `FGADeniedError` to deny. When a provider doesn't implement `requireActor`, Mastra preserves the trusted-actor bypass (allow after the tenant-scope check), so adding it is backward compatible.
|
|
65
|
+
|
|
66
|
+
Treat `actor.permissions` as an untrusted claim. Resolve the agent's authoritative grants from a trusted source keyed by `actor.agentId`, rather than trusting the inline values. See [System actors](https://mastra.ai/docs/server/auth/fga).
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import { FGADeniedError } from '@mastra/core/auth/ee'
|
|
70
|
+
import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'
|
|
71
|
+
|
|
72
|
+
class MyFGAProvider implements IFGAProvider {
|
|
73
|
+
// ...check, require, filterAccessible...
|
|
74
|
+
|
|
75
|
+
async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
|
|
76
|
+
const agentId = actor === true ? undefined : actor.agentId
|
|
77
|
+
// Resolve the agent's authoritative grants from a trusted source keyed by agentId.
|
|
78
|
+
const granted = await this.grantsForAgent(agentId)
|
|
79
|
+
const required = Array.isArray(params.permission) ? params.permission : [params.permission]
|
|
80
|
+
if (!required.some(permission => granted.includes(permission))) {
|
|
81
|
+
throw new FGADeniedError(null, params.resource, params.permission)
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Returns: `Promise<void>`
|
|
88
|
+
|
|
89
|
+
## Configuration properties
|
|
90
|
+
|
|
91
|
+
Optional properties control route coverage and startup validation.
|
|
92
|
+
|
|
93
|
+
**requireForProtectedRoutes** (`boolean`): When true, protected routes without route-level FGA metadata or resolver output are denied instead of allowed through. (Default: `false`)
|
|
94
|
+
|
|
95
|
+
**auditProtectedRoutes** (`boolean | 'warn' | 'error'`): Audits protected routes that lack built-in FGA metadata. Use true or 'warn' to log a startup warning, 'error' to fail startup, or false to disable. (Default: `false`)
|
|
96
|
+
|
|
97
|
+
**resolveRouteFGA** (`FGARouteResolver`): Derives resource type, resource ID, and permission from the route, parsed params, and request context.
|
|
98
|
+
|
|
99
|
+
**validatePermissions** (`(permissions: MastraFGAPermissionInput[]) => void | Promise<void>`): Startup validation for provider-specific permission mappings. Throw when a permission Mastra may emit is not mapped.
|
|
100
|
+
|
|
101
|
+
## Parameters
|
|
102
|
+
|
|
103
|
+
The `params` argument passed to `check`, `require`, and `requireActor`.
|
|
104
|
+
|
|
105
|
+
**resource** (`{ type: string; id: string }`): The resource being accessed.
|
|
106
|
+
|
|
107
|
+
**permission** (`MastraFGAPermissionInput | MastraFGAPermissionInput[]`): The permission(s) being checked. When an array is provided, the actor needs any one of the listed permissions.
|
|
108
|
+
|
|
109
|
+
**context** (`FGACheckContext`): Provider-specific context for resource resolution, including the owning resourceId, the request context, and action metadata.
|
|
110
|
+
|
|
111
|
+
## `ActorSignal`
|
|
112
|
+
|
|
113
|
+
Identifies a call made by a trusted non-user actor rather than an authenticated end user. It is either `true` (the anonymous system shorthand) or an object that names the acting agent and carries the grants a provider can enforce.
|
|
114
|
+
|
|
115
|
+
**actorKind** (`'system'`): Marks the object form of the signal.
|
|
116
|
+
|
|
117
|
+
**agentId** (`string`): Identity of the acting system agent. Unlike the check resource (the target), this names the actor itself, so a provider can enforce per-agent least privilege.
|
|
118
|
+
|
|
119
|
+
**permissions** (`MastraFGAPermissionInput[]`): Permission grants claimed for this actor. This is an untrusted, self-asserted hint; a provider enforcing real least privilege resolves the agent's authoritative grants from a trusted source keyed by agentId rather than trusting these values.
|
|
120
|
+
|
|
121
|
+
**scope** (`Record<string, string>`): Additional provider-specific scope for the actor, for example tenant or environment.
|
|
122
|
+
|
|
123
|
+
**sourceWorkflow** (`string`): Name of the workflow that started the actor run, when applicable.
|
|
124
|
+
|
|
125
|
+
## `FGADeniedError`
|
|
126
|
+
|
|
127
|
+
Thrown when an authorization check is denied. `require` and `requireActor` throw it to deny, and Mastra surfaces it as an HTTP `403`.
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
import { FGADeniedError } from '@mastra/core/auth/ee'
|
|
131
|
+
|
|
132
|
+
throw new FGADeniedError(user, { type: 'agent', id: 'reporter' }, 'agents:execute')
|
|
133
|
+
// Optional fourth argument: a reason string included in the error message.
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Related
|
|
137
|
+
|
|
138
|
+
- [Fine-grained authorization](https://mastra.ai/docs/server/auth/fga)
|
|
139
|
+
- [System actors](https://mastra.ai/docs/server/auth/fga)
|
|
140
|
+
- [WorkOS authentication](https://mastra.ai/reference/auth/workos)
|
|
@@ -154,8 +154,22 @@ const result = await thread.listMessages({
|
|
|
154
154
|
const result = await thread.listMessages({
|
|
155
155
|
orderBy: { field: 'createdAt', direction: 'ASC' },
|
|
156
156
|
})
|
|
157
|
+
|
|
158
|
+
// Get messages with shallow metadata filters
|
|
159
|
+
const result = await thread.listMessages({
|
|
160
|
+
filter: {
|
|
161
|
+
metadata: {
|
|
162
|
+
category: 'billing',
|
|
163
|
+
escalated: true,
|
|
164
|
+
priority: 2,
|
|
165
|
+
archivedAt: null,
|
|
166
|
+
},
|
|
167
|
+
},
|
|
168
|
+
})
|
|
157
169
|
```
|
|
158
170
|
|
|
171
|
+
Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. Every key-value pair must match with AND semantics. `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the server storage backend, and arbitrary metadata filters may scan candidate messages.
|
|
172
|
+
|
|
159
173
|
### Delete Messages
|
|
160
174
|
|
|
161
175
|
Delete one or more messages from a thread:
|
package/.docs/reference/index.md
CHANGED
|
@@ -49,6 +49,7 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
49
49
|
- [Auth0](https://mastra.ai/reference/auth/auth0)
|
|
50
50
|
- [Better Auth](https://mastra.ai/reference/auth/better-auth)
|
|
51
51
|
- [Clerk](https://mastra.ai/reference/auth/clerk)
|
|
52
|
+
- [Fine-Grained Authorization](https://mastra.ai/reference/auth/fga)
|
|
52
53
|
- [Firebase](https://mastra.ai/reference/auth/firebase)
|
|
53
54
|
- [Google](https://mastra.ai/reference/auth/google)
|
|
54
55
|
- [JSON Web Token](https://mastra.ai/reference/auth/jwt)
|
|
@@ -2,12 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
# Memory.recall()
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The `Memory.recall()` method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.
|
|
6
6
|
|
|
7
7
|
## Usage example
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
|
-
await memory
|
|
10
|
+
const { messages } = await memory.recall({
|
|
11
|
+
threadId: 'thread-123',
|
|
12
|
+
perPage: 20,
|
|
13
|
+
})
|
|
11
14
|
```
|
|
12
15
|
|
|
13
16
|
## Parameters
|
|
@@ -24,7 +27,7 @@ await memory?.recall({ threadId: 'user-123' })
|
|
|
24
27
|
|
|
25
28
|
**include** (`{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]`): Array of specific message IDs to include with optional context messages. Each item has an id (required), optional threadId (defaults to main threadId), withPreviousMessages (number of messages before, defaults to 2 for vector search, 0 otherwise), and withNextMessages (number of messages after, defaults to 2 for vector search, 0 otherwise).
|
|
26
29
|
|
|
27
|
-
**filter** (`{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean } }`): Filter options for message retrieval.
|
|
30
|
+
**filter** (`{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }; metadata?: Record<string, string | number | boolean | null> }`): Filter options for message retrieval. dateRange filters messages by creation date. metadata filters shallow message metadata by exact scalar key-value pairs using AND semantics. Metadata values can be strings, finite numbers, booleans, or null.
|
|
28
31
|
|
|
29
32
|
**orderBy** (`{ field: 'createdAt'; direction: 'ASC' | 'DESC' }`): Sort order for retrieved messages. Defaults to descending by creation date.
|
|
30
33
|
|
|
@@ -38,6 +41,28 @@ await memory?.recall({ threadId: 'user-123' })
|
|
|
38
41
|
|
|
39
42
|
**threadConfig.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): Settings related to memory thread creation. generateTitle controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
|
|
40
43
|
|
|
44
|
+
## Metadata filtering
|
|
45
|
+
|
|
46
|
+
Use `filter.metadata` to match shallow scalar metadata stored on messages:
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
const { messages } = await memory.recall({
|
|
50
|
+
threadId: 'thread-123',
|
|
51
|
+
filter: {
|
|
52
|
+
metadata: {
|
|
53
|
+
category: 'billing',
|
|
54
|
+
escalated: true,
|
|
55
|
+
priority: 2,
|
|
56
|
+
archivedAt: null,
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
})
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
All metadata entries are combined with AND semantics. A message must match every key and value with exact type equality. `null` matches metadata that is explicitly set to `null`; it doesn't match a missing key.
|
|
63
|
+
|
|
64
|
+
Metadata filters only support shallow scalar values: `string`, finite `number`, `boolean`, and `null`. Nested objects, arrays, `NaN`, and infinities are not supported. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the storage backend. Arbitrary metadata filters may require scanning candidate messages, so narrow the query with `threadId`, `resourceId`, or `dateRange` when possible.
|
|
65
|
+
|
|
41
66
|
## Returns
|
|
42
67
|
|
|
43
68
|
**messages** (`MastraDBMessage[]`): Array of retrieved messages in the database format
|
|
@@ -62,6 +62,8 @@ const stream = await agent.stream('message for agent')
|
|
|
62
62
|
|
|
63
63
|
**options.isTaskComplete.timeout** (`number`): Maximum time in milliseconds to wait for all scorers to complete.
|
|
64
64
|
|
|
65
|
+
**options.isTaskComplete.suppressFeedback** (`boolean`): When true, marks the completion check feedback so consumers can hide it from displayed output. Feedback is only added to the conversation when the check fails, to guide the next iteration.
|
|
66
|
+
|
|
65
67
|
**options.delegation** (`DelegationConfig`): Configuration for subagent delegation. Use this to control and monitor when the agent delegates tasks to other agents, including the ability to modify, reject delegations, and provide feedback to guide the supervisor.
|
|
66
68
|
|
|
67
69
|
**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters or reject the delegation entirely.
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.2.10
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`c8d8a01`](https://github.com/mastra-ai/mastra/commit/c8d8a010ee2efe2b7bf4d07707382c34c87b14e4), [`df6a9ce`](https://github.com/mastra-ai/mastra/commit/df6a9ce87214f7aadb2edfe62f67605fe998a0a4), [`73839cb`](https://github.com/mastra-ai/mastra/commit/73839cb58322679c170627d1015669ede5f619aa), [`371cf60`](https://github.com/mastra-ai/mastra/commit/371cf6075cef88ac6919a08d59a82e485397364a), [`8e4dc79`](https://github.com/mastra-ai/mastra/commit/8e4dc793dcf035ea506f9ce79f56d2d501a4be14), [`2db93cc`](https://github.com/mastra-ai/mastra/commit/2db93ccd0b872e4de7853a93383efe0647901df8), [`094ab61`](https://github.com/mastra-ai/mastra/commit/094ab6129a1a3ecf6eeb86decac17d5faea4e02a), [`fe80944`](https://github.com/mastra-ai/mastra/commit/fe80944f3ef6681fea6eae8200fce387b7bb3c2f), [`263d2ca`](https://github.com/mastra-ai/mastra/commit/263d2cac80ba3b03b9c0f008db6f1f1b9eb0278c), [`75f843d`](https://github.com/mastra-ai/mastra/commit/75f843d09f758223e6eeb321321bdcc5c7e779d0), [`e51e166`](https://github.com/mastra-ai/mastra/commit/e51e166c52e220abc9b64554ce37359dca8544b1)]:
|
|
8
|
+
- @mastra/core@1.53.0
|
|
9
|
+
|
|
10
|
+
## 1.2.10-alpha.9
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [[`73839cb`](https://github.com/mastra-ai/mastra/commit/73839cb58322679c170627d1015669ede5f619aa), [`8e4dc79`](https://github.com/mastra-ai/mastra/commit/8e4dc793dcf035ea506f9ce79f56d2d501a4be14), [`2db93cc`](https://github.com/mastra-ai/mastra/commit/2db93ccd0b872e4de7853a93383efe0647901df8), [`094ab61`](https://github.com/mastra-ai/mastra/commit/094ab6129a1a3ecf6eeb86decac17d5faea4e02a), [`fe80944`](https://github.com/mastra-ai/mastra/commit/fe80944f3ef6681fea6eae8200fce387b7bb3c2f), [`e51e166`](https://github.com/mastra-ai/mastra/commit/e51e166c52e220abc9b64554ce37359dca8544b1)]:
|
|
15
|
+
- @mastra/core@1.53.0-alpha.4
|
|
16
|
+
|
|
3
17
|
## 1.2.10-alpha.7
|
|
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.10
|
|
3
|
+
"version": "1.2.10",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"jsdom": "^26.1.0",
|
|
29
29
|
"local-pkg": "^1.1.2",
|
|
30
30
|
"zod": "^4.4.3",
|
|
31
|
-
"@mastra/core": "1.53.0
|
|
31
|
+
"@mastra/core": "1.53.0",
|
|
32
32
|
"@mastra/mcp": "^1.15.0"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
@@ -45,9 +45,9 @@
|
|
|
45
45
|
"tsx": "^4.23.1",
|
|
46
46
|
"typescript": "^6.0.3",
|
|
47
47
|
"vitest": "4.1.10",
|
|
48
|
-
"@internal/
|
|
49
|
-
"@internal/
|
|
50
|
-
"@mastra/core": "1.53.0
|
|
48
|
+
"@internal/types-builder": "0.0.92",
|
|
49
|
+
"@internal/lint": "0.0.117",
|
|
50
|
+
"@mastra/core": "1.53.0"
|
|
51
51
|
},
|
|
52
52
|
"homepage": "https://mastra.ai",
|
|
53
53
|
"repository": {
|