@mastra/mcp-docs-server 1.2.14-alpha.3 → 1.2.14-alpha.4

package/.docs/reference/core/addStoredWorkflow.md

@@ -0,0 +1,62 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.addStoredWorkflow()
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+The `.addStoredWorkflow()` method validates a stored workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).
+
+See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup example and the [stored workflow definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) for the accepted fields and graph entries.
+
+## Usage example
+
+```typescript
+await mastra.addStoredWorkflow({
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+})
+
+const run = await mastra.getWorkflow('greeting-workflow').createRun()
+const result = await run.start({ inputData: { name: 'Ada' } })
+```
+
+## Parameters
+
+**def** (`StoredWorkflowGraph`): The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.
+
+## Returns
+
+A promise that resolves once the definition is validated, registered, and persisted.
+
+## Behavior
+
+- The definition is fully validated (structure, references, schema flow) before anything is mutated. Agents, tools, and workflows referenced by the graph must already be registered on the instance.
+- Adding a definition with an existing ID replaces both the stored definition and the live registration. In-flight runs keep the graph they started with.
+- Without a storage adapter that supports the `workflowDefinitions` domain, the workflow is still validated and registered in memory, but the definition is lost on restart.
+- To add a root workflow together with helper workflows it nests, use [`addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows).
+
+## Related
+
+- [Mastra.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows): Add a dependency-ordered bundle of definitions
+- [Mastra.getWorkflow()](https://mastra.ai/reference/core/getWorkflow): Retrieve a registered workflow
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
+- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries

package/.docs/reference/core/addStoredWorkflows.md

@@ -0,0 +1,40 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.addStoredWorkflows()
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+The `.addStoredWorkflows()` method adds a bundle of stored workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.
+
+The whole bundle is validated up front. Members are then registered in dependency order, so a helper is always in place before the workflow that nests it.
+
+[`addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow) is the single-member case.
+
+## Usage example
+
+```typescript
+await mastra.addStoredWorkflows([
+  helperDefinition, // nested by the root — order in the array doesn't matter
+  rootDefinition, // graph contains { type: 'workflow', workflowId: helperDefinition.id }
+])
+```
+
+## Parameters
+
+**defs** (`readonly StoredWorkflowGraph[]`): The workflow definitions to add. Nested-workflow references may resolve against the live registries or against other members of the same bundle.
+
+## Returns
+
+A promise that resolves once every member is validated, registered, and persisted.
+
+## Behavior
+
+- References resolve against the instance's registries union the bundle's own IDs, so a root may nest a helper introduced in the same call. Registration order is derived from the dependency graph, not the array order.
+- A rejected bundle registers nothing. Duplicate IDs, invalid members, and dependency cycles are detected before anything is mutated, and if registration or persistence fails partway, the in-memory registry is restored to its prior state.
+- Storage writes happen last. A storage-level failure mid-bundle can leave some rows written, but the registry is still rolled back and the orphaned rows are inert until the next boot.
+
+## Related
+
+- [Mastra.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow): Add a single definition
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
+- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries

package/.docs/reference/index.md

