@mastra/mcp-docs-server 1.2.15-alpha.3 → 1.2.15-alpha.7

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -0,0 +1,117 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# createBedrockKBTool()
+
+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.
+
+## Usage example
+
+```typescript
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+  region: 'us-west-2',
+  numberOfResults: 5,
+  useAgenticRetrieval: true,
+})
+```
+
+### With an Agent
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+})
+
+const agent = new Agent({
+  name: 'KnowledgeAssistant',
+  instructions: 'Use the knowledge base tool to answer questions.',
+  model: myModel,
+  tools: { kb: kbTool },
+})
+```
+
+## Parameters
+
+**knowledgeBaseId** (`string`): The ID of the Amazon Bedrock Knowledge Base to query.
+
+**region** (`string`): AWS region where the Knowledge Base is deployed. Defaults to AWS\_REGION environment variable or us-east-1.
+
+**numberOfResults** (`number`): Maximum number of results to return. Defaults to 5.
+
+**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).
+
+**userId** (`string`): Default AWS user ID for document-level access control. A userId in the Mastra request context takes precedence.
+
+## Input Schema
+
+The tool accepts the following input when called by an agent:
+
+**queryText** (`string`): The search query to find relevant documents in the knowledge base.
+
+## Output Schema
+
+The tool returns an object with:
+
+**results** (`BedrockKBResult[]`): Array of retrieval results. Standard retrieval includes source and score when Bedrock provides them; agentic retrieval may omit those fields.
+
+### BedrockKBResult
+
+| Field      | Type                      | Description                                                                                                                           |
+| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
+| `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
+
+## Retrieval Modes
+
+### Agentic Retrieval (default)
+
+When `useAgenticRetrieval` is `true` (default), the tool uses `AgenticRetrieveStreamCommand` which:
+
+- Decomposes complex queries into sub-queries
+- Retrieves across multiple passes
+- Applies managed reranking for better results
+
+If agentic retrieval fails (e.g., older SDK, permissions), it automatically falls back to standard managed retrieval.
+
+### Standard Managed Retrieval
+
+When `useAgenticRetrieval` is `false`, the tool uses `RetrieveCommand` with `managedSearchConfiguration` for direct single-pass retrieval.
+
+## User-based access control
+
+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.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const requestContext = new RequestContext()
+requestContext.set('userId', 'user-123')
+
+await agent.generate('Find my private documents', { requestContext })
+```
+
+## Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
+      "Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
+    }
+  ]
+}
+```
+
+## SDK Requirements
+
+- `@aws-sdk/client-bedrock-agent-runtime` >= 3.1000 (AgenticRetrieveStreamCommand requires \~3.1000+)

package/.docs/reference/voice/google.md

@@ -109,7 +109,17 @@ Converts speech to text using Google Cloud Speech-to-Text service. Supports both
 
 Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
 
+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.
+
 ```typescript
+import { GoogleVoice } from '@mastra/voice-google'
+
+// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
+// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
+const voice = new GoogleVoice({
+  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
+})
+
 const transcript = await voice.listen(iosSafariAacStream, {
   v2: true,
   config: {
@@ -118,6 +128,8 @@ const transcript = await voice.listen(iosSafariAacStream, {
 })
 ```
 
+> **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.
+
 **audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
 
 **options** (`GoogleListenOptionsV2`): v2 recognition options
@@ -162,7 +174,7 @@ The Google Voice provider supports two authentication methods:
 
 ### Standard Mode (API Key)
 
-Uses a Google Cloud API key for authentication. Suitable for development and basic use cases.
+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)).
 
 ```typescript
 // Using environment variable (GOOGLE_API_KEY)
@@ -238,6 +250,8 @@ For Speech-to-Text:
 
 - `roles/speech.client` - Speech-to-Text Client
 
+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.
+
 #### OAuth Scopes
 
 For synchronous Text-to-Speech synthesis:
@@ -269,6 +283,8 @@ For long-audio Text-to-Speech operations:
 
 6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
 
-7. Available voices can be filtered by language code using the `getSpeakers()` method.
+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.
+
+8. Available voices can be filtered by language code using the `getSpeakers()` method.
 
-8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.
+9. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.

package/.docs/reference/workflows/step.md

@@ -191,8 +191,48 @@ const agentStep = createStep(testAgent, {
 
 **execute.retryCount** (`number`): The retry count for this specific step, it automatically increases each time the step is retried
 
+**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.
+
+**retries** (`number`): Number of times to retry the step's execute function if it throws.
+
 **metadata** (`Record<string, any>`): Optional key-value pairs for storing additional step information. Values must be serializable (no functions, circular references, etc.).
 
+## Scoring step output
+
+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.
+
+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.
+
+The following example attaches a scorer to a retrieval step so every execution is scored:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+import { retrievalRelevanceScorer } from '../scorers/retrieval-relevance'
+
+const retrievalStep = createStep({
+  id: 'retrieval',
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.object({ query: z.string(), chunks: z.array(z.string()) }),
+  scorers: {
+    retrievalRelevance: {
+      scorer: retrievalRelevanceScorer(),
+      sampling: { type: 'ratio', rate: 1 },
+    },
+  },
+  execute: async ({ inputData }) => {
+    const chunks = await retrieve(inputData.query)
+    return { query: inputData.query, chunks }
+  },
+})
+```
+
+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.
+
+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.
+
+> **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.
+
 ## Related
 
 - [Workflow state](https://mastra.ai/docs/workflows/workflow-state)

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/mcp-docs-server
 
+## 1.2.15-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`76e5132`](https://github.com/mastra-ai/mastra/commit/76e51328dbc0749c8304e6b3f21e4401f451b081), [`0282e16`](https://github.com/mastra-ai/mastra/commit/0282e16115538c8e9b248b90f0748eb01cb5dc98)]:
+  - @mastra/core@1.58.0-alpha.4
+
+## 1.2.15-alpha.6
+
+### Patch Changes
+
+- 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)]:
+  - @mastra/core@1.58.0-alpha.3
+  - @mastra/mcp@1.16.0-alpha.1
+
+## 1.2.15-alpha.4
+
+### Patch Changes
+
+- 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)]:
+  - @mastra/core@1.58.0-alpha.2
+
 ## 1.2.15-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.15-alpha.3",
+  "version": "1.2.15-alpha.7",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.16.0-alpha.0",
-    "@mastra/core": "1.58.0-alpha.1"
+    "@mastra/mcp": "^1.16.0-alpha.1",
+    "@mastra/core": "1.58.0-alpha.4"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -47,7 +47,7 @@
     "vitest": "4.1.10",
     "@internal/types-builder": "0.0.96",
     "@internal/lint": "0.0.121",
-    "@mastra/core": "1.58.0-alpha.1"
+    "@mastra/core": "1.58.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {