@mastra/mcp-docs-server 1.2.1-alpha.2 → 1.2.1-alpha.5

package/.docs/docs/streaming/tool-streaming.md

@@ -1,189 +0,0 @@
-# Tool streaming
-
-Tool streaming in Mastra enables tools to send incremental results while they run, rather than waiting until execution finishes. This allows you to surface partial progress, intermediate states, or progressive data directly to users or upstream agents and workflows.
-
-Streams can be written to in two main ways:
-
-- **From within a tool**: every tool receives a `context.writer` object, which is a writable stream you can use to push updates as execution progresses.
-- **From an agent stream**: you can also pipe an agent's `stream` output directly into a tool's writer, making it convenient to chain agent responses into tool results without extra glue code.
-
-By combining writable tool streams with agent streaming, you gain fine grained control over how intermediate results flow through your system and into the user experience.
-
-## Agent using tool
-
-Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This makes it possible to surface tool activity as part of the overall interaction.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { testTool } from '../tools/test-tool'
-
-export const testAgent = new Agent({
-  id: 'test-agent',
-  name: 'Test Agent',
-  instructions: 'You are a weather agent.',
-  model: 'openai/gpt-5.5',
-  tools: { testTool },
-})
-```
-
-### Using `context.writer`
-
-The `context.writer` object is available in a tool's `execute()` function and can be used to emit custom events, data, or values into the active stream. This enables tools to provide intermediate results or status updates while execution is still in progress.
-
-> **Warning:** You must `await` the call to `writer.write()` or else you will lock the stream and get a `WritableStream is locked` error.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-
-export const testTool = createTool({
-  execute: async (inputData, context) => {
-    const { value } = inputData
-
-    await context?.writer?.write({
-      type: 'custom-event',
-      status: 'pending',
-    })
-
-    const response = await fetch()
-
-    await context?.writer?.write({
-      type: 'custom-event',
-      status: 'success',
-    })
-
-    return {
-      value: '',
-    }
-  },
-})
-```
-
-You can also use `writer.custom()` to emit top-level stream chunks. This is useful when integrating with UI frameworks.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-
-export const testTool = createTool({
-  execute: async (inputData, context) => {
-    const { value } = inputData
-
-    await context?.writer?.custom({
-      type: 'data-tool-progress',
-      status: 'pending',
-    })
-
-    const response = await fetch()
-
-    await context?.writer?.custom({
-      type: 'data-tool-progress',
-      status: 'success',
-    })
-
-    return {
-      value: '',
-    }
-  },
-})
-```
-
-### Transient data chunks
-
-By default, `data-*` chunks emitted with `writer.custom()` are persisted to storage as part of the message history. For chunks that are only needed during live streaming — such as progress updates or verbose log output — set `transient: true` to skip storage persistence. Transient chunks are still streamed to the client in real time but aren't saved to the database.
-
-```typescript
-await context?.writer?.custom({
-  type: 'data-build-log',
-  data: { line: 'Compiling module 3 of 12...' },
-  transient: true,
-})
-```
-
-Use transient chunks when the data is large or high-frequency and only relevant during the live session. After a page refresh, transient chunks are no longer available — only the tool's return value and any non-transient chunks are loaded from storage.
-
-### Inspecting stream payloads
-
-Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or tool-specific data.
-
-```typescript
-const stream = await testAgent.stream(['What is the weather in London?', 'Use the testTool'])
-
-for await (const chunk of stream) {
-  if (chunk.payload.output?.type === 'custom-event') {
-    console.log(JSON.stringify(chunk, null, 2))
-  }
-}
-```
-
-## Tool lifecycle hooks
-
-Tools support lifecycle hooks that allow you to monitor different stages of tool execution during streaming. These hooks are particularly useful for logging or analytics.
-
-### Example: Using `onInputAvailable` and `onOutput`
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export const weatherTool = createTool({
-  id: 'weather-tool',
-  description: 'Get weather information',
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  outputSchema: z.object({
-    temperature: z.number(),
-    conditions: z.string(),
-  }),
-  // Called when the complete input is available
-  onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Weather requested for: ${input.city}`)
-  },
-  execute: async input => {
-    const weather = await fetchWeather(input.city)
-    return weather
-  },
-  // Called after successful execution
-  onOutput: ({ output, toolName }) => {
-    console.log(`${toolName} result: ${output.temperature}°F, ${output.conditions}`)
-  },
-})
-```
-
-### Available Hooks
-
-- **onInputStart**: Called when tool call input streaming begins
-- **onInputDelta**: Called for each chunk of input as it streams in
-- **onInputAvailable**: Called when complete input is parsed and validated
-- **onOutput**: Called after the tool successfully executes with the output
-
-For detailed documentation on all lifecycle hooks, see the [createTool() reference](https://mastra.ai/reference/tools/create-tool).
-
-### Streaming tool input in UIs
-
-When a model generates a tool call, the arguments arrive incrementally as `tool-call-delta` stream chunks before the final `tool-call` chunk. UIs can listen for the corresponding `tool_input_start`, `tool_input_delta`, and `tool_input_end` events to render tool arguments as they stream in — for example, showing a file path or command immediately rather than waiting for the complete tool call.
-
-Using a partial JSON parser on the accumulated `argsTextDelta` fragments lets you extract usable argument values before the JSON is complete. This enables features like live diff previews for edit tools, streaming file content for write tools, and instant display of search patterns or file paths.
-
-## Tool using an agent
-
-Pipe an agent's `fullStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export const testTool = createTool({
-  execute: async (inputData, context) => {
-    const { city } = inputData
-
-    const agent = context?.mastra?.getAgent('testAgent')
-    const stream = await agent?.stream(`What is the weather in ${city}?`)
-
-    await stream!.fullStream.pipeTo(context?.writer!)
-
-    return {
-      value: await stream!.text,
-    }
-  },
-})
-```

package/.docs/docs/streaming/workflow-streaming.md

@@ -1,109 +0,0 @@
-# Workflow streaming
-
-Workflow streaming in Mastra enables workflows to send incremental results while they execute, rather than waiting until completion. This allows you to surface partial progress, intermediate states, or progressive data directly to users or upstream agents and workflows.
-
-Streams can be written to in two main ways:
-
-- **From within a workflow step**: every workflow step receives a `writer` argument, which is a writable stream you can use to push updates as execution progresses.
-- **From an agent stream**: you can also pipe an agent's `stream` output directly into a workflow step's writer, making it convenient to chain agent responses into workflow results without extra glue code.
-
-By combining writable workflow streams with agent streaming, you gain fine-grained control over how intermediate results flow through your system and into the user experience.
-
-## Using the `writer` argument
-
-The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
-
-> **Warning:** You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
-
-```typescript
-import { createStep } from "@mastra/core/workflows";
-
-export const testStep = createStep({
-  execute: async ({ inputData, writer }) => {
-    const { value } = inputData;
-
-    await writer?.write({
-      type: "custom-event",
-      status: "pending"
-    });
-
-    const response = await fetch(...);
-
-    await writer?.write({
-      type: "custom-event",
-      status: "success"
-    });
-
-    return {
-      value: ""
-    };
-  },
-});
-```
-
-## Inspecting workflow stream payloads
-
-Events written to the stream are included in the emitted chunks. These chunks can be inspected to access any custom fields, such as event types, intermediate values, or step-specific data.
-
-```typescript
-const testWorkflow = mastra.getWorkflow('testWorkflow')
-
-const run = await testWorkflow.createRun()
-
-const stream = await run.stream({
-  inputData: {
-    value: 'initial data',
-  },
-})
-
-for await (const chunk of stream) {
-  console.log(chunk)
-}
-
-if (result!.status === 'suspended') {
-  // if the workflow is suspended, we can resume it with the resumeStream method
-  const resumedStream = await run.resumeStream({
-    resumeData: { value: 'resume data' },
-  })
-
-  for await (const chunk of resumedStream) {
-    console.log(chunk)
-  }
-}
-```
-
-## Resuming an interrupted workflow stream
-
-If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStream` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
-
-```typescript
-const newStream = await run.resumeStream()
-
-for await (const chunk of newStream) {
-  console.log(chunk)
-}
-```
-
-## Workflow using an agent
-
-Pipe an agent's `textStream` to the workflow step's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the workflow run.
-
-```typescript
-import { createStep } from '@mastra/core/workflows'
-import { z } from 'zod'
-
-export const testStep = createStep({
-  execute: async ({ inputData, mastra, writer }) => {
-    const { city } = inputData
-
-    const testAgent = mastra?.getAgent('testAgent')
-    const stream = await testAgent?.stream(`What is the weather in ${city}$?`)
-
-    await stream!.textStream.pipeTo(writer!)
-
-    return {
-      value: await stream!.text,
-    }
-  },
-})
-```