@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.
Files changed (56) hide show
  1. package/.docs/docs/agents/a2a.md +75 -2
  2. package/.docs/docs/agents/processors.md +2 -0
  3. package/.docs/docs/agents/skills.md +15 -1
  4. package/.docs/docs/capabilities/subagents.md +23 -5
  5. package/.docs/docs/connections/overview.md +94 -0
  6. package/.docs/docs/datasets/running-experiments.md +18 -0
  7. package/.docs/docs/evals/overview.md +16 -4
  8. package/.docs/docs/harness/agent-controller.md +6 -0
  9. package/.docs/docs/harness/overview.md +26 -0
  10. package/.docs/docs/index.md +1 -1
  11. package/.docs/docs/mcp/overview.md +10 -0
  12. package/.docs/docs/observability/feedback.md +16 -0
  13. package/.docs/guides/build-your-ui/ai-sdk-ui.md +25 -14
  14. package/.docs/guides/getting-started/quickstart.md +1 -1
  15. package/.docs/models/gateways/neon.md +15 -9
  16. package/.docs/models/gateways/netlify.md +1 -2
  17. package/.docs/models/gateways/openrouter.md +3 -2
  18. package/.docs/models/gateways/vercel.md +10 -3
  19. package/.docs/models/index.md +1 -1
  20. package/.docs/models/providers/cortecs.md +2 -1
  21. package/.docs/models/providers/deepinfra.md +6 -3
  22. package/.docs/models/providers/digitalocean.md +4 -3
  23. package/.docs/models/providers/empiriolabs.md +6 -4
  24. package/.docs/models/providers/friendli.md +8 -9
  25. package/.docs/models/providers/huggingface.md +4 -1
  26. package/.docs/models/providers/hyper.md +5 -6
  27. package/.docs/models/providers/kilo.md +9 -7
  28. package/.docs/models/providers/llmgateway.md +3 -3
  29. package/.docs/models/providers/meta.md +7 -5
  30. package/.docs/models/providers/nano-gpt.md +7 -4
  31. package/.docs/models/providers/neuralwatt.md +2 -1
  32. package/.docs/models/providers/ofox.md +74 -16
  33. package/.docs/models/providers/opencode-go.md +1 -1
  34. package/.docs/models/providers/opencode.md +2 -3
  35. package/.docs/models/providers/upstage.md +3 -2
  36. package/.docs/models/providers/vivgrid.md +4 -2
  37. package/.docs/models/providers/wandb.md +1 -1
  38. package/.docs/reference/agents/channels.md +20 -1
  39. package/.docs/reference/agents/generate.md +1 -1
  40. package/.docs/reference/ai-sdk/chat-route.md +2 -0
  41. package/.docs/reference/client-js/observability.md +22 -0
  42. package/.docs/reference/client-js/workflows.md +13 -0
  43. package/.docs/reference/file-based-agents/config.md +22 -21
  44. package/.docs/reference/file-based-agents/instructions.md +42 -17
  45. package/.docs/reference/index.md +1 -0
  46. package/.docs/reference/observability/metrics/automatic-metrics.md +10 -8
  47. package/.docs/reference/server/routes.md +25 -11
  48. package/.docs/reference/storage/composite.md +58 -0
  49. package/.docs/reference/streaming/agents/stream.md +1 -1
  50. package/.docs/reference/tools/bedrock-kb-tool.md +117 -0
  51. package/.docs/reference/tools/mcp-client.md +54 -0
  52. package/.docs/reference/voice/google.md +19 -3
  53. package/.docs/reference/workflows/step.md +40 -0
  54. package/.docs/reference/workspace/workspace-class.md +2 -0
  55. package/CHANGELOG.md +23 -0
  56. 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 or reject the delegation entirely.
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. Suitable for development and basic use cases.
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. Available voices can be filtered by language code using the `getSpeakers()` method.
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
- 8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.
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.1",
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.15.1",
32
- "@mastra/core": "1.58.0-alpha.0"
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": "^1.19.14",
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/types-builder": "0.0.96",
49
- "@mastra/core": "1.58.0-alpha.0",
50
- "@internal/lint": "0.0.121"
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": {