@mastra/mcp-docs-server 1.3.1-alpha.1 → 1.3.1-alpha.2

package/.docs/docs/evals/vitest-integration.md

@@ -30,29 +30,6 @@ export default defineConfig({
 
 The setup file registers the custom matchers on `expect`. Alternatively, call `registerEvalMatchers()` from `@mastra/evals/vitest` in your own setup file.
 
-## Resolving targets from the Mastra instance
-
-Get the `target` (and any registered scorers) from your `Mastra` instance with `mastra.getAgent()`, `mastra.getWorkflow()`, and `mastra.getScorer()` instead of importing the agent or workflow file directly. A directly imported agent or workflow has no Mastra instance attached, so anything that reaches into the registry at runtime fails. For example, a workflow step that calls `mastra.getAgent('weatherAgent')` throws because `mastra` is `undefined`, and the same applies to child workflows, `.agent('agent-id')` references by string, and tools that call `mastra.getWorkflow()`. Registered targets also attach the configured `storage`, which is what lets scores persist and trace-based trajectory scoring work. `runEvals` logs a warning when the target isn't registered.
-
-The examples below look up `answerRelevancyScorer` and `trajectoryAccuracyScorer` with `mastra.getScorer()`, so register them on the `Mastra` instance first:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import {
-  createAnswerRelevancyScorer,
-  createTrajectoryAccuracyScorerCode,
-} from '@mastra/evals/scorers/prebuilt'
-
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-  workflows: { weatherWorkflow },
-  scorers: {
-    answerRelevancyScorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
-    trajectoryAccuracyScorer: createTrajectoryAccuracyScorerCode(),
-  },
-})
-```
-
 ## Asserting on a dataset with `expectEvals`
 
 `expectEvals` runs a `runEvals` evaluation inside a regular `test()` and asserts a minimum pass rate. It accepts the same configuration as `runEvals`: a `target` agent or workflow, `data` items, and `scorers`, `gates`, or thresholds. Gates score each item pass/fail, so `toPass(0.8)` requires at least 80% of items to pass every gate. Scorer thresholds still compare the average score across items and must pass regardless of the rate:

package/.docs/docs/observability/feedback.md

@@ -130,7 +130,7 @@ await observability!.deleteFeedback({
 })
 ```
 
-Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block updates to the still-visible feedback, and you retry by calling the delete API again. Open-source deployments have no background reconciler. Configure retention for every observability signal to expire deletion requests after the signal rows they protect. If any signal is unbounded, deletion requests also remain unbounded to prevent deleted data from being reintroduced. On ClickHouse, delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
+Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block updates to the still-visible feedback, and you retry by calling the delete API again. On ClickHouse, the next review update also retries the delete and reports the feedback as not found if the retry succeeds, or saves the new status and returns the delete's error if it fails again. Open-source deployments have no background reconciler. Configure retention for every observability signal to expire deletion requests after the signal rows they protect. If any signal is unbounded, deletion requests also remain unbounded to prevent deleted data from being reintroduced. On ClickHouse, delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
 
 ## Query feedback analytics
 

package/.docs/integrations/databases/clickhouse.md

