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

package/.docs/raw/streaming/events.mdx

@@ -0,0 +1,115 @@
+---
+title: "Streaming Events | Streaming | Mastra"
+description: "Learn about the different types of streaming events in Mastra, including text deltas, tool calls, step events, and how to handle them in your applications."
+---
+
+# 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 `.streamVNext()`.
+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.
+
+## Inspecting agent streams
+
+Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
+
+```typescript {3,7} showLineNumbers copy
+const testAgent = mastra.getAgent("testAgent");
+
+const stream = await testAgent.streamVNext([
+  { role: "user", content: "Help me organize my day" },
+]);
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> See [Agent.streamVNext()](../../reference/agents/streamVNext.mdx) 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 {2,7,15}
+{
+  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 {5,11} showLineNumbers copy
+const testWorkflow = mastra.getWorkflow("testWorkflow");
+
+const run = await testWorkflow.createRunAsync();
+
+const stream = await run.streamVNext({
+  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 {2,8,11}
+{
+  type: 'start',
+  runId: '221333ed-d9ee-4737-922b-4ab4d9de73e6',
+  from: 'WORKFLOW',
+  // ...
+}
+{
+  type: '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'
+  }
+}
+```

package/.docs/raw/streaming/overview.mdx

@@ -0,0 +1,137 @@
+---
+title: "Streaming Overview | Streaming | Mastra"
+description: "Streaming in Mastra enables real-time, incremental responses from both agents and workflows, providing immediate feedback as AI-generated content is produced."
+---
+
+import { StreamVNextCallout } from "@/components/streamVNext-callout.tsx"
+
+# Streaming Overview
+
+<StreamVNextCallout />
+
+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 currently supports two streaming methods, this page explains how to use `streamVNext()`.
+
+1. **`.stream()`**: Current stable API, supports **AI SDK v4** (`LanguageModelV1`).
+2. **`.streamVNext()`**: Experimental API, supports **AI SDK v5** (`LanguageModelV2`).
+
+## Streaming with agents
+
+You can pass a single string for simple 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.streamVNext()`
+
+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 {3,7} showLineNumbers copy
+const testAgent = mastra.getAgent("testAgent");
+
+const stream = await testAgent.streamVNext([
+  { role: "user", content: "Help me organize my day" },
+]);
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+> See [Agent.streamVNext()](../../reference/agents/streamVNext.mdx) for more information.
+
+### Output from `Agent.streamVNext()`
+
+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
+
+For integration with AI SDK v5, use `format` 'aisdk' to get an `AISDKV5OutputStream`:
+
+```typescript {5} showLineNumbers copy
+const testAgent = mastra.getAgent("testAgent");
+
+const stream = await testAgent.streamVNext(
+  [{ role: "user", content: "Help me organize my day" }],
+  { format: "aisdk" }
+);
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## 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 `.createRunAsync()`.
+
+### Using `Run.streamVNext()`
+
+This is the experimental API. It returns a `ReadableStream` of events directly.
+
+```typescript {3,9} showLineNumbers copy
+const run = await testWorkflow.createRunAsync();
+
+const stream = await run.streamVNext({
+  inputData: {
+    value: "initial data"
+  }
+});
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> See [Run.streamVNext()](../../reference/workflows/run-methods/streamVNext.mdx) for more information.
+
+### Output from `Run.streamVNext()`
+
+The experimental API 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: 'step-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](./events.mdx)
+- [Using Agents](../agents/overview.mdx)
+- [Workflows overview](../workflows/overview.mdx)

package/.docs/raw/streaming/tool-streaming.mdx

@@ -0,0 +1,113 @@
+---
+title: "Tool Streaming | Streaming | Mastra"
+description: "Learn how to use tool streaming in Mastra, including handling tool calls, tool results, and tool execution events during streaming."
+---
+
+import { Callout } from "nextra/components";
+
+# 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 `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 `streamVNext` output directly into a tool’s writer, making it easy 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 {4,10} showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+import { testTool } from "../tools/test-tool";
+
+export const testAgent = new Agent({
+  name: "test-agent",
+  instructions: "You are a weather agent.",
+  model: openai("gpt-4o-mini"),
+  tools: { testTool }
+});
+```
+
+### Using the `writer` argument
+
+The `writer` argument is passed to 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.
+
+<Callout type="warning">
+You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
+</Callout>
+
+```typescript {5,8,15} showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+
+export const testTool = createTool({
+  // ...
+  execute: async ({ context, writer }) => {
+    const { value } = context;
+
+   await writer?.write({
+      type: "custom-event",
+      status: "pending"
+    });
+
+    const response = await fetch(...);
+
+   await writer?.write({
+      type: "custom-event",
+      status: "success"
+    });
+
+    return {
+      value: ""
+    };
+  }
+});
+```
+
+### 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 showLineNumbers copy
+const stream = await testAgent.streamVNext([
+  "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 using an agent
+
+Pipe an agent’s `textStream` to the tool’s `writer`. This streams partial output, and Mastra automatically aggregates the agent’s usage into the tool run.
+
+```typescript showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const testTool = createTool({
+  // ...
+  execute: async ({ context, mastra, writer }) => {
+    const { city } = context;
+
+    const testAgent = mastra?.getAgent("testAgent");
+    const stream = await testAgent?.streamVNext(`What is the weather in ${city}?`);
+
+    await stream!.textStream.pipeTo(writer!);
+
+    return {
+      value: await stream!.text
+    };
+  }
+});
+```
+

package/.docs/raw/streaming/workflow-streaming.mdx

@@ -0,0 +1,97 @@
+---
+title: "Workflow Streaming | Streaming | Mastra"
+description: "Learn how to use workflow streaming in Mastra, including handling workflow execution events, step streaming, and workflow integration with agents and tools."
+---
+
+import { Callout } from "nextra/components";
+
+# 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 `streamVNext` output directly into a workflow step's writer, making it easy 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.
+
+<Callout type="warning">
+You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
+</Callout>
+
+```typescript {5,8,15} showLineNumbers copy
+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 showLineNumbers copy
+const testWorkflow = mastra.getWorkflow("testWorkflow");
+
+const run = await testWorkflow.createRunAsync();
+
+const stream = await run.streamVNext({
+  inputData: {
+    value: "initial data"
+  }
+});
+
+for await (const chunk of stream) {
+  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 showLineNumbers copy
+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?.streamVNext(`What is the weather in ${city}$?`);
+
+    await stream!.textStream.pipeTo(writer!);
+
+    return {
+      value: await stream!.text,
+    };
+  },
+});
+```

package/.docs/raw/tools-mcp/overview.mdx

@@ -3,6 +3,8 @@ title: "Tools Overview | Tools & MCP | Mastra Docs"
 description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
 ---
 
+import { Steps } from "nextra/components";
+
 # Tools Overview
 
 Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
@@ -65,3 +67,45 @@ Some providers that we include this layer for:
 - **DeepSeek & Meta:** Apply similar compatibility logic to ensure schema alignment and tool usability.
 
 This approach makes tool usage more reliable and model-agnostic for both custom and MCP tools.
+
+
+## Testing tools locally
+There are two ways to run and test tools.
+
+<Steps>
+
+### Mastra Playground
+
+With the Mastra Dev Server running you can test a tool from the Mastra Playground by visiting [http://localhost:4111/tools](http://localhost:4111/tools) in your browser.
+
+> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
+
+### Command line
+
+Invoke a tool using `.execute()`.
+
+```typescript filename="src/test-tool.ts" showLineNumbers copy
+import { RuntimeContext } from "@mastra/core/runtime-context";
+import { testTool } from "./mastra/tools/test-tool";
+
+const runtimeContext = new RuntimeContext();
+
+const result = await testTool.execute({
+  context: {
+    value: "foo"
+  },
+  runtimeContext
+});
+
+console.log(result);
+```
+
+> See [createTool()](../../reference/tools/create-tool.mdx) for more information.
+
+To test this tool, run the following:
+
+```bash copy
+npx tsx src/test-tool.ts
+```
+
+</Steps>

package/.docs/raw/workflows/overview.mdx

@@ -130,7 +130,7 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
-### Register workflow
+## Register workflow
 
 Register a workflow using `workflows` in the main Mastra instance:
 
@@ -154,20 +154,24 @@ export const mastra = new Mastra({
 });
 ```
 
