@mastra/mcp-docs-server 1.2.24-alpha.9 → 1.2.24

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

@@ -8,89 +8,27 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-Processor methods run at different points in the agent execution lifecycle:
-
-```text
-┌────────────────────────────────────────────────────────────────────┐
-│                        Agent Execution Flow                        │
-├────────────────────────────────────────────────────────────────────┤
-│                                                                    │
-│  User Input                                                        │
-│      │                                                             │
-│      ▼                                                             │
-│  ┌────────────────────────┐                                        │
-│  │  processInput          │  ← Runs ONCE at start                  │
-│  └───────────┬────────────┘                                        │
-│              │                                                     │
-│              ▼                                                     │
-│  ┌──────────────────────────────────────────────────────────────┐  │
-│  │                        Agentic Loop                          │  │
-│  │                                                              │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processInputStep      │  ← Runs at EACH step             │  │
-│  │  └───────────┬────────────┘                                  │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processLLMRequest     │  ← Before provider call          │  │
-│  │  └───────────┬────────────┘                                  │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │        LLM Execution ──── API Error? ───┐                    │  │
-│  │              │                          │                    │  │
-│  │              │              ┌───────────┴──────────┐         │  │
-│  │              │              │  processAPIError     │         │  │
-│  │              │              └──────────────────────┘         │  │
-│  │              │                (retry loops back to LLM)      │  │
-│  │              ▼                                               │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processOutputStream   │  ← Runs on EACH stream chunk     │  │
-│  │  └───────────┬────────────┘                                  │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processLLMResponse    │  ← After stream completes        │  │
-│  │  └───────────┬────────────┘                                  │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processOutputStep     │  ← Runs after EACH LLM step      │  │
-│  │  └───────────┬────────────┘                                  │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │        Tool Execution (if needed)                            │  │
-│  │              │                                               │  │
-│  │              ▼                                               │  │
-│  │  ┌────────────────────────┐                                  │  │
-│  │  │  processToolResult     │  ← Runs per tool, after each     │  │
-│  │  └───────────┬────────────┘    tool.execute() returns        │  │
-│  │              │                                               │  │
-│  │              └──────── Loop back if tools called ────────────│  │
-│  │                                                              │  │
-│  └──────────────────────────────────────────────────────────────┘  │
-│              │                                                     │
-│              ▼                                                     │
-│  ┌────────────────────────┐                                        │
-│  │  processOutputResult   │  ← Runs ONCE after completion          │
-│  └────────────────────────┘                                        │
-│              │                                                     │
-│              ▼                                                     │
-│        Final Response                                              │
-│                                                                    │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-| 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 a locally executed tool returns or a provider-executed result arrives, before the raw result is persisted to `messageList` | Inspect tool output and enforce security policies                                              |
-| `processOutputResult` | Once after generation completes                                                                                                            | Post-process final response, log results                                                       |
+For a conceptual walkthrough of preparation, the agent loop, tool execution, and finalization, see the [agent lifecycle guide](https://mastra.ai/docs/guides/agent-lifecycle).
+
+## Callback timing
+
+| Callback or operation                                                    | Frequency                                                           | Position and visibility                                                                                                          |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `processInput`                                                           | Once per initial request                                            | During input preparation before the loop. Resuming from a durable snapshot may skip it.                                          |
+| `processInputStep`                                                       | Once per model step                                                 | Before the provider request. It sees messages and tool results accumulated so far.                                               |
+| `processLLMRequest`                                                      | Once per provider call                                              | Last processor stage for rewriting the provider-facing prompt. Its prompt changes aren't written back to the message list.       |
+| `processOutputStream`                                                    | Per streamed chunk                                                  | Runs while model output arrives. Data chunks are included when the processor opts in.                                            |
+| `processLLMResponse`                                                     | Once per completed provider stream                                  | Receives the completed response for the current model step.                                                                      |
+| `processOutputStep`                                                      | Once per model step                                                 | Runs after the model response and before locally executed tools.                                                                 |
+| Tool [`onInputStart`](https://mastra.ai/reference/tools/create-tool)     | When streamed tool input begins                                     | Runs before complete tool arguments are available.                                                                               |
+| Tool [`onInputDelta`](https://mastra.ai/reference/tools/create-tool)     | Per streamed tool-input chunk                                       | Observes incremental tool arguments.                                                                                             |
+| Tool [`onInputAvailable`](https://mastra.ai/reference/tools/create-tool) | Once when tool input is complete                                    | Runs after arguments are parsed and validated, before execution.                                                                 |
+| Tool execution                                                           | Once per local tool call                                            | Receives the live [`RequestContext`](https://mastra.ai/docs/server/request-context). Approval or suspension can delay execution. |
+| Tool [`onOutput`](https://mastra.ai/reference/tools/create-tool)         | Once after successful local execution                               | Receives the tool output.                                                                                                        |
+| `processToolResult`                                                      | Per local/client result, or when a deferred provider result arrives | Can inspect, redact, or abort before a raw tool result enters the message list.                                                  |
+| `processAPIError`                                                        | On eligible provider API errors                                     | Can update request state and request another provider attempt.                                                                   |
+| [`onIterationComplete`](https://mastra.ai/reference/agents/generate)     | Once after each completed loop iteration                            | Observes the iteration result and can influence whether execution continues.                                                     |
+| `processOutputResult`                                                    | Once at finalization                                                | Post-processes the completed agent result before it's returned.                                                                  |
 
 ## Interface definition
 

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

@@ -372,25 +372,50 @@ On authenticated servers, the read routes require the `stored-workflows:read` pe
 
 ## Datasets and experiments
 
-| Method   | Path                                                                   | Description                                                               |
-| -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `GET`    | `/api/datasets`                                                        | List datasets                                                             |
-| `POST`   | `/api/datasets`                                                        | Create a dataset                                                          |
-| `GET`    | `/api/datasets/:datasetId`                                             | Get dataset by ID                                                         |
-| `PATCH`  | `/api/datasets/:datasetId`                                             | Update a dataset                                                          |
-| `DELETE` | `/api/datasets/:datasetId`                                             | Delete a dataset                                                          |
-| `GET`    | `/api/datasets/:datasetId/items`                                       | List dataset items                                                        |
-| `POST`   | `/api/datasets/:datasetId/items`                                       | Add a dataset item                                                        |
-| `GET`    | `/api/experiments`                                                     | List experiments across datasets                                          |
-| `GET`    | `/api/datasets/:datasetId/experiments`                                 | List experiments for a dataset                                            |
-| `POST`   | `/api/datasets/:datasetId/experiments`                                 | Trigger an experiment, or create one without starting it (`start: false`) |
-| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/items/:itemId/run` | Execute one experiment item server-side                                   |
-| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/results`           | Submit an externally computed item result                                 |
-| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/finalize`          | Finalize a caller-driven experiment                                       |
-| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId`                   | Get experiment by ID                                                      |
-| `PATCH`  | `/api/datasets/:datasetId/experiments/:experimentId`                   | Update an experiment's name, description or metadata                      |
-| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId/results`           | List experiment results                                                   |
-| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two experiments                                                   |
+| Method   | Path                                                                   | Description                                                                                 |
+| -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `GET`    | `/api/datasets`                                                        | List datasets                                                                               |
+| `POST`   | `/api/datasets`                                                        | Create a dataset                                                                            |
+| `GET`    | `/api/datasets/:datasetId`                                             | Get dataset by ID                                                                           |
+| `PATCH`  | `/api/datasets/:datasetId`                                             | Update a dataset                                                                            |
+| `DELETE` | `/api/datasets/:datasetId`                                             | Delete a dataset                                                                            |
+| `GET`    | `/api/datasets/:datasetId/items`                                       | List dataset items                                                                          |
+| `POST`   | `/api/datasets/:datasetId/items`                                       | Add a dataset item                                                                          |
+| `DELETE` | `/api/datasets/:datasetId/items/:itemId/purge`                         | Permanently scrub an item's content from every dataset version and linked experiment result |
+| `GET`    | `/api/experiments`                                                     | List experiments across datasets                                                            |
+| `DELETE` | `/api/experiments/:experimentId`                                       | Delete an experiment, including one orphaned by dataset deletion                            |
+| `GET`    | `/api/datasets/:datasetId/experiments`                                 | List experiments for a dataset                                                              |
+| `POST`   | `/api/datasets/:datasetId/experiments`                                 | Trigger an experiment, or create one without starting it (`start: false`)                   |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/items/:itemId/run` | Execute one experiment item server-side                                                     |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/results`           | Submit an externally computed item result                                                   |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/finalize`          | Finalize a caller-driven experiment                                                         |
+| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId`                   | Get experiment by ID                                                                        |
+| `PATCH`  | `/api/datasets/:datasetId/experiments/:experimentId`                   | Update an experiment's name, description or metadata                                        |
+| `DELETE` | `/api/datasets/:datasetId/experiments/:experimentId`                   | Delete an experiment that belongs to the dataset                                            |
+| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId/results`           | List experiment results                                                                     |
+| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two experiments                                                                     |
+
+### Delete an experiment
+
+Both delete routes remove the experiment and its result records. When storage supports observability and trace deletion, Mastra also removes the traces produced by the experiment together with their spans and trace-linked signals.
+
+Use the dataset-scoped route when you know the owning dataset:
+
+```bash
+curl -X DELETE http://localhost:4111/api/datasets/dataset-id/experiments/experiment-id
+```
+
+The route accepts optional `organizationId` and `projectId` query parameters. It returns `404` if the dataset is outside the supplied tenancy, the experiment doesn't exist, or the experiment doesn't belong to the dataset.
+
+Use the top-level route when you don't have a dataset reference, including when dataset deletion has orphaned the experiment by clearing its `datasetId`:
+
+```bash
+curl -X DELETE http://localhost:4111/api/experiments/experiment-id
+```
+
+The top-level route accepts optional `organizationId` and `projectId` query parameters. When either is present, deletion is limited to that tenancy. A tenancy mismatch returns `{ "success": true }` without deleting the experiment. Without tenancy parameters, a missing experiment returns `404`.
+
+A successful deletion returns `{ "success": true }`. The top-level route returns the same response for a tenancy mismatch, but doesn't delete anything. Both routes return `501` unless the installed `@mastra/core` advertises support through the `experiment-deletion` feature flag, including when an older version predates this support. When storage lacks observability or trace deletion support, Mastra logs a warning, leaves the traces in place, and still deletes the experiment with its result records. If trace cleanup fails after an earlier batch succeeds, the route returns `500` and preserves the experiment and result records even though some traces may already have been removed.
 
 ### Caller-driven experiment routes
 

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

@@ -61,7 +61,7 @@ const graphTool = createGraphRAGTool({
 
 The tool returns an object with:
 
-**relevantContext** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
+**relevantContext** (`string[]`): Array of chunk text strings for the most relevant document chunks, in rank order, retrieved using graph-based ranking. Text is read from the text field of each chunk's metadata.
 
 **sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
@@ -77,6 +77,8 @@ The tool returns an object with:
 }
 ```
 
