@mastra/mcp-docs-server 1.1.35-alpha.2 → 1.1.35-alpha.21

package/.docs/reference/streaming/ChunkType.md

@@ -518,6 +518,50 @@ Emitted when the task throws or times out. Triggers a continuation turn when con
 
 **payload.completedAt** (`Date`): Timestamp at which the task failed
 
+### background-task-suspended
+
+Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted; resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.
+
+When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation — the agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
+
+**type** (`"background-task-suspended"`): Chunk type identifier
+
+**payload** (`BackgroundTaskSuspendedPayload`): Suspension details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.suspendData** (`unknown`): Whatever the tool passed to \`suspend(data)\`
+
+### background-task-resumed
+
+Emitted when a suspended task is resumed via `mastra.backgroundTaskManager.resume(taskId, resumeData)`. The task transitions back to `running` and the tool's `execute` is restarted with `resumeData` populated.
+
+**type** (`"background-task-resumed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskResumedPayload`): Resume details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.startedAt** (`Date`): Timestamp at which the task resumed
+
+**payload.args** (`Record<string, unknown>`): Original tool arguments
+
 ### background-task-cancelled
 
 Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).

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

@@ -333,9 +333,9 @@ await agent.stream('message for agent', {
 })
 ```
 
-## OpenAI WebSocket transport
+## Responses WebSocket transport
 
-Opt into OpenAI Responses WebSocket streaming via `providerOptions.openai.transport`. This only applies to streaming calls and is currently supported for direct OpenAI models (for example, `openai/gpt-5.4`). If WebSocket streaming is unavailable, Mastra falls back to HTTP streaming. By default, Mastra closes the WebSocket when the stream finishes.
+Opt into Responses WebSocket streaming with provider options. This only applies to streaming calls and is supported for direct OpenAI models and Azure OpenAI Responses deployments. If WebSocket streaming is unavailable, Mastra falls back to HTTP streaming. By default, Mastra closes the WebSocket when the stream finishes.
 
 ```ts
 const stream = await agent.stream('Hello', {
@@ -351,6 +351,20 @@ const stream = await agent.stream('Hello', {
 })
 ```
 
+For Azure OpenAI, configure the gateway with `useResponsesAPI: true`, then use `providerOptions.azure.transport`.
+
+```ts
+const stream = await agent.stream('Hello', {
+  providerOptions: {
+    azure: {
+      transport: 'websocket',
+      store: false,
+      websocket: { closeOnFinish: true },
+    },
+  },
+})
+```
+
 To keep the connection open after the stream finishes, set `closeOnFinish: false` and close it manually.
 
 ```ts
@@ -367,6 +381,8 @@ const stream = await agent.stream('Hello', {
 stream.transport?.close()
 ```
 
+Responses WebSocket connections run one response at a time. Mastra rejects overlapping continuation requests that include `previous_response_id` on the same WebSocket transport. Wait for the active stream to finish before sending the next turn in the response chain.
+
 ## Related
 
 - [Generating responses](https://mastra.ai/docs/agents/overview)

package/.docs/reference/tools/create-tool.md

@@ -173,6 +173,50 @@ The tool still returns the full `execute` result to your application, while the
 - `type: 'json'`
 - `type: 'content'` with parts like `text`, `image-url`, `image-data`, `file-url`, `file-data`, `file-id`, `image-file-id`, or `custom`
 
+## Example with `transform`
+
+Use `transform` when the tool should keep raw inputs or outputs for runtime behavior, but display streams or transcript messages should receive a smaller or safer shape.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const customerTool = createTool({
+  id: 'lookup-customer',
+  description: 'Looks up a customer',
+  inputSchema: z.object({
+    customerId: z.string(),
+    internalPath: z.string(),
+  }),
+  outputSchema: z.object({
+    displayName: z.string(),
+    apiKey: z.string(),
+    debugScore: z.number(),
+  }),
+  execute: async () => {
+    return {
+      displayName: 'Acme',
+      apiKey: 'secret-value',
+      debugScore: 0.97,
+    }
+  },
+  transform: {
+    display: {
+      input: ({ input }) => ({ customerId: input?.customerId }),
+      output: ({ output }) => ({ displayName: output?.displayName }),
+      error: () => ({ message: 'Customer lookup failed' }),
+    },
+    transcript: {
+      input: ({ input }) => ({ customerId: input?.customerId }),
+      output: ({ output }) => ({ displayName: output?.displayName }),
+      error: () => ({ message: 'Customer lookup failed' }),
+    },
+  },
+})
+```
+
+The tool still receives the raw `inputSchema` value and returns the raw `execute` result. Mastra applies `display` transforms to streamed UI payloads and `transcript` transforms to user-visible transcript messages.
+
 ## Example with MCP annotations
 
 When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
@@ -224,6 +268,8 @@ export const weatherTool = createTool({
 
 **toModelOutput** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
 
+**transform** (`ToolPayloadTransform`): Optional target-aware transform for tool payloads before they leave runtime for display streams or user-visible transcript messages. Configure \`display\` and \`transcript\` transforms for phases such as \`input\`, \`inputDelta\`, \`output\`, \`error\`, \`approval\`, \`suspend\`, and \`resume\`.
+
 **suspendSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
 
 **resumeSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.

package/.docs/reference/tools/mcp-client.md

@@ -987,6 +987,53 @@ await agent.generate('Hello!', {
 })
 ```
 
+## Handling auth failures inside custom fetch
+
+A custom `fetch` should not `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
+
+Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it does not offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server does not push notifications.
+
+The following pattern waits for an auth token on POST requests, attaches it to outgoing headers, and short-circuits the GET listener with a synthetic 405:
+
+```typescript
+async function waitForToken(timeoutMs = 5000): Promise<string | null> {
+  // Replace with your token lookup. Return null if no token is available.
+  return getAuthToken({ timeoutMs })
+}
+
+const mcpClient = new MCPClient({
+  servers: {
+    apiServer: {
+      url: new URL('https://api.example.com/mcp'),
+      fetch: async (url, init) => {
+        const method = (init?.method || 'GET').toUpperCase()
+
+        // The SDK opens a background GET stream for server-pushed notifications.
+        // If your server does not use it, short-circuit with 405 to stop reconnect attempts.
+        if (method === 'GET') {
+          return new Response(null, { status: 405, statusText: 'Method Not Allowed' })
+        }
+
+        // POST: wait for the token, then forward the request with an Authorization header.
+        const token = await waitForToken()
+        if (!token) {
+          // Forward the request without a token and let the server reject it.
+          // The SDK surfaces non-2xx POST responses as errors to the caller of
+          // tools/list, tools/call, etc., which is the desired behavior here.
+          return fetch(url, init)
+        }
+
+        const headers = new Headers(init?.headers)
+        headers.set('authorization', `Bearer ${token}`)
+        return fetch(url, { ...init, headers })
+      },
+    },
+  },
+})
+```
+
+Return `405` for the GET listener only when your server does not push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
+
 ## Using SSE request headers
 
 When using the legacy SSE MCP transport, you must configure both `requestInit` and `eventSourceInit` due to a bug in the MCP SDK. Alternatively, you can use a custom `fetch` function which will be automatically used for both POST requests and SSE connections:

package/.docs/reference/workflows/workflow-state-reader.md

@@ -0,0 +1,113 @@
+# Workflow state reader
+
+Workflow state reader helpers inspect the public `WorkflowState` returned by `workflow.getWorkflowRunById()`. Use them to recover suspended runs, inspect resume labels, and read step payloads or outputs without parsing raw workflow snapshots.
+
+## Usage example
+
+```typescript
+import { createWorkflowStateReader } from '@mastra/core/workflows'
+
+const state = await workflow.getWorkflowRunById('run-123')
+
+if (state) {
+  const reader = createWorkflowStateReader(state)
+  const suspendedStep = reader.getSuspendedStep()
+  const labels = reader.getResumeLabels()
+
+  console.log(reader.getStatus())
+  console.log(reader.getStepOutput('extract-data'))
+  console.log(suspendedStep?.path)
+  console.log(labels.approve)
+}
+```
+
+## Functions
+
+### `createWorkflowStateReader(state)`
+
+Creates a reader object with methods bound to one `WorkflowState`.
+
+```typescript
+const reader = createWorkflowStateReader(state)
+const suspendedStep = reader.getSuspendedStep()
+```
+
+### `getWorkflowStepOutput(state, stepId)`
+
+Returns the output for a step ID, including nested workflow dot paths such as `parent.child`. For `foreach` steps, returns one entry per iteration; suspended iterations can have `undefined` output entries.
+
+```typescript
+const output = getWorkflowStepOutput(state, 'extract-data')
+```
+
+### `getWorkflowStepPayload(state, stepId)`
+
+Returns the payload that was passed to a step. For `foreach` steps, returns one entry per iteration.
+
+```typescript
+const payload = getWorkflowStepPayload(state, 'extract-data')
+```
+
+### `getWorkflowSuspendedStep(state)`
+
+Returns the first suspended step from the workflow state. When multiple steps are suspended, ordering follows the order stored in `suspendedPaths`.
+
+```typescript
+const suspendedStep = getWorkflowSuspendedStep(state)
+```
+
+### `getWorkflowSuspendedSteps(state)`
+
+Returns all suspended steps from the workflow state. Each result includes the top-level step ID, resume path, execution path, suspend payload, suspend output, and matching resume labels.
+
+```typescript
+const suspendedSteps = getWorkflowSuspendedSteps(state)
+```
+
+### `getWorkflowResumeLabel(state, label)`
+
+Returns a resume label by name.
+
+```typescript
+const label = getWorkflowResumeLabel(state, 'approve')
+```
+
+### `getWorkflowResumeLabels(state)`
+
+Returns all resume labels from the workflow state.
+
+```typescript
+const labels = getWorkflowResumeLabels(state)
+```
+
+## Reader methods
+
+`createWorkflowStateReader(state)` returns the following methods:
+
+**getStatus** (`() => WorkflowRunStatus`): Returns the workflow run status.
+
+**getResult** (`() => WorkflowState["result"]`): Returns the terminal workflow result when it exists.
+
+**getError** (`() => WorkflowState["error"]`): Returns the terminal workflow error when it exists.
+
+**getStepOutput** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the output for a step ID or nested workflow dot path.
+
+**getStepPayload** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the payload for a step ID or nested workflow dot path.
+
+**getSuspendedStep** (`() => { stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> } | undefined`): Returns the first suspended step.
+
+**getSuspendedSteps** (`() => Array<{ stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> }>`): Returns all suspended steps.
+
+**getResumeLabel** (`(label: string) => { stepId: string; foreachIndex?: number } | undefined`): Returns a resume label by name.
+
+**getResumeLabels** (`() => Record<string, { stepId: string; foreachIndex?: number }>`): Returns all resume labels.
+
+## Notes
+
+`requestContext` and `tracingContext` are only returned by `workflow.getWorkflowRunById()` when explicitly requested with `fields`.
+
+## Related
+
+- [Suspend & resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
+- [Workflow class](https://mastra.ai/reference/workflows/workflow)

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @mastra/mcp-docs-server
 
+## 1.1.35-alpha.20
+
+### Patch Changes
+
+- Updated dependencies [[`7ad5585`](https://github.com/mastra-ai/mastra/commit/7ad55856406f1de398dc713f6a9eaa78b2784bb6), [`210ea7a`](https://github.com/mastra-ai/mastra/commit/210ea7af559791b73a44fc9c12179908aaa3183f), [`83218c8`](https://github.com/mastra-ai/mastra/commit/83218c88b37773c9424fbe733b37be556e55e94d), [`265ec9f`](https://github.com/mastra-ai/mastra/commit/265ec9f887b5c81255c873a76ff7796f16e4f99b), [`6ce80bf`](https://github.com/mastra-ai/mastra/commit/6ce80bf4872a891e0bddf8b80561a80584efb14b), [`9268531`](https://github.com/mastra-ai/mastra/commit/9268531e7ec4be98beeba3b3ae8be0a7ea380662), [`13ead79`](https://github.com/mastra-ai/mastra/commit/13ead79149486b88144db7e11e6ff551caef5be1), [`bd36d8e`](https://github.com/mastra-ai/mastra/commit/bd36d8eb6de8c9a0310352649dbd4b06703c2299), [`8ac9141`](https://github.com/mastra-ai/mastra/commit/8ac9141439caa8fdd674944c4d84f29b3c730296)]:
+  - @mastra/core@1.33.0-alpha.10
+
+## 1.1.35-alpha.18
+
+### Patch Changes
+
+- Updated dependencies [[`5688881`](https://github.com/mastra-ai/mastra/commit/5688881669c7ed157f31ac77f6fc5f8d95ceea32)]:
+  - @mastra/core@1.33.0-alpha.9
+
+## 1.1.35-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [[`7c275a8`](https://github.com/mastra-ai/mastra/commit/7c275a810595e1a6c41ccc39720531ab65734700), [`890b24c`](https://github.com/mastra-ai/mastra/commit/890b24cc7d32ed6aa4dfe253e54dc6bf4099f690), [`0f48ebf`](https://github.com/mastra-ai/mastra/commit/0f48ebfc7ac7897b2092a189f45751924cf56d1c), [`f180e49`](https://github.com/mastra-ai/mastra/commit/f180e4990e71b04c9a475b523584071712f0048f), [`9260e01`](https://github.com/mastra-ai/mastra/commit/9260e015276fb1b500f7878ee452b47476bf1583), [`2f6c54e`](https://github.com/mastra-ai/mastra/commit/2f6c54e17c041cac1def54baaa6b771647836414), [`e06a159`](https://github.com/mastra-ai/mastra/commit/e06a1598ca07a6c3778aefc2a2d288363c6294ff), [`db34bc6`](https://github.com/mastra-ai/mastra/commit/db34bc6fb36cf125bda0c46be4d3fdc774b70cc4)]:
+  - @mastra/core@1.33.0-alpha.8
+  - @mastra/mcp@1.7.0
+
+## 1.1.35-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`6742347`](https://github.com/mastra-ai/mastra/commit/6742347d71955d7639adc9ddf6ff8282de7ee3ba), [`7b0ad1f`](https://github.com/mastra-ai/mastra/commit/7b0ad1f5c53dc118c6da12ae82ae2587037dc2b8), [`62666c3`](https://github.com/mastra-ai/mastra/commit/62666c367eaeac3941ead454b1d38810cc855721), [`4af2160`](https://github.com/mastra-ai/mastra/commit/4af2160322f4718cac421930cce85641e9512389), [`136c959`](https://github.com/mastra-ai/mastra/commit/136c9592fb0eeb0cd212f28629d8a29b7557a2fc), [`4df7cc7`](https://github.com/mastra-ai/mastra/commit/4df7cc79342fd065fe7fdeef93c094db14b12bcd), [`aca3121`](https://github.com/mastra-ai/mastra/commit/aca31211233dac25459f140ea4fcfb3a5af64c18), [`9cdf38e`](https://github.com/mastra-ai/mastra/commit/9cdf38e58506e1109c8b38f97cd7770978a4218e), [`990851e`](https://github.com/mastra-ai/mastra/commit/990851edcb0e30be5c2c18b6532f1a876cc2d335), [`6068a6c`](https://github.com/mastra-ai/mastra/commit/6068a6c42950fad3ebfc92346417896ba60803d2), [`00106be`](https://github.com/mastra-ai/mastra/commit/00106bede59b81e5b0e9cd6aad8d3b5dbc336387), [`e2a079c`](https://github.com/mastra-ai/mastra/commit/e2a079cc3755b1895f7bd5dc36e9be81b11c7c22), [`534a456`](https://github.com/mastra-ai/mastra/commit/534a456a25e4df1e5407e7e632f4cb3b1fa14f9d), [`36bae07`](https://github.com/mastra-ai/mastra/commit/36bae07c0e70b1b3006f2fd20830e8883dcbd066)]:
+  - @mastra/core@1.33.0-alpha.7
+
+## 1.1.35-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`b560d6f`](https://github.com/mastra-ai/mastra/commit/b560d6f88b9b904b15c10f75c949eb145bc27684), [`36b3bbf`](https://github.com/mastra-ai/mastra/commit/36b3bbf5a8d59f7e23d47e29340e76c681b4929c), [`b275631`](https://github.com/mastra-ai/mastra/commit/b275631dc10541a482b2e2d4a3e3cfa843bd5fa1)]:
+  - @mastra/core@1.33.0-alpha.6
+
+## 1.1.35-alpha.11
+
+### Patch Changes
+
+- Updated dependencies [[`bae019e`](https://github.com/mastra-ai/mastra/commit/bae019ecb6694da96909f7ec7b9eb3a0a33aa887), [`33f5061`](https://github.com/mastra-ai/mastra/commit/33f5061cd1c0335020c3faae61ce96de822854fa), [`99869ec`](https://github.com/mastra-ai/mastra/commit/99869ecb1f2aa6dfcc44fa4e843e5ee0344efa64), [`d86f031`](https://github.com/mastra-ai/mastra/commit/d86f031eb6b0b2570145afafea664e59bf688962)]:
+  - @mastra/core@1.33.0-alpha.5
+
+## 1.1.35-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`9f17410`](https://github.com/mastra-ai/mastra/commit/9f1741080def23d42ee50b39887a385ae316a3c6), [`c6eb39e`](https://github.com/mastra-ai/mastra/commit/c6eb39ea6dca381c6563cb240237fbe608e02f93), [`900d086`](https://github.com/mastra-ai/mastra/commit/900d086bb737b9cf2fcf68f11b0389b801a2738c), [`4c0e286`](https://github.com/mastra-ai/mastra/commit/4c0e28637c9cfb4f416549b55e97ebfa13319dfc), [`25184ff`](https://github.com/mastra-ai/mastra/commit/25184ffaf1293ec95119426eb1a1f8d38831b96c), [`aebde9c`](https://github.com/mastra-ai/mastra/commit/aebde9cfacf56592c6b6350cae721740fe090b8a)]:
+  - @mastra/core@1.33.0-alpha.4
+
+## 1.1.35-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`087e413`](https://github.com/mastra-ai/mastra/commit/087e4133e5d6efa36619e9556c16750e4179c047), [`087e413`](https://github.com/mastra-ai/mastra/commit/087e4133e5d6efa36619e9556c16750e4179c047), [`087e413`](https://github.com/mastra-ai/mastra/commit/087e4133e5d6efa36619e9556c16750e4179c047)]:
+  - @mastra/core@1.33.0-alpha.3
+
+## 1.1.35-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`d1fdbd0`](https://github.com/mastra-ai/mastra/commit/d1fdbd012add5623cb7e6b7f882b605ab358bbb4), [`d91ebe2`](https://github.com/mastra-ai/mastra/commit/d91ebe28ee065d8f2ed6df741c3c07f58d359529)]:
+  - @mastra/core@1.33.0-alpha.2
+
+## 1.1.35-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`dccd8f1`](https://github.com/mastra-ai/mastra/commit/dccd8f1f8b8f1ad203b77556207e5529567c616d)]:
+  - @mastra/core@1.33.0-alpha.1
+
 ## 1.1.35-alpha.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.35-alpha.2",
+  "version": "1.1.35-alpha.21",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.33.0-alpha.0",
+    "@mastra/core": "1.33.0-alpha.10",
     "@mastra/mcp": "^1.7.0"
   },
   "devDependencies": {
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/lint": "0.0.92",
+    "@mastra/core": "1.33.0-alpha.10",
     "@internal/types-builder": "0.0.67",
-    "@mastra/core": "1.33.0-alpha.0"
+    "@internal/lint": "0.0.92"
   },
   "homepage": "https://mastra.ai",
   "repository": {