@mastra/mcp-docs-server 1.2.4-alpha.1 → 1.2.4-alpha.6

package/.docs/reference/storage/retention.md

@@ -0,0 +1,180 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage retention
+
+Storage grows without bound by default. Retention is an opt-in, age-based cleanup system: you declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Anything you don't configure is kept forever, so there is no behavior change until you opt in.
+
+`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk — on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+
+Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they are not valid retention keys.
+
+The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
+
+## Usage example
+
+Declare `retention` on any `MastraCompositeStore` (or an adapter that extends it, such as `LibSQLStore`), then call `prune()` from your own scheduler.
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+const storage = new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+  retention: {
+    memory: {
+      messages: { maxAge: '30d' },
+      threads: { maxAge: '90d', batchSize: 500 },
+    },
+    observability: {
+      spans: { maxAge: '7d' },
+    },
+  },
+})
+
+// Wire this to your own cron/scheduler — Mastra never runs it for you.
+const results = await storage.prune()
+```
+
+`retention` is fully typed. Keys must be real domain keys, and each table key must be one the domain declares as retention-eligible. Passing the object straight into a store config type-checks it; if you build it standalone, use `satisfies RetentionConfig` so unknown domains or tables are compile errors:
+
+```typescript
+import type { RetentionConfig } from '@mastra/core/storage'
+
+const retention = {
+  memory: {
+    messages: { maxAge: '30d' }, // ok
+    bogus: { maxAge: '30d' }, // Error: not a memory retention table
+  },
+  bogusDomain: {}, // Error: not a storage domain
+} satisfies RetentionConfig
+```
+
+## Retention config
+
+Set the `retention` field on the store config.
+
+**retention** (`RetentionConfig`): Per-domain, per-table age policies. Unset domains and tables are kept forever.
+
+**retention.\[domain]** (`Record<TableKey, TableRetentionPolicy>`): A real storage domain key (e.g. \`memory\`, \`observability\`). Maps that domain's retention-eligible table keys to their policies.
+
+### TableRetentionPolicy
+
+**maxAge** (`Duration`): Maximum age to keep rows. Rows whose anchor timestamp is strictly older than \`Date.now() - maxAge\` are eligible for deletion. A number is milliseconds, or a string with a unit suffix: \`ms\`, \`s\`, \`m\`, \`h\`, \`d\`, \`w\` (e.g. \`'30d'\`, \`'12h'\`).
+
+**batchSize** (`number`): Rows deleted per batch. Each batch is its own transaction, which bounds lock duration and WAL growth on large tables. (Default: `1000`)
+
+### Retention-eligible tables
+
+Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data: creation time for append-only logs, last activity for live state, and completion time for jobs and runs (so in-flight work is never pruned).
+
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                 |
+| ----------------- | ------------------ | ---------------- | ----------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                        |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                       |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                      |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity — state for still-active threads survives              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                          |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                  |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                  |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity — suspended or long-running workflows survive          |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion — in-flight tasks (`NULL`) are never pruned |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion — running experiments are never pruned      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                  |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                                |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                |
+
+> **Note:**
+>
+> - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
+> - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. There is no separate `results` key.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and are not pruned.
+> - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
+> - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
+> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows — effective granularity is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
+
+## Methods
+
+### Retention
+
+#### `prune(options?)`
+
+Deletes rows older than their configured `maxAge` across every domain that has a policy in `retention`. Returns one `PruneResult` per table touched. With no `retention` configured it's a no-op returning `[]`.
+
+`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
+
+Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
+
+```typescript
+const results = await storage.prune({
+  maxRows: 50_000, // cap work this call
+  pauseMs: 50, // breathe between batches
+})
+
+for (const r of results) {
+  console.log(`${r.domain}.${r.table}: deleted ${r.deleted}, done=${r.done}`)
+}
+```
+
+Returns: `Promise<PruneResult[]>`
+
+##### PruneOptions
+
+**maxBatches** (`number`): Maximum delete batches per table per call. When reached, that table's result is returned with \`done: false\`.
+
+**maxRows** (`number`): Maximum rows deleted per table per call. When reached, that table's result is returned with \`done: false\`.
+
+**pauseMs** (`number`): Delay in milliseconds between batches, to avoid starving live traffic.
+
+**signal** (`AbortSignal`): Cooperative cancellation. The batch loop checks it between batches and stops cleanly, returning partial results with \`done: false\`.
+
+##### PruneResult
+
+Each result describes one table's progress:
+
+```typescript
+interface PruneResult {
+  domain: string // e.g. 'memory'
+  table: string // physical table name, e.g. 'mastra_messages'
+  deleted: number // rows deleted during this call
+  done: boolean // false => eligible rows remain; call prune() again
+}
+```
+
+## Running prune on a schedule
+
+`prune()` has no built-in scheduler — you decide when it runs. Because it is bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+
+```typescript
+// Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).
+async function retentionTick() {
+  const results = await storage.prune({ maxRows: 100_000, pauseMs: 25 })
+  const incomplete = results.filter(r => !r.done)
+  if (incomplete.length) {
+    // Rows remain; the next scheduled tick will continue where this one stopped.
+    console.log(
+      'retention still draining:',
+      incomplete.map(r => `${r.domain}.${r.table}`),
+    )
+  }
+}
+```
+
+You can also cancel a long-running prune with an `AbortSignal` — the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
+
+## Reclaiming disk
+
+`prune()` deletes rows but does not shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing — for most users this alone solves the unbounded-growth problem.
+
+Handing that free space back to the OS is a separate concern that Mastra does not manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself, in a maintenance window — a full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+
+> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/reference/storage/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
+
+## Related
+
+- [libSQL storage](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL storage](https://mastra.ai/reference/storage/postgresql)
+- [Composite storage](https://mastra.ai/reference/storage/composite)
+- [Storage overview](https://mastra.ai/reference/storage/overview)

package/.docs/reference/storage/spanner.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Google Cloud Spanner storage
 
 The Google Cloud Spanner storage implementation provides a horizontally scalable, strongly consistent storage backend for Mastra. It targets the GoogleSQL dialect of Cloud Spanner.

package/.docs/reference/storage/upstash.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Upstash storage
 
 The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ChunkType
 
 The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MastraModelOutput
 
 The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent.stream()
 
 The `.stream()` method enables real-time streaming of responses from an agent with enhanced capabilities and format flexibility. This method accepts messages and optional streaming options, providing a next-generation streaming experience with support for both Mastra's native format and AI SDK v5+ compatibility.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent.streamLegacy() (Legacy)
 
 > **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for details on upgrading.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent.streamUntilIdle()
 
 **Added in:** `@mastra/core@1.29.0`

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Run.observeStream()
 
 The `.observeStream()` method opens a new `ReadableStream` to a workflow run that's currently running, allowing you to observe the stream of events if the original stream is no longer available.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Run.resumeStream()
 
 The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Run.stream()
 
 The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Run.timeTravelStream()
 
 The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.

package/.docs/reference/templates/overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Overview
 
 This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
@@ -201,6 +203,7 @@ We recommend using OpenAI, Anthropic, or Google model providers for templates. C
 import { Agent } from '@mastra/core/agent'
 
 const agent = new Agent({
+  id: 'example-agent',
   name: 'example-agent',
   model: 'openai/gpt-5.5', // or other provider strings
   instructions: 'Your agent instructions here',

package/.docs/reference/tools/brightdata.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Bright Data tools
 
 The `@mastra/brightdata` package wraps the [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) as Mastra-compatible tools. It exposes factory functions for web search and web fetch — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.

package/.docs/reference/tools/create-code-mode.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createCodeMode()
 
 **Added in:** `@mastra/core@1.38.0`
@@ -40,6 +42,7 @@ const { tool, instructions } = createCodeMode({
 })
 
 export const shopAgent = new Agent({
+  id: 'shop-assistant',
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
   model: 'openai/gpt-5.5',

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createTool()
 
 The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
@@ -27,6 +29,66 @@ export const tool = createTool({
 })
 ```
 
+## Parameters
+
+**id** (`string`): A unique identifier for the tool.
+
+**description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
+
+**inputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected input parameters for the tool's \`execute\` function.
+
+**outputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected output structure of the tool's \`execute\` function.
+
+**strict** (`boolean`): When true, Mastra enables strict tool input generation on model adapters that support it. This helps supported providers return arguments that match the tool schema more closely.
+
+**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.
+
+**requireApproval** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
+
+**mcp** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
+
+**requestContextSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
+
+**execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
+
+**execute.input** (`z.infer<TInput>`): The validated input data based on inputSchema
+
+**execute.context** (`ToolExecutionContext`): Optional execution context containing metadata
+
+**execute.context.requestContext** (`RequestContext`): Request Context for accessing shared state and dependencies
+
+**execute.context.tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata
+
+**execute.context.abortSignal** (`AbortSignal`): Signal for aborting the tool execution
+
+**execute.context.agent** (`AgentToolExecutionContext`): Agent-specific context, available when the tool is executed by an agent.
+
+**execute.context.workflow** (`WorkflowToolExecutionContext`): Workflow-specific context (state, setState, suspend, etc.)
+
+**execute.context.mcp** (`MCPToolExecutionContext`): MCP-specific context (elicitation, etc.)
+
+**execute.context.observe** (`ToolObserve`): Observability helpers for recording child spans and structured logs from inside a tool's execute function. Always provided — when no tracing context is active, \`span\` runs the function directly and \`log\` is a no-op.
+
+**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+## Returns
+
+The `createTool()` function returns a `Tool` object.
+
+**Tool** (`object`): An object representing the defined tool, ready to be added to an agent.
+
 ## Define schemas
 
 You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
@@ -254,64 +316,6 @@ export const weatherTool = createTool({
 })
 ```
 
-## Parameters
-
-**id** (`string`): A unique identifier for the tool.
-
-**description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
-
-**inputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected input parameters for the tool's \`execute\` function.
-
-**outputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected output structure of the tool's \`execute\` function.
-
-**strict** (`boolean`): When true, Mastra enables strict tool input generation on model adapters that support it. This helps supported providers return arguments that match the tool schema more closely.
-
-**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.
-
-**requireApproval** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
-
-**mcp** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
-
-**requestContextSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
-
-**execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
-
-**execute.input** (`z.infer<TInput>`): The validated input data based on inputSchema
-
-**execute.context** (`ToolExecutionContext`): Optional execution context containing metadata
-
-**execute.context.requestContext** (`RequestContext`): Request Context for accessing shared state and dependencies
-
-**execute.context.tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata
-
-**execute.context.abortSignal** (`AbortSignal`): Signal for aborting the tool execution
-
-**execute.context.agent** (`AgentToolExecutionContext`): Agent-specific context, available when the tool is executed by an agent.
-
-**execute.context.workflow** (`WorkflowToolExecutionContext`): Workflow-specific context (state, setState, suspend, etc.)
-
-**execute.context.mcp** (`MCPToolExecutionContext`): MCP-specific context (elicitation, etc.)
-
-**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
-
-## Returns
-
-The `createTool()` function returns a `Tool` object.
-
-**Tool** (`object`): An object representing the defined tool, ready to be added to an agent.
-
 ## Tool lifecycle hooks
 
 Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.

package/.docs/reference/tools/document-chunker-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createDocumentChunkerTool()
 
 The `createDocumentChunkerTool()` function creates a tool for splitting documents into smaller chunks for efficient processing and retrieval. It supports different chunking strategies and configurable parameters.

package/.docs/reference/tools/graph-rag-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createGraphRAGTool()
 
 The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph of semantic relationships between documents. It uses the `GraphRAG` system under the hood to provide graph-based retrieval, finding relevant content through both direct similarity and connected relationships.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MCPClient
 
 The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
@@ -1063,6 +1065,7 @@ const mcpClient = new MCPClient({
 
 // Use with an agent — requestContext is automatically forwarded
 const agent = new Agent({
+  id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant.',
   model: openai('gpt-5.4'),

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MCPServer
 
 The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. This allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect to these capabilities and make them available to an agent.
@@ -112,7 +114,7 @@ When you provide agents in the `agents` configuration property, `MCPServer` will
 
 The description for this generated tool will be: "Ask agent `<agent.name>` a question. Agent description: `<agent.description>`".
 
-**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
+**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
 
 This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
 

package/.docs/reference/tools/perplexity.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Perplexity tools
 
 The `@mastra/perplexity` package wraps the [Perplexity Search API](https://docs.perplexity.ai/docs/search/quickstart) as a Mastra-compatible tool. It exposes a factory function that returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) and full Zod input/output schemas.

package/.docs/reference/tools/tavily.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Tavily tools
 
 The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.

package/.docs/reference/tools/vector-query-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createVectorQueryTool()
 
 The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.

package/.docs/reference/vectors/astra.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Astra vector store
 
 The AstraVector class provides vector search using [DataStax Astra DB](https://www.datastax.com/products/datastax-astra), a cloud-native, serverless database built on Apache Cassandra. It provides vector search capabilities with enterprise-grade scalability and high availability.

package/.docs/reference/vectors/chroma.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Chroma vector store
 
 The ChromaVector class provides vector search using [Chroma](https://docs.trychroma.com/docs/overview/getting-started), an open-source embedding database. It offers efficient vector search with metadata filtering and hybrid search capabilities.

package/.docs/reference/vectors/convex.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Convex vector store
 
 The `ConvexVector` class provides vector storage and similarity search using [Convex](https://convex.dev). It stores embeddings inside Convex and performs cosine similarity search in the Mastra adapter.

package/.docs/reference/vectors/couchbase.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Couchbase vector store
 
 The `CouchbaseVector` class provides vector search using [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html). It enables efficient similarity search and metadata filtering within your Couchbase collections.

package/.docs/reference/vectors/duckdb.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DuckDB vector store
 
 The DuckDB storage implementation provides an embedded high-performance vector search solution using [DuckDB](https://duckdb.org/), an in-process analytical database. It uses the VSS extension for vector similarity search with HNSW indexing, offering a lightweight and efficient vector database that requires no external server.

package/.docs/reference/vectors/elasticsearch.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Elasticsearch vector store
 
 The `ElasticSearchVector` class provides vector search using [Elasticsearch](https://www.elastic.co/elasticsearch/) with its `dense_vector` field type and k-NN search capabilities. It's part of the `@mastra/elasticsearch` package.

package/.docs/reference/vectors/lance.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Lance vector store
 
 The LanceVectorStore class provides vector search using [LanceDB](https://lancedb.github.io/lancedb/), an embedded vector database built on the Lance columnar format. It offers efficient storage and fast similarity search for both local development and production deployments.

package/.docs/reference/vectors/libsql.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # libSQL vector store
 
 The libSQL storage implementation provides a SQLite-compatible vector search [libSQL](https://github.com/tursodatabase/libsql), a fork of SQLite with vector extensions, and [Turso](https://turso.tech/) with vector extensions, offering a lightweight and efficient vector database solution. It's part of the `@mastra/libsql` package and offers efficient vector similarity search with metadata filtering.

package/.docs/reference/vectors/mongodb.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MongoDB vector store
 
 The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.

package/.docs/reference/vectors/opensearch.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # OpenSearch vector store
 
 The OpenSearchVector class provides vector search using [OpenSearch](https://opensearch.org/), an open-source search and analytics engine. It uses OpenSearch's k-NN capabilities to perform vector similarity search.

package/.docs/reference/vectors/pg.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PG vector store
 
 The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.

package/.docs/reference/vectors/pinecone.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Pinecone vector store
 
 The PineconeVector class provides an interface to [Pinecone](https://www.pinecone.io/)'s vector database. It provides real-time vector search, with features like hybrid search, metadata filtering, and namespace management.

package/.docs/reference/vectors/qdrant.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Qdrant vector store
 
 The QdrantVector class provides vector search using [Qdrant](https://qdrant.tech/), a vector similarity search engine. It provides a production-ready service with a convenient API to store, search, and manage vectors with additional payload and extended filtering support.

package/.docs/reference/vectors/s3vectors.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Amazon S3 vectors store
 
 The `S3Vectors` class provides vector search using [Amazon S3 Vectors (Preview)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html). It stores vectors in **vector buckets** and performs similarity search in **vector indexes**, with JSON-based metadata filters.

package/.docs/reference/vectors/turbopuffer.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Turbopuffer vector store
 
 The TurbopufferVector class provides vector search using [Turbopuffer](https://turbopuffer.com/), a high-performance vector database optimized for RAG applications. Turbopuffer offers fast vector similarity search with advanced filtering capabilities and efficient storage management.

package/.docs/reference/vectors/upstash.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Upstash vector store
 
 The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.