+The graph is built from the `text` field of each result's metadata, so `document` (and `relevantContext`) contain that text. Store the chunk text under `metadata.text` when upserting.
+
 ## Default tool description
 
 The default description focuses on:

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

@@ -79,7 +79,7 @@ const queryTool = createVectorQueryTool({
 
 The tool returns an object with:
 
-**relevantContext** (`string`): Combined text from the most relevant document chunks
+**relevantContext** (`any[]`): Array of metadata objects for the most relevant chunks, in rank order (one entry per result). The chunk text is available at relevantContext\[i].text when it was stored in metadata during ingestion.
 
 **sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
@@ -95,6 +95,8 @@ The tool returns an object with:
 }
 ```
 
+`document` is only populated by vector stores whose `query()` returns document content, such as Chroma, Elasticsearch, LanceDB, and MongoDB. For other stores, such as PgVector, it's an empty string. Read the chunk text from `sources[i].metadata.text` (or whichever metadata key you stored it under).
+
 ## Default tool description
 
 The default description focuses on:
@@ -489,7 +491,7 @@ The tool is created with:
 
 - **ID**: `VectorQuery {vectorStoreName} {indexName} Tool`
 - **Input Schema**: Requires queryText and filter objects
-- **Output Schema**: Returns relevantContext string
+- **Output Schema**: Returns `relevantContext` (array of chunk metadata) and `sources` (array of `QueryResult`)
 
 ## Related
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.24-alpha.9",
+  "version": "1.2.24",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.65.0-alpha.4",
+    "@mastra/core": "1.65.0",
     "@mastra/mcp": "^1.17.3"
   },
   "devDependencies": {
@@ -44,9 +44,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.130",
-    "@internal/types-builder": "0.0.105",
-    "@mastra/core": "1.65.0-alpha.4"
+    "@internal/lint": "0.0.131",
+    "@mastra/core": "1.65.0",
+    "@internal/types-builder": "0.0.106"
   },
   "homepage": "https://mastra.ai",
   "repository": {