@mastra/mcp-docs-server 1.2.15-alpha.1 → 1.2.15-alpha.6
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/a2a.md +75 -2
- package/.docs/docs/agents/processors.md +2 -0
- package/.docs/docs/agents/skills.md +15 -1
- package/.docs/docs/capabilities/subagents.md +23 -5
- package/.docs/docs/connections/overview.md +94 -0
- package/.docs/docs/datasets/running-experiments.md +18 -0
- package/.docs/docs/evals/overview.md +16 -4
- package/.docs/docs/harness/agent-controller.md +6 -0
- package/.docs/docs/harness/overview.md +26 -0
- package/.docs/docs/index.md +1 -1
- package/.docs/docs/mcp/overview.md +10 -0
- package/.docs/docs/observability/feedback.md +16 -0
- package/.docs/guides/build-your-ui/ai-sdk-ui.md +25 -14
- package/.docs/guides/getting-started/quickstart.md +1 -1
- package/.docs/models/gateways/neon.md +15 -9
- package/.docs/models/gateways/netlify.md +1 -2
- package/.docs/models/gateways/openrouter.md +3 -2
- package/.docs/models/gateways/vercel.md +10 -3
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/cortecs.md +2 -1
- package/.docs/models/providers/deepinfra.md +6 -3
- package/.docs/models/providers/digitalocean.md +4 -3
- package/.docs/models/providers/empiriolabs.md +6 -4
- package/.docs/models/providers/friendli.md +8 -9
- package/.docs/models/providers/huggingface.md +4 -1
- package/.docs/models/providers/hyper.md +5 -6
- package/.docs/models/providers/kilo.md +9 -7
- package/.docs/models/providers/llmgateway.md +3 -3
- package/.docs/models/providers/meta.md +7 -5
- package/.docs/models/providers/nano-gpt.md +7 -4
- package/.docs/models/providers/neuralwatt.md +2 -1
- package/.docs/models/providers/ofox.md +74 -16
- package/.docs/models/providers/opencode-go.md +1 -1
- package/.docs/models/providers/opencode.md +2 -3
- package/.docs/models/providers/upstage.md +3 -2
- package/.docs/models/providers/vivgrid.md +4 -2
- package/.docs/models/providers/wandb.md +1 -1
- package/.docs/reference/agents/channels.md +20 -1
- package/.docs/reference/agents/generate.md +1 -1
- package/.docs/reference/ai-sdk/chat-route.md +2 -0
- package/.docs/reference/client-js/observability.md +22 -0
- package/.docs/reference/client-js/workflows.md +13 -0
- package/.docs/reference/file-based-agents/config.md +22 -21
- package/.docs/reference/file-based-agents/instructions.md +42 -17
- package/.docs/reference/index.md +1 -0
- package/.docs/reference/observability/metrics/automatic-metrics.md +10 -8
- package/.docs/reference/server/routes.md +25 -11
- package/.docs/reference/storage/composite.md +58 -0
- package/.docs/reference/streaming/agents/stream.md +1 -1
- package/.docs/reference/tools/bedrock-kb-tool.md +117 -0
- package/.docs/reference/tools/mcp-client.md +54 -0
- package/.docs/reference/voice/google.md +19 -3
- package/.docs/reference/workflows/step.md +40 -0
- package/.docs/reference/workspace/workspace-class.md +2 -0
- package/CHANGELOG.md +23 -0
- package/package.json +7 -7
|
@@ -251,6 +251,64 @@ const memoryStore = await storage.getStore('memory')
|
|
|
251
251
|
const thread = await memoryStore?.getThreadById({ threadId: '...' })
|
|
252
252
|
```
|
|
253
253
|
|
|
254
|
+
## Closing connections
|
|
255
|
+
|
|
256
|
+
`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
import { MastraCompositeStore } from '@mastra/core/storage'
|
|
260
|
+
import { PostgresStore } from '@mastra/pg'
|
|
261
|
+
import { Mastra } from '@mastra/core'
|
|
262
|
+
|
|
263
|
+
const pgStore = new PostgresStore({
|
|
264
|
+
id: 'pg-storage',
|
|
265
|
+
connectionString: process.env.DATABASE_URL,
|
|
266
|
+
})
|
|
267
|
+
|
|
268
|
+
export const mastra = new Mastra({
|
|
269
|
+
storage: new MastraCompositeStore({ id: 'composite', default: pgStore }),
|
|
270
|
+
})
|
|
271
|
+
|
|
272
|
+
process.on('SIGTERM', async () => {
|
|
273
|
+
// Releases the Postgres pool, so the process can exit
|
|
274
|
+
await mastra.shutdown()
|
|
275
|
+
})
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
A store you construct only to supply a domain isn't reachable through the composite. Keep a reference to it and close it yourself:
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
import { MastraCompositeStore } from '@mastra/core/storage'
|
|
282
|
+
import { ClickhouseStore } from '@mastra/clickhouse'
|
|
283
|
+
import { PostgresStore } from '@mastra/pg'
|
|
284
|
+
import { Mastra } from '@mastra/core'
|
|
285
|
+
|
|
286
|
+
const pgStore = new PostgresStore({
|
|
287
|
+
id: 'pg-storage',
|
|
288
|
+
connectionString: process.env.DATABASE_URL,
|
|
289
|
+
})
|
|
290
|
+
|
|
291
|
+
const clickhouseStore = new ClickhouseStore({
|
|
292
|
+
id: 'clickhouse-storage',
|
|
293
|
+
url: process.env.CLICKHOUSE_URL,
|
|
294
|
+
username: process.env.CLICKHOUSE_USERNAME,
|
|
295
|
+
password: process.env.CLICKHOUSE_PASSWORD,
|
|
296
|
+
})
|
|
297
|
+
|
|
298
|
+
export const mastra = new Mastra({
|
|
299
|
+
storage: new MastraCompositeStore({
|
|
300
|
+
id: 'composite',
|
|
301
|
+
default: pgStore,
|
|
302
|
+
domains: { observability: clickhouseStore.stores?.observability },
|
|
303
|
+
}),
|
|
304
|
+
})
|
|
305
|
+
|
|
306
|
+
process.on('SIGTERM', async () => {
|
|
307
|
+
await mastra.shutdown()
|
|
308
|
+
await clickhouseStore.close()
|
|
309
|
+
})
|
|
310
|
+
```
|
|
311
|
+
|
|
254
312
|
## Use cases
|
|
255
313
|
|
|
256
314
|
### Separate databases for different workloads
|
|
@@ -66,7 +66,7 @@ const stream = await agent.stream('message for agent')
|
|
|
66
66
|
|
|
67
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.
|
|
68
68
|
|
|
69
|
-
**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters
|
|
69
|
+
**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters, reject the delegation entirely, or mutate context.requestContext to add entries to the subagent run's request context.
|
|
70
70
|
|
|
71
71
|
**options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): Called after a subagent delegation completes. The context includes a bail() method to stop further execution, and you can return { feedback } to guide the supervisor's next action. Feedback is saved to supervisor memory as an assistant message.
|
|
72
72
|
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# createBedrockKBTool()
|
|
4
|
+
|
|
5
|
+
The `createBedrockKBTool()` function creates a tool that retrieves relevant documents from an Amazon Bedrock Knowledge Base. It supports both managed search configuration and agentic retrieval (query decomposition and managed reranking) with automatic fallback to standard retrieval.
|
|
6
|
+
|
|
7
|
+
## Usage example
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { createBedrockKBTool } from '@mastra/rag'
|
|
11
|
+
|
|
12
|
+
const kbTool = createBedrockKBTool({
|
|
13
|
+
knowledgeBaseId: 'YOUR_KB_ID',
|
|
14
|
+
region: 'us-west-2',
|
|
15
|
+
numberOfResults: 5,
|
|
16
|
+
useAgenticRetrieval: true,
|
|
17
|
+
})
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### With an Agent
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { Agent } from '@mastra/core/agent'
|
|
24
|
+
import { createBedrockKBTool } from '@mastra/rag'
|
|
25
|
+
|
|
26
|
+
const kbTool = createBedrockKBTool({
|
|
27
|
+
knowledgeBaseId: 'YOUR_KB_ID',
|
|
28
|
+
})
|
|
29
|
+
|
|
30
|
+
const agent = new Agent({
|
|
31
|
+
name: 'KnowledgeAssistant',
|
|
32
|
+
instructions: 'Use the knowledge base tool to answer questions.',
|
|
33
|
+
model: myModel,
|
|
34
|
+
tools: { kb: kbTool },
|
|
35
|
+
})
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Parameters
|
|
39
|
+
|
|
40
|
+
**knowledgeBaseId** (`string`): The ID of the Amazon Bedrock Knowledge Base to query.
|
|
41
|
+
|
|
42
|
+
**region** (`string`): AWS region where the Knowledge Base is deployed. Defaults to AWS\_REGION environment variable or us-east-1.
|
|
43
|
+
|
|
44
|
+
**numberOfResults** (`number`): Maximum number of results to return. Defaults to 5.
|
|
45
|
+
|
|
46
|
+
**useAgenticRetrieval** (`boolean`): Use AgenticRetrieveStream for complex queries with query decomposition and managed reranking. Falls back to standard Retrieve on failure. Defaults to true (disable with USE\_AGENTIC\_RETRIEVAL=false env var).
|
|
47
|
+
|
|
48
|
+
**userId** (`string`): Default AWS user ID for document-level access control. A userId in the Mastra request context takes precedence.
|
|
49
|
+
|
|
50
|
+
## Input Schema
|
|
51
|
+
|
|
52
|
+
The tool accepts the following input when called by an agent:
|
|
53
|
+
|
|
54
|
+
**queryText** (`string`): The search query to find relevant documents in the knowledge base.
|
|
55
|
+
|
|
56
|
+
## Output Schema
|
|
57
|
+
|
|
58
|
+
The tool returns an object with:
|
|
59
|
+
|
|
60
|
+
**results** (`BedrockKBResult[]`): Array of retrieval results. Standard retrieval includes source and score when Bedrock provides them; agentic retrieval may omit those fields.
|
|
61
|
+
|
|
62
|
+
### BedrockKBResult
|
|
63
|
+
|
|
64
|
+
| Field | Type | Description |
|
|
65
|
+
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
66
|
+
| `content` | `string` | The text content of the retrieved passage. |
|
|
67
|
+
| `source` | `string \| undefined` | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
|
|
68
|
+
| `score` | `number \| undefined` | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items. |
|
|
69
|
+
| `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result. |
|
|
70
|
+
|
|
71
|
+
## Retrieval Modes
|
|
72
|
+
|
|
73
|
+
### Agentic Retrieval (default)
|
|
74
|
+
|
|
75
|
+
When `useAgenticRetrieval` is `true` (default), the tool uses `AgenticRetrieveStreamCommand` which:
|
|
76
|
+
|
|
77
|
+
- Decomposes complex queries into sub-queries
|
|
78
|
+
- Retrieves across multiple passes
|
|
79
|
+
- Applies managed reranking for better results
|
|
80
|
+
|
|
81
|
+
If agentic retrieval fails (e.g., older SDK, permissions), it automatically falls back to standard managed retrieval.
|
|
82
|
+
|
|
83
|
+
### Standard Managed Retrieval
|
|
84
|
+
|
|
85
|
+
When `useAgenticRetrieval` is `false`, the tool uses `RetrieveCommand` with `managedSearchConfiguration` for direct single-pass retrieval.
|
|
86
|
+
|
|
87
|
+
## User-based access control
|
|
88
|
+
|
|
89
|
+
Set `userId` in the Mastra request context to forward it as the Bedrock `userContext.userId`. This supports knowledge bases that enforce document-level access control. The request context value overrides the default `userId` configured on the tool.
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
import { RequestContext } from '@mastra/core/request-context'
|
|
93
|
+
|
|
94
|
+
const requestContext = new RequestContext()
|
|
95
|
+
requestContext.set('userId', 'user-123')
|
|
96
|
+
|
|
97
|
+
await agent.generate('Find my private documents', { requestContext })
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Required IAM Permissions
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"Version": "2012-10-17",
|
|
105
|
+
"Statement": [
|
|
106
|
+
{
|
|
107
|
+
"Effect": "Allow",
|
|
108
|
+
"Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
|
|
109
|
+
"Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
|
|
110
|
+
}
|
|
111
|
+
]
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## SDK Requirements
|
|
116
|
+
|
|
117
|
+
- `@aws-sdk/client-bedrock-agent-runtime` >= 3.1000 (AgenticRetrieveStreamCommand requires \~3.1000+)
|
|
@@ -37,6 +37,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
|
|
|
37
37
|
|
|
38
38
|
**env** (`Record<string, string>`): For Stdio servers: Environment variables to set for the command.
|
|
39
39
|
|
|
40
|
+
**inheritDefaultEnv** (`boolean`): For Stdio servers: Whether the subprocess environment starts from the MCP SDK's default inherited environment. The default is a curated whitelist, not the full process environment: on POSIX it inherits HOME, LOGNAME, PATH, SHELL, TERM, and USER; on Windows it inherits APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR\_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, and USERPROFILE. When set to false, only the variables explicitly listed in env are passed to the subprocess. Note that a subprocess without PATH may fail to spawn commands that are not absolute paths. (Default: `true`)
|
|
41
|
+
|
|
40
42
|
**url** (`URL`): For HTTP servers (Streamable HTTP or SSE): The URL of the server.
|
|
41
43
|
|
|
42
44
|
**requestInit** (`RequestInit`): For HTTP servers: Request configuration for the fetch API.
|
|
@@ -45,6 +47,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
|
|
|
45
47
|
|
|
46
48
|
**fetch** (`MastraFetchLike`): For HTTP servers: Custom fetch implementation used for all network requests. Receives an optional third requestContext parameter containing request-scoped data (e.g., authentication cookies, bearer tokens) from the incoming request. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers, forward request-scoped credentials to the MCP server, customize request behavior per-request, or intercept and modify requests/responses. When fetch is provided, requestInit, eventSourceInit, and authProvider become optional, as you can handle these concerns within your custom fetch function.
|
|
47
49
|
|
|
50
|
+
**allowedHosts** (`string[]`): For HTTP servers: Opt-in allowlist of hosts the client may contact on behalf of this server. Each entry is matched against the URL host (hostname plus port when the URL carries a non-default port), for example "api.example.com" or "localhost:8080". Matching is exact and case-insensitive on the hostname; wildcards are not supported and the URL scheme is not checked. An empty array denies all requests. When unset, no restriction is applied. See the Security section below for enforcement details.
|
|
51
|
+
|
|
48
52
|
**logger** (`LogHandler`): Optional additional handler for logging.
|
|
49
53
|
|
|
50
54
|
**timeout** (`number`): Server-specific timeout in milliseconds.
|
|
@@ -159,6 +163,56 @@ When `forwardInstructions` is omitted (the default), instructions are still cach
|
|
|
159
163
|
|
|
160
164
|
> **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
|
|
161
165
|
|
|
166
|
+
## Security
|
|
167
|
+
|
|
168
|
+
### Subprocess environment for Stdio servers
|
|
169
|
+
|
|
170
|
+
Stdio subprocesses don't inherit the full parent process environment. By default the subprocess environment starts from the MCP SDK's curated whitelist (POSIX: `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, `USER`; Windows: `APPDATA`, `HOMEDRIVE`, `HOMEPATH`, `LOCALAPPDATA`, `PATH`, `PROCESSOR_ARCHITECTURE`, `SYSTEMDRIVE`, `SYSTEMROOT`, `TEMP`, `USERNAME`, `USERPROFILE`), merged with any variables you set in `env`. Sensitive variables such as API keys aren't inherited unless you pass them explicitly.
|
|
171
|
+
|
|
172
|
+
For stricter isolation, set `inheritDefaultEnv: false` so only your configured `env` entries reach the subprocess:
|
|
173
|
+
|
|
174
|
+
```typescript
|
|
175
|
+
const mcp = new MCPClient({
|
|
176
|
+
servers: {
|
|
177
|
+
myTool: {
|
|
178
|
+
command: '/usr/local/bin/my-mcp-server',
|
|
179
|
+
inheritDefaultEnv: false,
|
|
180
|
+
env: { MY_TOOL_API_KEY: process.env.MY_TOOL_API_KEY! },
|
|
181
|
+
},
|
|
182
|
+
},
|
|
183
|
+
})
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Variables you place in `env` are forwarded verbatim, so treat server configurations that come from untrusted sources (for example, user-supplied config files) as untrusted input.
|
|
187
|
+
|
|
188
|
+
### Restricting outbound hosts with `allowedHosts`
|
|
189
|
+
|
|
190
|
+
When HTTP server URLs come from untrusted configuration, an attacker-controlled URL can point the client at internal services (server-side request forgery). Set `allowedHosts` on such servers to restrict which hosts the client will contact:
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
const mcp = new MCPClient({
|
|
194
|
+
servers: {
|
|
195
|
+
remote: {
|
|
196
|
+
url: new URL(untrustedConfig.serverUrl),
|
|
197
|
+
allowedHosts: ['api.example.com'],
|
|
198
|
+
},
|
|
199
|
+
},
|
|
200
|
+
})
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Enforcement details:
|
|
204
|
+
|
|
205
|
+
- On the default fetch path, requests to disallowed hosts, including every redirect hop, are blocked **before** they're sent. Redirects are followed manually (up to 5 hops) so each hop is validated, and the `Authorization` header isn't carried across hops to a different origin (any scheme, host, or port change drops it, matching standard fetch behavior).
|
|
206
|
+
- When you supply a custom `fetch` (or a custom `eventSourceInit.fetch`), the initial URL is still checked before the request, but redirect hops are validated **after the fact** using `response.url`: the outbound hop may occur, and the response is discarded when its final URL points at a disallowed host. A hand-built `Response` with an empty `response.url` skips this post-hoc check.
|
|
207
|
+
- OAuth requests made through `authProvider` (authorization server metadata discovery, token exchange, refresh) are also validated. If your authorization server runs on a different host than the MCP server, add that host to `allowedHosts` too.
|
|
208
|
+
- A blocked host fails the connection with a clear error and is never retried by the reconnect logic.
|
|
209
|
+
|
|
210
|
+
`allowedHosts` is intentionally minimal: it matches exact hosts and doesn't support wildcards or scheme checks. If you need richer policy (scheme checks, IP-range rules), supply a custom `fetch` implementation, which is invoked for every request the client makes.
|
|
211
|
+
|
|
212
|
+
### Treat tool responses as untrusted input
|
|
213
|
+
|
|
214
|
+
Tool results returned by MCP servers flow into your agent's context as model input. A malicious or compromised server can use tool output for prompt injection. The transport client doesn't sanitize tool responses: sanitization policy belongs at the agent layer, where Mastra's [input and output processors](https://mastra.ai/docs/agents/processors) let you inspect, transform, or block content before and after it reaches the model. Combine this with `requireToolApproval` and the `forwardInstructions` security note above when working with third-party servers.
|
|
215
|
+
|
|
162
216
|
## Methods
|
|
163
217
|
|
|
164
218
|
### `listTools()`
|
|
@@ -109,7 +109,17 @@ Converts speech to text using Google Cloud Speech-to-Text service. Supports both
|
|
|
109
109
|
|
|
110
110
|
Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
|
|
111
111
|
|
|
112
|
+
The v2 `recognize` call is IAM-authorized and does not accept API-key-only authentication. Configure service account credentials on the `listeningModel` (or set `GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` so the recognizer path can be resolved, even when `vertexAI` is not enabled.
|
|
113
|
+
|
|
112
114
|
```typescript
|
|
115
|
+
import { GoogleVoice } from '@mastra/voice-google'
|
|
116
|
+
|
|
117
|
+
// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
|
|
118
|
+
// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
|
|
119
|
+
const voice = new GoogleVoice({
|
|
120
|
+
listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
|
|
121
|
+
})
|
|
122
|
+
|
|
113
123
|
const transcript = await voice.listen(iosSafariAacStream, {
|
|
114
124
|
v2: true,
|
|
115
125
|
config: {
|
|
@@ -118,6 +128,8 @@ const transcript = await voice.listen(iosSafariAacStream, {
|
|
|
118
128
|
})
|
|
119
129
|
```
|
|
120
130
|
|
|
131
|
+
> **Note:** `listen({ v2: true })` fails with `PERMISSION_DENIED` on `speech.recognizers.recognize` when only `GOOGLE_API_KEY` is set. An API-key request carries no OAuth identity, so granting `roles/speech.client` to a user account does not help — the role must be granted to the service account presented in the request. This applies regardless of the `vertexAI` setting; `speak()` and v1 `listen()` still work with an API key alone.
|
|
132
|
+
|
|
121
133
|
**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
|
|
122
134
|
|
|
123
135
|
**options** (`GoogleListenOptionsV2`): v2 recognition options
|
|
@@ -162,7 +174,7 @@ The Google Voice provider supports two authentication methods:
|
|
|
162
174
|
|
|
163
175
|
### Standard Mode (API Key)
|
|
164
176
|
|
|
165
|
-
Uses a Google Cloud API key for authentication.
|
|
177
|
+
Uses a Google Cloud API key for authentication. Covers `speak()` and v1 `listen()`. It does not cover `listen({ v2: true })`, which is IAM-authorized and requires service account credentials (see [v2](#v2)).
|
|
166
178
|
|
|
167
179
|
```typescript
|
|
168
180
|
// Using environment variable (GOOGLE_API_KEY)
|
|
@@ -238,6 +250,8 @@ For Speech-to-Text:
|
|
|
238
250
|
|
|
239
251
|
- `roles/speech.client` - Speech-to-Text Client
|
|
240
252
|
|
|
253
|
+
Grant `roles/speech.client` to the service account whose credentials the request presents (via `keyFilename`, `credentials`, or `GOOGLE_APPLICATION_CREDENTIALS`). This role is required for `listen({ v2: true })` specifically, not only for Vertex AI mode. Granting it to a user account has no effect on API-key-only requests, which carry no identity to authorize.
|
|
254
|
+
|
|
241
255
|
#### OAuth Scopes
|
|
242
256
|
|
|
243
257
|
For synchronous Text-to-Speech synthesis:
|
|
@@ -269,6 +283,8 @@ For long-audio Text-to-Speech operations:
|
|
|
269
283
|
|
|
270
284
|
6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
|
|
271
285
|
|
|
272
|
-
7.
|
|
286
|
+
7. `listen({ v2: true })` requires service account credentials and `GOOGLE_CLOUD_PROJECT`; it fails with `PERMISSION_DENIED` when only `GOOGLE_API_KEY` is set. `speak()` and v1 `listen()` work with an API key alone.
|
|
287
|
+
|
|
288
|
+
8. Available voices can be filtered by language code using the `getSpeakers()` method.
|
|
273
289
|
|
|
274
|
-
|
|
290
|
+
9. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.
|
|
@@ -191,8 +191,48 @@ const agentStep = createStep(testAgent, {
|
|
|
191
191
|
|
|
192
192
|
**execute.retryCount** (`number`): The retry count for this specific step, it automatically increases each time the step is retried
|
|
193
193
|
|
|
194
|
+
**scorers** (`MastraScorers | (({ requestContext }) => MastraScorers | Promise<MastraScorers>)`): Scorers that run automatically after the step completes successfully. Each scorer evaluates the step's own input and output, and the results are stored and attached to the step's trace. Provide a map of { \[name]: { scorer, sampling? } }, or a function that returns one. Scoring runs asynchronously and doesn't block the workflow. See Scoring step output.
|
|
195
|
+
|
|
196
|
+
**retries** (`number`): Number of times to retry the step's execute function if it throws.
|
|
197
|
+
|
|
194
198
|
**metadata** (`Record<string, any>`): Optional key-value pairs for storing additional step information. Values must be serializable (no functions, circular references, etc.).
|
|
195
199
|
|
|
200
|
+
## Scoring step output
|
|
201
|
+
|
|
202
|
+
Attach `scorers` to a step to evaluate that step's output automatically, at the point it runs, instead of only scoring the workflow's final answer. This is useful for multi-step and RAG workflows, where you want to see which step degraded quality, for example whether a retrieval step returned relevant chunks before later steps reason over them.
|
|
203
|
+
|
|
204
|
+
Each scorer receives the step's own `input` and `output`. Scoring runs asynchronously after the step succeeds, and the result is stored against the step's trace. Use `sampling` to control how often a scorer runs.
|
|
205
|
+
|
|
206
|
+
The following example attaches a scorer to a retrieval step so every execution is scored:
|
|
207
|
+
|
|
208
|
+
```typescript
|
|
209
|
+
import { createStep } from '@mastra/core/workflows'
|
|
210
|
+
import { z } from 'zod'
|
|
211
|
+
import { retrievalRelevanceScorer } from '../scorers/retrieval-relevance'
|
|
212
|
+
|
|
213
|
+
const retrievalStep = createStep({
|
|
214
|
+
id: 'retrieval',
|
|
215
|
+
inputSchema: z.object({ query: z.string() }),
|
|
216
|
+
outputSchema: z.object({ query: z.string(), chunks: z.array(z.string()) }),
|
|
217
|
+
scorers: {
|
|
218
|
+
retrievalRelevance: {
|
|
219
|
+
scorer: retrievalRelevanceScorer(),
|
|
220
|
+
sampling: { type: 'ratio', rate: 1 },
|
|
221
|
+
},
|
|
222
|
+
},
|
|
223
|
+
execute: async ({ inputData }) => {
|
|
224
|
+
const chunks = await retrieve(inputData.query)
|
|
225
|
+
return { query: inputData.query, chunks }
|
|
226
|
+
},
|
|
227
|
+
})
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Attach a scorer to each step you want to measure to build per-step scores across a multi-step workflow. Because scoring is scoped to a single step, you don't need a dedicated cross-step metric to see where quality changes.
|
|
231
|
+
|
|
232
|
+
Agent and tool steps added with [`Workflow.agent()`](https://mastra.ai/reference/workflows/workflow-methods/agent) and [`Workflow.tool()`](https://mastra.ai/reference/workflows/workflow-methods/tool) accept the same `scorers` option in their step options.
|
|
233
|
+
|
|
234
|
+
> **Note:** Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) to learn how live evaluations run and where results are stored, and [Custom scorers](https://mastra.ai/docs/evals/custom-scorers) to build your own.
|
|
235
|
+
|
|
196
236
|
## Related
|
|
197
237
|
|
|
198
238
|
- [Workflow state](https://mastra.ai/docs/workflows/workflow-state)
|
|
@@ -67,6 +67,8 @@ const workspace = new Workspace({
|
|
|
67
67
|
|
|
68
68
|
**tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken.
|
|
69
69
|
|
|
70
|
+
**tools.writeLockTimeoutMs** (`number`): Maximum time in milliseconds a write tool waits to acquire the per-file write lock before failing. Raise this for slow or cold-starting filesystems (e.g. remote sandboxes).
|
|
71
|
+
|
|
70
72
|
**tools.hooks** (`WorkspaceToolHooks`): Hooks that run before and after every enabled workspace tool call. See Tool hooks below.
|
|
71
73
|
|
|
72
74
|
**operationTimeout** (`number`): Timeout for operations in milliseconds
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,28 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.2.15-alpha.6
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`d7cf7fa`](https://github.com/mastra-ai/mastra/commit/d7cf7fafc1ae1b50bd8462dd0e6c671a8606db93), [`0f9a448`](https://github.com/mastra-ai/mastra/commit/0f9a448502157e59f7b76f24360ad497168f5ef8), [`289f4ce`](https://github.com/mastra-ai/mastra/commit/289f4ce16e3293370440172132c52ee787cbc09f), [`4f16ff8`](https://github.com/mastra-ai/mastra/commit/4f16ff824bf2f9b0ddc93f210477c10c8a4fb1ab), [`1c67d85`](https://github.com/mastra-ai/mastra/commit/1c67d85e9da8285662f4dbbf47e0378c3fee0747), [`ba24be6`](https://github.com/mastra-ai/mastra/commit/ba24be662439c331ab23a600041f93803c89eca8), [`842b5fe`](https://github.com/mastra-ai/mastra/commit/842b5fe22b6a7fa811bd14e48eb9af523ac989f2), [`80bdf3a`](https://github.com/mastra-ai/mastra/commit/80bdf3ae16ade6ff63bde0cb16fa2df8ab7dd4dd), [`9ba1247`](https://github.com/mastra-ai/mastra/commit/9ba12470c77f1c03642d720ce67e517e878f666e), [`fd96298`](https://github.com/mastra-ai/mastra/commit/fd96298a8367622f4ebfcaa97b5b6c1fbbd14564), [`6a84954`](https://github.com/mastra-ai/mastra/commit/6a84954a2667f85b6d59da652dab1bbff007ccb0), [`52d8ef0`](https://github.com/mastra-ai/mastra/commit/52d8ef03801f1deb7ee48532fc4190dd4a33916c), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`289f4ce`](https://github.com/mastra-ai/mastra/commit/289f4ce16e3293370440172132c52ee787cbc09f), [`efd5c81`](https://github.com/mastra-ai/mastra/commit/efd5c81cc25fde3c2ddd86fc1178deb4ec176e19), [`0976933`](https://github.com/mastra-ai/mastra/commit/0976933142333ec78451feef265b68bcb45aa5e7), [`242b945`](https://github.com/mastra-ai/mastra/commit/242b94558777bfbdeb42cbfea84afff0b6ad0633), [`fea5cae`](https://github.com/mastra-ai/mastra/commit/fea5caedc7e2cfea51784a15e015952692027abf), [`4b59f78`](https://github.com/mastra-ai/mastra/commit/4b59f786cbc9a7d1ef07a07517dbd4b96865e99d), [`9ba1247`](https://github.com/mastra-ai/mastra/commit/9ba12470c77f1c03642d720ce67e517e878f666e), [`7010c5d`](https://github.com/mastra-ai/mastra/commit/7010c5d15728bf9c5dfe4fb6b1bf80ce23bf143a)]:
|
|
8
|
+
- @mastra/core@1.58.0-alpha.3
|
|
9
|
+
- @mastra/mcp@1.16.0-alpha.1
|
|
10
|
+
|
|
11
|
+
## 1.2.15-alpha.4
|
|
12
|
+
|
|
13
|
+
### Patch Changes
|
|
14
|
+
|
|
15
|
+
- Updated dependencies [[`b4c89b4`](https://github.com/mastra-ai/mastra/commit/b4c89b4371b0c86da57403ad1a3b3ef0681f3128), [`e44e8f3`](https://github.com/mastra-ai/mastra/commit/e44e8f370b66c339ddcaba946d33da6d3c3f06cd), [`c967a5e`](https://github.com/mastra-ai/mastra/commit/c967a5eec150c5dc5418c4a4388982d1fb7ad27c), [`f53d5bd`](https://github.com/mastra-ai/mastra/commit/f53d5bd4885b29e4ac29a428a6044088ea8d6aa3), [`bda2235`](https://github.com/mastra-ai/mastra/commit/bda22353ee28f2df0eaea555f7cae1549f979c0b), [`a7eb4a1`](https://github.com/mastra-ai/mastra/commit/a7eb4a11450f6170274ed5141bffe821d4fdd5a6), [`2f9ef3f`](https://github.com/mastra-ai/mastra/commit/2f9ef3f4ca06fc2dcdd5088c26b7f4da6a016791), [`e7eefcb`](https://github.com/mastra-ai/mastra/commit/e7eefcb162cda7c493e8c3bf43050ead0efbcb2c), [`4d7aca2`](https://github.com/mastra-ai/mastra/commit/4d7aca2fe75f225c83d1502d63079568e6ec163f), [`c4ec889`](https://github.com/mastra-ai/mastra/commit/c4ec889561c0264c43f66d04d587bee4ce35e792), [`9be8878`](https://github.com/mastra-ai/mastra/commit/9be8878dcf0388e84fc4873e0eec27bd49b881a4)]:
|
|
16
|
+
- @mastra/core@1.58.0-alpha.2
|
|
17
|
+
|
|
18
|
+
## 1.2.15-alpha.2
|
|
19
|
+
|
|
20
|
+
### Patch Changes
|
|
21
|
+
|
|
22
|
+
- Updated dependencies [[`e7109ee`](https://github.com/mastra-ai/mastra/commit/e7109ee6f731bacc79c885906f3c7dca8d8f013a), [`772c0c8`](https://github.com/mastra-ai/mastra/commit/772c0c897cec383258de2e6178147f8014767c7b), [`578bf2e`](https://github.com/mastra-ai/mastra/commit/578bf2e6a88e9d5b8bf502204e15a95dfbb679ae), [`06b2d87`](https://github.com/mastra-ai/mastra/commit/06b2d87e63bcdd0ed59215c6789692b9b12de376), [`ac01d63`](https://github.com/mastra-ai/mastra/commit/ac01d6355974aec73fdb8781449ed12bac582094), [`a810a05`](https://github.com/mastra-ai/mastra/commit/a810a058f62ad407cfc1701e0be36ae91145d7cf), [`f8da216`](https://github.com/mastra-ai/mastra/commit/f8da21633e7eb0e31c9ce0fc30567870d19416d3), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`c71e307`](https://github.com/mastra-ai/mastra/commit/c71e3077e69eae3f25aa628e3778f153a9d6ab36), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`6104347`](https://github.com/mastra-ai/mastra/commit/61043473ba6bfd0a25156824e853e13165562e6c), [`45bfb88`](https://github.com/mastra-ai/mastra/commit/45bfb88fd52f1dd3be20e2a38905777c96499c90), [`e3b9307`](https://github.com/mastra-ai/mastra/commit/e3b9307098daefbfae2a52ae2ef51bc9fc701190), [`d6834c5`](https://github.com/mastra-ai/mastra/commit/d6834c5a7866b16734d23900163c2414ed70d791), [`c52d346`](https://github.com/mastra-ai/mastra/commit/c52d3462ec831a5d95926ecd3d3373f5928ad2e5), [`0023e79`](https://github.com/mastra-ai/mastra/commit/0023e7919431078280abd11c89d1edeae35fcc69), [`c2ad51e`](https://github.com/mastra-ai/mastra/commit/c2ad51e2467f901eecba8c9f4a45e22a50bd7c18), [`3dc97ea`](https://github.com/mastra-ai/mastra/commit/3dc97ea415fad353b48a13095fad1835933cc12a), [`3d01cd3`](https://github.com/mastra-ai/mastra/commit/3d01cd387321b6f9c5cac31d487c84bf51b19c78), [`7bf3086`](https://github.com/mastra-ai/mastra/commit/7bf308663f0115ca74ad20554ade740f06640859), [`a8dd139`](https://github.com/mastra-ai/mastra/commit/a8dd1391a9fe9a6632c25809ef236980afa9a020), [`e5786be`](https://github.com/mastra-ai/mastra/commit/e5786be02bb903073082bd9d6da880ebaacc343f), [`2093fbd`](https://github.com/mastra-ai/mastra/commit/2093fbd53bb744bae19ec89f6d73db9a66fbe8a7), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`7b4393d`](https://github.com/mastra-ai/mastra/commit/7b4393d557411fdcf07b0e30e5acaf7cc85154ae)]:
|
|
23
|
+
- @mastra/core@1.58.0-alpha.1
|
|
24
|
+
- @mastra/mcp@1.16.0-alpha.0
|
|
25
|
+
|
|
3
26
|
## 1.2.15-alpha.0
|
|
4
27
|
|
|
5
28
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.15-alpha.
|
|
3
|
+
"version": "1.2.15-alpha.6",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -28,11 +28,11 @@
|
|
|
28
28
|
"jsdom": "^26.1.0",
|
|
29
29
|
"local-pkg": "^1.1.2",
|
|
30
30
|
"zod": "^4.4.3",
|
|
31
|
-
"@mastra/mcp": "^1.
|
|
32
|
-
"@mastra/core": "1.58.0-alpha.
|
|
31
|
+
"@mastra/mcp": "^1.16.0-alpha.1",
|
|
32
|
+
"@mastra/core": "1.58.0-alpha.3"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
|
-
"@hono/node-server": "^
|
|
35
|
+
"@hono/node-server": "^2.0.0",
|
|
36
36
|
"@types/jsdom": "^21.1.7",
|
|
37
37
|
"@types/node": "22.20.1",
|
|
38
38
|
"@vitest/coverage-v8": "4.1.10",
|
|
@@ -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
|
-
"@mastra/core": "1.58.0-alpha.
|
|
50
|
-
"@internal/
|
|
48
|
+
"@internal/lint": "0.0.121",
|
|
49
|
+
"@mastra/core": "1.58.0-alpha.3",
|
|
50
|
+
"@internal/types-builder": "0.0.96"
|
|
51
51
|
},
|
|
52
52
|
"homepage": "https://mastra.ai",
|
|
53
53
|
"repository": {
|