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

package/.docs/docs/build-with-ai/skills.md

@@ -1,63 +0,0 @@
-# Mastra skills
-
-Mastra Skills are folders of instructions, scripts, and resources that agents can discover and use to gain Mastra knowledge. They contain setup instructions, best practices, and methods to fetch up-to-date information from Mastra's documentation.
-
-## Installation
-
-To install all available Mastra skills, run the following command:
-
-**npm**:
-
-```bash
-npx skills add mastra-ai/skills
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx skills add mastra-ai/skills
-```
-
-**Yarn**:
-
-```bash
-yarn dlx skills add mastra-ai/skills
-```
-
-**Bun**:
-
-```bash
-bun x skills add mastra-ai/skills
-```
-
-Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
-
-They're also available on [GitHub](https://github.com/mastra-ai/skills).
-
-## Update skill
-
-To update to the latest version of the Mastra skill, run:
-
-**npm**:
-
-```bash
-npx skills update mastra
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx skills update mastra
-```
-
-**Yarn**:
-
-```bash
-yarn dlx skills update mastra
-```
-
-**Bun**:
-
-```bash
-bun x skills update mastra
-```

package/.docs/docs/streaming/background-task-streaming.md

@@ -1,80 +0,0 @@
-# Background task streaming
-
-**Added in:** `@mastra/core@1.29.0`
-
-`mastra.backgroundTaskManager.stream()` returns a `ReadableStream` of [background task](https://mastra.ai/docs/agents/background-tasks) lifecycle events. Use it to monitor running tasks across the system, for example to drive a status dashboard, surface progress in your own UI, or pipe events into an SSE response.
-
-The stream emits the same chunk types that appear inside `Agent.streamUntilIdle()` (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`). See [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the full payload shapes.
-
-> **Note:** Background tasks must be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) before `backgroundTaskManager` is available. When disabled, `mastra.backgroundTaskManager` is `undefined`.
-
-## Subscribe to all task events
-
-Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
-
-```typescript
-const bgManager = mastra.backgroundTaskManager
-if (!bgManager) throw new Error('Background tasks are not enabled')
-
-const controller = new AbortController()
-const stream = bgManager.stream({ abortSignal: controller.signal })
-
-for await (const chunk of stream) {
-  switch (chunk.type) {
-    case 'background-task-running':
-      console.log('started', chunk.payload.taskId, chunk.payload.toolName)
-      break
-    case 'background-task-completed':
-      console.log('done', chunk.payload.taskId, chunk.payload.result)
-      break
-    case 'background-task-failed':
-      console.error('failed', chunk.payload.taskId, chunk.payload.error)
-      break
-  }
-}
-```
-
-The stream stays open until the caller's `AbortSignal` fires. Always pass an `abortSignal` so you can disconnect cleanly.
-
-## Filter the stream
-
-Pass any combination of filter options to narrow the events you receive. Filters apply to both the initial snapshot and the live event subscription.
-
-```typescript
-const stream = bgManager.stream({
-  agentId: 'researcher',
-  threadId: 't1',
-  resourceId: 'u1',
-  abortSignal: controller.signal,
-})
-```
-
-| Filter        | Description                                         |
-| ------------- | --------------------------------------------------- |
-| `agentId`     | Only events from tasks dispatched by this agent     |
-| `runId`       | Only events from this specific agent run            |
-| `threadId`    | Only events from tasks scoped to this memory thread |
-| `resourceId`  | Only events from tasks scoped to this resource      |
-| `taskId`      | Only events for a single task                       |
-| `abortSignal` | Closes the stream when the signal aborts            |
-
-## Look up task state directly
-
-For one-off lookups instead of a live stream, use `getTask` and `listTasks`:
-
-```typescript
-const task = await mastra.backgroundTaskManager?.getTask(taskId)
-const { tasks, total } = await mastra.backgroundTaskManager?.listTasks({
-  status: 'running',
-  agentId: 'researcher',
-})
-```
-
-These read from storage rather than the pubsub stream, so they're suitable for paginated lists and detail views.
-
-## Related
-
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
-- [`Agent.streamUntilIdle()` reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
-- [Background task chunks](https://mastra.ai/reference/streaming/ChunkType)
-- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)

package/.docs/docs/streaming/events.md

@@ -1,148 +0,0 @@
-# Streaming events
-
-Streaming from agents or workflows provides real-time visibility into either the LLM’s output or the status of a workflow run. This feedback can be passed directly to the user, or used within applications to handle workflow status more effectively, creating a smoother and more responsive experience.
-
-Events emitted from agents or workflows represent different stages of generation and execution, such as when a run starts, when text is produced, or when a tool is invoked.
-
-## Event types
-
-Below is a complete list of events emitted from `.stream()`. Depending on whether you’re streaming from an **agent** or a **workflow**, only a subset of these events will occur:
-
-- **start**: Marks the beginning of an agent or workflow run.
-- **step-start**: Indicates a workflow step has begun execution.
-- **text-delta**: Incremental text chunks as they're generated by the LLM.
-- **tool-call**: When the agent decides to use a tool, including the tool name and arguments.
-- **tool-result**: The result returned from tool execution.
-- **step-finish**: Confirms that a specific step has fully finalized, and may include metadata like the finish reason for that step.
-- **finish**: When the agent or workflow completes, including usage statistics.
-
-## Network event types
-
-When using `agent.network()` for multi-agent collaboration, additional event types are emitted to track the orchestration flow:
-
-- **routing-agent-start**: The routing agent begins analyzing the task to decide which primitive (agent/workflow/tool) to delegate to.
-- **routing-agent-text-delta**: Incremental text as the routing agent processes the response from the selected primitive.
-- **routing-agent-end**: The routing agent completes its selection, including the selected primitive and reason for selection.
-- **agent-execution-start**: A delegated agent begins execution.
-- **agent-execution-end**: A delegated agent completes execution.
-- **agent-execution-event-\***: Events from the delegated agent's execution (e.g., `agent-execution-event-text-delta`).
-- **workflow-execution-start**: A delegated workflow begins execution.
-- **workflow-execution-end**: A delegated workflow completes execution.
-- **workflow-execution-event-\***: Events from the delegated workflow's execution.
-- **tool-execution-start**: A delegated tool begins execution.
-- **tool-execution-end**: A delegated tool completes execution.
-- **network-execution-event-step-finish**: A network iteration step completes.
-- **network-execution-event-finish**: The entire network execution completes.
-
-## Inspecting agent streams
-
-Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
-
-```typescript
-const testAgent = mastra.getAgent('testAgent')
-
-const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
-
-for await (const chunk of stream) {
-  console.log(chunk)
-}
-```
-
-> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
-
-### Example agent output
-
-Below is an example of events that may be emitted. Each event always includes a `type` and can include additional fields like `from` and `payload`.
-
-```typescript
-{
-  type: 'start',
-  from: 'AGENT',
-  // ..
-}
-{
-  type: 'step-start',
-  from: 'AGENT',
-  payload: {
-    messageId: 'msg-cdUrkirvXw8A6oE4t5lzDuxi',
-    // ...
-  }
-}
-{
-  type: 'tool-call',
-  from: 'AGENT',
-  payload: {
-    toolCallId: 'call_jbhi3s1qvR6Aqt9axCfTBMsA',
-    toolName: 'testTool'
-    // ..
-  }
-}
-```
-
-## Inspecting workflow streams
-
-Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
-
-```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)
-}
-```
-
-### Example workflow output
-
-Below is an example of events that may be emitted. Each event always includes a `type` and can include additional fields like `from` and `payload`.
-
-```typescript
-{
-  type: 'workflow-start',
-  runId: '221333ed-d9ee-4737-922b-4ab4d9de73e6',
-  from: 'WORKFLOW',
-  // ...
-}
-{
-  type: 'workflow-step-start',
-  runId: '221333ed-d9ee-4737-922b-4ab4d9de73e6',
-  from: 'WORKFLOW',
-  payload: {
-    stepName: 'step-1',
-    args: { value: 'initial data' },
-    stepCallId: '9e8c5217-490b-4fe7-8c31-6e2353a3fc98',
-    startedAt: 1755269732792,
-    status: 'running'
-  }
-}
-```
-
-### Foreach progress events
-
-When a workflow uses `.foreach()`, each iteration emits a `workflow-step-progress` event. You can use these to track real-time progress:
-
-```typescript
-for await (const chunk of stream) {
-  if (chunk.type === 'workflow-step-progress') {
-    console.log(
-      `${chunk.payload.id}: ${chunk.payload.completedCount}/${chunk.payload.totalCount} — ${chunk.payload.iterationStatus}`,
-    )
-  }
-}
-```
-
-Each progress event includes:
-
-- **`id`**: The step ID of the foreach step
-- **`completedCount`**: Number of iterations completed so far
-- **`totalCount`**: Total number of iterations
-- **`currentIndex`**: Index of the iteration that completed
-- **`iterationStatus`**: Status of the iteration (`success`, `failed`, or `suspended`)
-- **`iterationOutput`**: Output of the iteration (when successful)

package/.docs/docs/streaming/overview.md

@@ -1,136 +0,0 @@
-# Streaming overview
-
-Mastra supports real-time, incremental responses from agents and workflows, allowing users to see output as it’s generated instead of waiting for completion. This is useful for chat, long-form content, multi-step workflows, or any scenario where immediate feedback matters.
-
-## Getting started
-
-Mastra's streaming API adapts based on your model version:
-
-- **`.stream()`**: For V2 models, supports **AI SDK v5** and later (`LanguageModelV2`).
-- **`.streamLegacy()`**: For V1 models, supports **AI SDK v4** (`LanguageModelV1`).
-
-## Streaming with agents
-
-You can pass a single string for basic prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
-
-### Using `Agent.stream()`
-
-A `textStream` breaks the response into chunks as it's generated, allowing output to stream progressively instead of arriving all at once. Iterate over the `textStream` using a `for await` loop to inspect each stream chunk.
-
-```typescript
-const testAgent = mastra.getAgent('testAgent')
-
-const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
-
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk)
-}
-```
-
-> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
-
-> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
-
-### Output from `Agent.stream()`
-
-The output streams the generated response from the agent.
-
-```text
-Of course!
-To help you organize your day effectively, I need a bit more information.
-Here are some questions to consider:
-...
-```
-
-### Agent stream properties
-
-An agent stream provides access to various response properties:
-
-- **`stream.textStream`**: A readable stream that emits text chunks.
-- **`stream.text`**: Promise that resolves to the full text response.
-- **`stream.finishReason`**: The reason the agent stopped streaming.
-- **`stream.usage`**: Token usage information.
-
-### AI SDK v5+ Compatibility
-
-AI SDK v5 (and later) uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
-
-For integration with AI SDK v5+, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
-
-```typescript
-import { toAISdkV5Stream } from '@mastra/ai-sdk'
-
-const testAgent = mastra.getAgent('testAgent')
-
-const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
-
-// Convert to AI SDK v5+ compatible stream
-const aiSDKStream = toAISdkV5Stream(stream, { from: 'agent' })
-```
-
-For converting messages to AI SDK v5+ format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
-
-```typescript
-import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
-
-const messages = [{ role: 'user', content: 'Hello' }]
-const aiSDKMessages = toAISdkV5Messages(messages)
-```
-
-## Streaming with workflows
-
-Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRun()`.
-
-### Using `Run.stream()`
-
-The `stream()` method returns a `ReadableStream` of events directly.
-
-```typescript
-const run = await testWorkflow.createRun()
-
-const stream = await run.stream({
-  inputData: {
-    value: 'initial data',
-  },
-})
-
-for await (const chunk of stream) {
-  console.log(chunk)
-}
-```
-
-> **Info:** Visit [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream) for more information.
-
-### Output from `Run.stream()`
-
-The event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
-
-```typescript
-{
-  type: 'workflow-start',
-  runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',
-  from: 'WORKFLOW',
-  payload: {
-    stepName: 'step-1',
-    args: { value: 'initial data' },
-    stepCallId: '8e15e618-be0e-4215-a5d6-08e58c152068',
-    startedAt: 1755121710066,
-    status: 'running'
-  }
-}
-```
-
-### Workflow stream properties
-
-A workflow stream provides access to various response properties:
-
-- **`stream.status`**: The status of the workflow run.
-- **`stream.result`**: The result of the workflow run.
-- **`stream.usage`**: The total token usage of the workflow run.
-
-## Related
-
-- [Streaming events](https://mastra.ai/docs/streaming/events)
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
-- [Using Agents](https://mastra.ai/docs/agents/overview)
-- [Workflows overview](https://mastra.ai/docs/workflows/overview)

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,
-    }
-  },
-})
-```