@@ -83,6 +83,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)
+- [.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow)
+- [.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows)
 - [.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
 - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
@@ -364,8 +366,10 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/workers/overview)
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
+- [Stored Workflow Definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
 - [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
+- [.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)
 - [.branch()](https://mastra.ai/reference/workflows/workflow-methods/branch)
 - [.commit()](https://mastra.ai/reference/workflows/workflow-methods/commit)
 - [.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
@@ -377,6 +381,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.sleep()](https://mastra.ai/reference/workflows/workflow-methods/sleep)
 - [.sleepUntil()](https://mastra.ai/reference/workflows/workflow-methods/sleepUntil)
 - [.then()](https://mastra.ai/reference/workflows/workflow-methods/then)
+- [.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool)
 - [.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel)
 - [.restart()](https://mastra.ai/reference/workflows/run-methods/restart)
 - [.resume()](https://mastra.ai/reference/workflows/run-methods/resume)

package/.docs/reference/processors/processor-interface.md

@@ -58,6 +58,11 @@ Processor methods run at different points in the agent execution lifecycle:
 │  │              ▼                                               │  │
 │  │        Tool Execution (if needed)                            │  │
 │  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processToolResult     │  ← Runs per tool, after each     │  │
+│  │  └───────────┬────────────┘    tool.execute() returns        │  │
+│  │              │                                               │  │
 │  │              └──────── Loop back if tools called ────────────│  │
 │  │                                                              │  │
 │  └──────────────────────────────────────────────────────────────┘  │
@@ -73,16 +78,17 @@ Processor methods run at different points in the agent execution lifecycle:
 └────────────────────────────────────────────────────────────────────┘
 ```
 
-| Method                | When it runs                                                 | Use case                                                                                       |
-| --------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `processInput`        | Once at the start, before the agentic loop                   | Validate/transform initial user input, add context                                             |
-| `processInputStep`    | At each step of the agentic loop, before each LLM call       | Transform messages between steps, handle tool results                                          |
-| `processLLMRequest`   | After LLM request conversion, before the provider call       | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
-| `processAPIError`     | When an LLM API call fails                                   | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
-| `processOutputStream` | On each streaming chunk during LLM response                  | Filter/modify streaming content, detect patterns in real-time                                  |
-| `processLLMResponse`  | After the LLM step completes and stream chunks are collected | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
-| `processOutputStep`   | After each LLM response, before tool execution               | Validate output quality, implement guardrails with retry                                       |
-| `processOutputResult` | Once after generation completes                              | Post-process final response, log results                                                       |
+| Method                | When it runs                                                                                | Use case                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `processInput`        | Once at the start, before the agentic loop                                                  | Validate/transform initial user input, add context                                             |
+| `processInputStep`    | At each step of the agentic loop, before each LLM call                                      | Transform messages between steps, handle tool results                                          |
+| `processLLMRequest`   | After LLM request conversion, before the provider call                                      | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes   |
+| `processAPIError`     | When an LLM API call fails                                                                  | Inspect API rejections, optionally mutate state/messages, and request a retry                  |
+| `processOutputStream` | On each streaming chunk during LLM response                                                 | Filter/modify streaming content, detect patterns in real-time                                  |
+| `processLLMResponse`  | After the LLM step completes and stream chunks are collected                                | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
+| `processOutputStep`   | After each LLM response, before tool execution                                              | Validate output quality, implement guardrails with retry                                       |
+| `processToolResult`   | Per tool, after `tool.execute()` returns and before the result is added to the message list | Scan tool output for prompt injection, redact sensitive fields, abort on policy violations     |
+| `processOutputResult` | Once after generation completes                                                             | Post-process final response, log results                                                       |
 
 ## Interface definition
 
@@ -131,6 +137,8 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
 
   processOutputStep?(args: ProcessOutputStepArgs<TTripwireMetadata>): ProcessorMessageResult
 
+  processToolResult?(args: ProcessToolResultArgs<TTripwireMetadata>): ProcessorMessageResult
+
   processOutputResult?(args: ProcessOutputResultArgs<TTripwireMetadata>): ProcessorMessageResult
 }
 ```
@@ -698,6 +706,109 @@ export class QualityGuardrail implements Processor {
 }
 ```
 
+### `processToolResult`
+
+Processes a tool's result after `tool.execute()` returns and before the result is added to the message list or fed to the next LLM call. Symmetric with `processOutputStep`, which fires before tool execution. Use this method to scan tool output for prompt injection, redact sensitive fields, or abort the run with `abort('reason', { retry: true })`.
+
+To replace the tool's result, mutate `messageList` in place via `messageList.updateToolInvocation`. The runtime re-reads the post-processor result from the message list and overwrites the downstream tool-result stream chunk before it is enqueued, so streaming clients see the processed value.
+
+This method does not fire when `tool.execute()` throws; it is called only for successful tool executions where a result is available.
+
+```typescript
+processToolResult?(args: ProcessToolResultArgs): ProcessorMessageResult;
+```
+
+#### `ProcessToolResultArgs`
+
+**messages** (`MastraDBMessage[]`): All messages including the current assistant message with the tool call.
+
+**messageList** (`MessageList`): MessageList instance for managing messages. Call updateToolInvocation to replace the tool result with a redacted or transformed value.
+
+**stepNumber** (`number`): Current step number (0-indexed).
+
+**toolName** (`string`): Name of the tool that was executed.
+
+**toolCallId** (`string`): Unique identifier for this specific tool call.
+
+**args** (`unknown`): Arguments the LLM passed to the tool.
+
+**result** (`unknown`): Value returned by the tool. For client-executed tools this is the output of tool.execute() after it has passed through ensureSerializable. For provider-executed tools (e.g. Anthropic web\_search) it is the raw result from the provider stream, which is not run through ensureSerializable.
+
+**providerExecuted** (`boolean`): Whether this result came from a provider-executed tool such as Anthropic web\_search. Defaults to undefined for client-executed tools.
+
+**systemMessages** (`CoreMessage[]`): All system messages for read access.
+
+**steps** (`StepResult[]`): All completed steps so far.
+
+**state** (`Record<string, unknown>`): Per-processor state that persists across all method calls within this request. Shared with other processor methods on the same processor.
+
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort the run. Pass retry: true to request the LLM retry the step with the abort reason as feedback.
+
+**retryCount** (`number`): Number of times processors have triggered retry. Starts at 0.
+
+**tracingContext** (`TracingContext`): Tracing context for observability.
+
+**requestContext** (`RequestContext`): Request-scoped context with execution metadata.
+
+#### Use cases
+
+- Scanning tool output for prompt injection before the LLM sees it.
+- Redacting sensitive fields from tool returns (PII, secrets, credentials).
+- Aborting the run when a tool returns content that violates policy.
+- Logging or instrumenting tool returns for compliance or audit.
+
+#### Example: Redact sensitive fields
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class RedactToolResult implements Processor {
+  id = 'redact-tool-result'
+
+  async processToolResult({ toolName, toolCallId, args, result, messageList }) {
+    if (toolName !== 'lookup-customer') return
+
+    const redacted = {
+      ...(result as Record<string, unknown>),
+      ssn: '[REDACTED]',
+      email: '[REDACTED]',
+    }
+
+    messageList.updateToolInvocation({
+      type: 'tool-invocation',
+      toolInvocation: {
+        state: 'result',
+        toolCallId,
+        toolName,
+        args,
+        result: redacted,
+      },
+    })
+  }
+}
+```
+
+#### Example: Block prompt injection in tool output
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class ScanToolResult implements Processor {
+  id = 'scan-tool-result'
+
+  async processToolResult({ result, abort }) {
+    const text = typeof result === 'string' ? result : JSON.stringify(result)
+    if (containsPromptInjection(text)) {
+      abort('blocked by scan-tool-result: suspected prompt injection')
+    }
+  }
+}
+
+function containsPromptInjection(text: string): boolean {
+  return /ignore (all )?(previous|prior) instructions/i.test(text)
+}
+```
+
 ## Processor types
 
 Mastra provides type aliases to ensure processors implement the required methods:

package/.docs/reference/server/routes.md

@@ -183,6 +183,19 @@ The route returns:
 | `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
 | `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
 
+### Stored workflows
+
+Stored workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows).
+
+| Method   | Path                                      | Description                                                                    |
+| -------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/stored/workflows`                   | List stored workflow definitions, filterable by `status` and `authorId`        |
+| `GET`    | `/api/stored/workflows/:storedWorkflowId` | Get a stored workflow definition by ID                                         |
+| `POST`   | `/api/stored/workflows`                   | Upsert a definition (plus optional helper `dependencies`) and live-register it |
+| `DELETE` | `/api/stored/workflows/:storedWorkflowId` | Delete a stored definition and unregister the live workflow                    |
+
+On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered stored workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
+
 ### Create run request body
 
 ```typescript

package/.docs/reference/storage/overview.md

@@ -10,14 +10,15 @@ Mastra storage is organized into domains. Each domain owns a set of tables or co
 
 Not every storage adapter implements every domain. Composite storage lets you mix adapters per domain when the adapter packages export the corresponding domain classes.
 
-| Domain          | Description                                                                            |
-| --------------- | -------------------------------------------------------------------------------------- |
-| `memory`        | Conversation persistence: messages, threads, and resources (including working memory). |
-| `workflows`     | Workflow run snapshots used for suspend and resume.                                    |
-| `scores`        | Evaluation score records from eval runs.                                               |
-| `observability` | Traces and spans used by observability exporters and Studio.                           |
-| `datasets`      | Dataset records, versioned items, and dataset versions used by experiments.            |
-| `experiments`   | Experiment runs and per-item experiment results.                                       |
+| Domain                | Description                                                                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                 |
+| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                    |
+| `workflowDefinitions` | Persisted [stored workflow](https://mastra.ai/docs/workflows/stored-workflows) definitions (beta). Loaded and live-registered on boot. |
+| `scores`              | Evaluation score records from eval runs.                                                                                               |
+| `observability`       | Traces and spans used by observability exporters and Studio.                                                                           |
+| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                            |
+| `experiments`         | Experiment runs and per-item experiment results.                                                                                       |
 
 The schema definitions below cover the built-in database-backed tables documented for `memory`, `workflows`, `scores`, and `observability`. Other domains, and non-database adapters, use implementation-specific storage structures.
 

package/.docs/reference/streaming/workflows/observeStream.md

@@ -34,7 +34,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-start`**: A step begins execution
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result
 
 ## Related
 

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -66,7 +66,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-start`**: A step begins execution
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result
 
 ## Related
 

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

@@ -93,7 +93,7 @@ The stream emits event types during workflow execution. Each event has a `type`
 - **`workflow-step-output`**: Custom output from a step
 - **`workflow-step-progress`**: A foreach step reports per-iteration progress (includes `completedCount`, `totalCount`, `currentIndex`, `iterationStatus`, and optional `iterationOutput`)
 - **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
+- **`workflow-finish`**: Workflow execution completes with usage statistics. For successful runs, `payload.finalWorkflowResult` carries the workflow's final result so stream consumers don't need a follow-up fetch
 
 ## Related