@@ -93,9 +93,7 @@ Lightweight deletion is a hide-only operation that marks rows with ClickHouse's
 
 When all five observability signals have finite retention, Mastra also applies a TTL to deletion requests so they outlive the signal rows they protect. If any signal is unbounded, deletion requests remain unbounded. See [storage retention](https://mastra.ai/reference/storage/retention) for how the deletion-request TTL is calculated.
 
-Feedback review-status updates require `ALTER UPDATE` permission on `mastra_feedback_events` and, when delta polling is enabled, `INSERT` permission on `mastra_feedback_events_delta`. These updates wait for the ClickHouse mutation to finish on the server that receives the write, so latency depends on that server's mutation queue. Other replicas apply the mutation through the replication log, so a reader on a lagging replica can briefly see the previous status, and an inactive replica doesn't block the update. They modify the existing feedback row and preserve deletion masks: a concurrent review update cannot recreate deleted feedback. Successful updates remain available through delta polling. If a newer version of the same feedback event is ingested while a review update is in flight, the update is re-applied to that newer version; after repeated conflicts it fails with a conflict error (HTTP 409) and the caller retries.
-
-The status mutation and the delta insert are separate operations. If the delta insert fails, the API returns an error even though the status may have changed, and continued delta polling doesn't recover that notification: later polls from the same cursor never return it, and starting delta mode without a cursor subscribes at the current head. To recover, retry the review update after resolving the error, or reread the feedback with a regular list query.
+Feedback review-status updates read the current row and insert a replacement, so they need `SELECT` and `INSERT` rather than `ALTER UPDATE`, and the insert materialized view publishes each update to delta polling. An update that re-runs a delete also needs the delete permissions listed in [initialization](#initialization). A review update that lands while a delete of the same feedback is in progress re-runs that delete and returns not found, so it can't recreate deleted feedback. A failed delete doesn't block review updates, but the next update retries it: if the retry succeeds, the update returns not found; if it fails again, the new status is saved but the update returns the delete's error. If a network error or a lagging replica lets a review row outlive a successful delete, the next review update of that feedback deletes it again and returns not found.
 
 ### Observability with the legacy domain
 
@@ -372,16 +370,10 @@ const observability = new ObservabilityStorageClickhouseVNext({
 await observability.init()
 ```
 
-In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials still need more than read and insert:
+In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials need:
 
 - `SELECT` and `INSERT` on the Mastra tables.
 - `ALTER DELETE` on the observability tables you delete from. On ClickHouse 26.6 and earlier, lightweight deletes also require `ALTER UPDATE` on those tables; ClickHouse 26.7 removed that requirement.
-- For feedback review updates, `ALTER UPDATE(reviewStatus)` on `mastra_feedback_events` and `INSERT` on `mastra_feedback_events_delta`.
-
-```sql
-GRANT ALTER UPDATE(reviewStatus) ON <database>.mastra_feedback_events TO <runtime_user>;
-GRANT INSERT ON <database>.mastra_feedback_events_delta TO <runtime_user>;
-```
 
 ## Observability
 

package/.docs/models/providers/edenai.md

@@ -164,7 +164,7 @@ for await (const chunk of stream) {
 | `edenai/groq/openai/gpt-oss-120b`                                      | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `edenai/groq/openai/gpt-oss-20b`                                       | 131K    |       |           |       |       |       | $0.07      | $0.30       |
 | `edenai/groq/openai/gpt-oss-safeguard-20b`                             | 131K    |       |           |       |       |       | $0.07      | $0.30       |
-| `edenai/infomaniak/mistralai/Ministral-3-14B-Instruct-2512`            | 100K    |       |           |       |       |       | $0.34      | $0.46       |
+| `edenai/infomaniak/mistralai/Ministral-3-14B-Instruct-2512`            | 100K    |       |           |       |       |       | $0.34      | $0.45       |
 | `edenai/ionos/meta-llama/Llama-3.3-70B-Instruct`                       | 128K    |       |           |       |       |       | $0.74      | $0.74       |
 | `edenai/ionos/openai/gpt-oss-120b`                                     | 131K    |       |           |       |       |       | $0.17      | $0.74       |
 | `edenai/minimax/MiniMax-M2`                                            | 205K    |       |           |       |       |       | $0.30      | $1          |
@@ -265,7 +265,7 @@ for await (const chunk of stream) {
 | `edenai/qwen/qwen3.8-max`                                              | 1.0M    |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwen3.8-max-0902`                                         | 1.0M    |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwq-plus`                                                 | 131K    |       |           |       |       |       | $0.80      | $2          |
-| `edenai/scaleway/deepseek-v4-flash-0731`                               | 256K    |       |           |       |       |       | $0.46      | $0.91       |
+| `edenai/scaleway/deepseek-v4-flash-0731`                               | 256K    |       |           |       |       |       | $0.45      | $0.91       |
 | `edenai/scaleway/gemma-3-27b-it`                                       | 40K     |       |           |       |       |       | $0.29      | $0.57       |
 | `edenai/scaleway/gpt-oss-120b`                                         | 128K    |       |           |       |       |       | $0.17      | $0.68       |
 | `edenai/scaleway/llama-3.3-70b-instruct`                               | 128K    |       |           |       |       |       | $1         | $1          |

package/.docs/models/providers/kilo.md

@@ -43,11 +43,11 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $4         | $20         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.04      | $1          |
-| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.39      | $3          |
+| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.39      | $1          |
 | `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.03      | $0.32       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $1         | $11         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $1         | $12         |
 | `kilo/~openai/gpt-astra-latest`                                 | 1.1M    |       |           |       |       |       | $10        | $50         |
 | `kilo/~openai/gpt-luna-latest`                                  | 1.1M    |       |           |       |       |       | $0.10      | $0.50       |
 | `kilo/~openai/gpt-mini-latest`                                  | 400K    |       |           |       |       |       | $0.75      | $5          |
@@ -55,7 +55,7 @@ for await (const chunk of stream) {
 | `kilo/~openai/gpt-terra-latest`                                 | 1.1M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~x-ai/grok-latest`                                        | 500K    |       |           |       |       |       | $2         | $5          |
 | `kilo/~z-ai/glm-flash-latest`                                   | 1.0M    |       |           |       |       |       | $0.04      | $0.14       |
-| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.56      | $3          |
+| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.56      | $2          |
 | `kilo/aion-labs/aion-2.0`                                       | 131K    |       |           |       |       |       | $0.80      | $2          |
 | `kilo/aion-labs/aion-3.0`                                       | 131K    |       |           |       |       |       | $3         | $6          |
 | `kilo/aion-labs/aion-3.0-mini`                                  | 131K    |       |           |       |       |       | $0.70      | $1          |
@@ -386,7 +386,7 @@ for await (const chunk of stream) {
 | `kilo/tencent/hy-mt2-1.8b`                                      | 8K      |       |           |       |       |       | $0.04      | $0.18       |
 | `kilo/tencent/hy-mt2-30b-a3b`                                   | 8K      |       |           |       |       |       | $0.07      | $0.29       |
 | `kilo/tencent/hy-mt2-7b`                                        | 8K      |       |           |       |       |       | $0.07      | $0.29       |
-| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.13      | $0.53       |
+| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.08      | $0.33       |
 | `kilo/tencent/hy3-preview`                                      | 262K    |       |           |       |       |       | $0.18      | $0.60       |
 | `kilo/tencent/hy4-preview`                                      | 1.0M    |       |           |       |       |       | $0.83      | $3          |
 | `kilo/thedrummer/cydonia-24b-v4.1`                              | 131K    |       |           |       |       |       | $0.30      | $0.50       |

package/.docs/reference/memory/observational-memory.md

@@ -186,6 +186,7 @@ const memory = new Memory({
 - Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
+- When `workingMemory.schema` is set, `WorkingMemoryExtractor` validates each update against that schema before saving it. If an update doesn't match, it's skipped and reported as an extraction failure while the previous working memory stays in place. Because the schema isn't sent to the model as a structured output constraint, one invalid working memory update can't fail other extractors. A `null` in an optional field is treated as not provided.
 - `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor` and defaults `workingMemory.agentManaged` to `false`. It defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
 - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 

package/.docs/reference/observability/feedback.md

@@ -138,7 +138,7 @@ await mastraClient.deleteFeedback({
 
 Returns `Promise<{ success: boolean }>` from `mastraClient.deleteFeedback()` and the HTTP route. The storage domain method returns `Promise<void>`. Requests with more than 1,000 ids return `400`, and a server running `@mastra/core` older than `1.66.0` returns `501`. ClickHouse vNext, PostgreSQL vNext, DuckDB, and the in-memory store implement deletion. Every other adapter, including LibSQL and MongoDB, throws `OBSERVABILITY_STORAGE_DELETE_FEEDBACK_NOT_IMPLEMENTED`.
 
-On ClickHouse, deletion uses lightweight deletes on the main feedback events table to remove rows from reads, including OLAP queries, without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block `updateFeedbackReviewStatus()` on the still-visible feedback, and you retry by calling `deleteFeedback()` again. Open-source deployments have no background reconciler. ClickHouse applies a TTL to deletion requests only when all five signals have finite retention. See [ClickHouse native TTL](https://mastra.ai/reference/storage/retention). Delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
+On ClickHouse, deletion uses lightweight deletes on the main feedback events table to remove rows from reads, including OLAP queries, without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block `updateFeedbackReviewStatus()` on the still-visible feedback, and you retry by calling `deleteFeedback()` again. `updateFeedbackReviewStatus()` also retries the delete and throws a not-found error if the retry succeeds, or saves the new status and throws the delete's error if it fails again. Open-source deployments have no background reconciler. ClickHouse applies a TTL to deletion requests only when all five signals have finite retention. See [ClickHouse native TTL](https://mastra.ai/reference/storage/retention). Delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
 
 ### `deleteScores(args)`
 

package/.docs/reference/observability/tracing/spans.md

@@ -51,7 +51,7 @@ interface BaseSpan<TType extends SpanType> {
 
   /** Snapshot of the RequestContext */
   requestContext?: Record<string, any>
-  /** Is an event span? (occurs at startTime, has no endTime) */
+  /** Is an event span? (point-in-time: endTime equals startTime) */
   isEvent: boolean
 }
 ```
@@ -133,7 +133,7 @@ createEventSpan<TChildType extends SpanType>(
 ): Span<TChildType>
 ```
 
-Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
+Creates an event span under this span. Event spans represent point-in-time occurrences with no duration. They're emitted as soon as they're created, with `isEvent: true` and an `endTime` equal to their `startTime`, so stored and exported records have `endedAt` equal to `startedAt`.
 
 ## `ExportedSpan`
 

package/.docs/reference/server/nestjs-adapter.md

@@ -87,7 +87,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): Request context parsing config
 
-**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH.
+**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH. Custom routes from server.apiRoutes (registerApiRoute()) are added automatically based on their requiresAuth setting.
 
 **tools** (`Record<string, Tool>`): Registered tools for the server
 
@@ -95,7 +95,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP transport options
 
-**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Enable Mastra token auth. Disabled by default — most NestJS apps use their own auth guards. Query-string apiKey auth is opt-in for backward compatibility. (Default: `` `{ enabled: false }` ``)
+**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Controls Mastra auth for Mastra routes. When server.auth is configured on your Mastra instance, it runs automatically (the same pipeline as other adapters: bearer tokens, cookie sessions, session refresh, and mapUserToResourceId). Set enabled: false to rely only on your own NestJS guards. Query-string apiKey auth is opt-in for backward compatibility.
 
 ## Async registration
 

package/.docs/reference/streaming/agents/stream.md

@@ -190,6 +190,8 @@ const stream = await agent.stream('message for agent')
 
 **options.toolCallConcurrency** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
 
+**options.eagerToolExecution** (`boolean`): Defaults to true. A tool call whose arguments have finished streaming starts executing immediately, instead of waiting for the model to finish the whole step. Set it to false to restore the previous scheduling. Tool results and message history keep their model-call order either way. Only server-side tools are started early: approval-gated, suspend-schema-declaring, provider-executed, client-side, background-dispatched (by argument or by backgroundTasks config), missing and inactive tools are left to the post-stream pass, as is any run using autoResumeSuspendedTools or an output processor that runs after the stream completes. That last case is wider than it sounds: a processor workflow you build yourself counts whatever it contains, because its contents are not inspected, and so does structuredOutput when given an explicit model. A processor implementing processToolResult is excluded too when a provider-executed tool is configured: that hook runs inside the stream when a provider result arrives there, and its abort bails the turn before the post-stream pass, so starting a tool early would change whether it runs, not just when. Without a provider tool, the hook only sees results after the pass and early dispatch stays on. Also left to the post-stream pass is any run using toolCallConcurrency.strategy: 'called' (the full set of called tools is not known until the step finishes). Eager executions honour the same toolCallConcurrency limit (they are counted separately from the post-stream pass, so the limit constrains each rather than being pooled across both) and aborting the run waits for work already running, then keeps its result, as the post-stream pass does. A tool that already ran is never run again, and its finished result is never thrown away. If the last model fails mid-stream with no retry, its calls still run through the post-stream pass, which adopts eager work instead of restarting it. If the attempt is retried or failed over, tools still running are allowed to finish, and every started call's result or error is written into the conversation before the replacement attempt begins, even if the retry never runs. A tool that calls suspend() at runtime without declaring a suspend schema cannot be detected in advance; the early attempt hands its suspension back to that call's own post-stream iteration, which raises the real suspension with the tool's own payload, so the tool body runs exactly once — the same as it would without early execution. Because that pre-suspend work already happened, an attempt holding such a call is never retried or failed over: the run suspends on that call instead, so resuming it is the only way the tool runs again. Not supported by durable agents, which reject an explicit true.
+
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is { providerName: { optionKey: value } }. For example: { openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }.
 
 **options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI-specific options. Example: { reasoningEffort: 'high' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.1-alpha.1",
+  "version": "1.3.1-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,8 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.71.0-alpha.0",
-    "@mastra/mcp": "^2.1.0"
+    "@mastra/mcp": "^2.1.0",
+    "@mastra/core": "1.71.0-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -44,8 +44,8 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "@internal/lint": "0.0.136",
-    "@internal/types-builder": "0.0.111",
-    "@mastra/core": "1.71.0-alpha.0"
+    "@mastra/core": "1.71.0-alpha.1",
+    "@internal/types-builder": "0.0.111"
   },
   "homepage": "https://mastra.ai",
   "repository": {