-### Run workflow
+## Testing workflows locally
 There are two ways to run and test workflows.
 
 <Steps>
 
-#### Mastra Playground
+### Mastra Playground
 
 With the Mastra Dev Server running you can run the workflow from the Mastra Playground by visiting [http://localhost:4111/workflows](http://localhost:4111/workflows) in your browser.
 
-#### Command line
+> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
 
-Create a run instance of any Mastra workflow using `createRunAsync` and `start`:
+### Command line
+
+Create a workflow run instance using `createRunAsync` and `start`:
 
 ```typescript {3,5} filename="src/test-workflow.ts" showLineNumbers copy
+import "dotenv/config";
+
 import { mastra } from "./mastra";
 
 const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
@@ -178,15 +182,13 @@ const result = await run.start({
   }
 });
 
-// Dump the complete workflow result (includes status, steps and result)
-console.log(JSON.stringify(result, null, 2));
+console.log(result);
 
-// Get the workflow output value
 if (result.status === 'success') {
-  console.log(`output value: ${result.result.output}`);
+  console.log(result.result.output);
 }
 ```
-> see [createRunAsync](/reference/workflows/create-run) and [start](/reference/workflows/run-methods/start) for more information.
+> see [createRunAsync](../../reference/workflows/create-run.mdx) and [start](../../reference/workflows/run-methods/start.mdx) for more information.
 
 To trigger this workflow, run the following:
 
@@ -196,11 +198,11 @@ npx tsx src/test-workflow.ts
 
 </Steps>
 
-#### Run workflow results
+### Run workflow results
 
 The result of running a workflow using either `start()` or `resume()` will look like one of the following, depending on the outcome.
 
-##### Status success
+#### Status success
 
 ```json
 {
@@ -224,7 +226,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 - **result**: Includes the final output of the workflow, typed according to the `outputSchema`
 
 
-##### Status suspended
+#### Status suspended
 
 ```json
 {
@@ -246,7 +248,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 
 - **suspended**: An optional array listing any steps currently awaiting input before continuing
 
-##### Status failed
+#### Status failed
 
 ```json
 {
@@ -264,7 +266,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 ```
 - **error**: An optional field that includes the error message if the workflow fails
 
-### Stream workflow
+## Stream workflow
 
 Similar to the run method shown above, workflows can also be streamed:
 
@@ -286,7 +288,7 @@ for await (const chunk of result.stream) {
 
 > See [stream](/reference/workflows/run-methods/stream) and [messages](/reference/workflows/run-methods/stream#messages) for more information.
 
-### Watch Workflow
+## Watch Workflow
 
 A workflow can also be watched, allowing you to inspect each event that is emitted.
 
@@ -308,7 +310,7 @@ const result = await run.start({
 
 > See [watch](/reference/workflows/run-methods/watch) for more information.
 
-## More resources
+## Related
 
 - The [Workflow Guide](../../guides/guide/ai-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
 - [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)

package/dist/stdio.js

@@ -798,7 +798,11 @@ async function listDirContents(dirPath) {
   }
 }
 async function readMdxContent(docPath, queryKeywords) {
-  const fullPath = path3__default.join(docsBaseDir, docPath);
+  const fullPath = path3__default.resolve(path3__default.join(docsBaseDir, docPath));
+  if (!fullPath.startsWith(path3__default.resolve(docsBaseDir))) {
+    void logger.error(`Path traversal attempt detected`);
+    return { found: false };
+  }
   void logger.debug(`Reading MDX content from: ${fullPath}`);
   try {
     const stats = await fs3.stat(fullPath);

package/dist/tools/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4JxB,eAAO,MAAM,eAAe;;;;;;;;;EAW1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;oBAkBG,SAAS;CAiDhC,CAAC"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgKxB,eAAO,MAAM,eAAe;;;;;;;;;EAW1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;oBAkBG,SAAS;CAiDhC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.17-alpha.2",
+  "version": "0.13.17-alpha.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -30,10 +30,10 @@
     "jsdom": "^26.1.0",
     "turndown": "^7.2.0",
     "uuid": "^11.1.0",
-    "zod": "^3.25.67",
-    "zod-to-json-schema": "^3.24.5",
-    "@mastra/mcp": "^0.11.3-alpha.0",
-    "@mastra/core": "0.15.3-alpha.2"
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6",
+    "@mastra/core": "0.15.3-alpha.4",
+    "@mastra/mcp": "^0.11.3-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.17.1",
@@ -48,8 +48,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.34",
-    "@mastra/core": "0.15.3-alpha.2"
+    "@mastra/core": "0.15.3-alpha.4",
+    "@internal/lint": "0.0.34"
   },
   "scripts": {
     "prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",