@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.11

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,19 @@
 # mastra
 
+## 1.0.0-beta.9
+
+### Patch Changes
+
+- Allow to run mastra studio from anywhere in the file system, and not necessarily inside a mastra project ([#11067](https://github.com/mastra-ai/mastra/pull/11067))
+
+- Make sure to verify that a mastra instance is running on server.port OR 4111 by default ([#11066](https://github.com/mastra-ai/mastra/pull/11066))
+
+- Internal changes to enable a custom base path for Mastra Studio ([#10441](https://github.com/mastra-ai/mastra/pull/10441))
+
+- Updated dependencies [[`38380b6`](https://github.com/mastra-ai/mastra/commit/38380b60fca905824bdf6b43df307a58efb1aa15), [`798d0c7`](https://github.com/mastra-ai/mastra/commit/798d0c740232653b1d754870e6b43a55c364ffe2), [`ffe84d5`](https://github.com/mastra-ai/mastra/commit/ffe84d54f3b0f85167fe977efd027dba027eb998), [`2c212e7`](https://github.com/mastra-ai/mastra/commit/2c212e704c90e2db83d4109e62c03f0f6ebd2667), [`4ca4306`](https://github.com/mastra-ai/mastra/commit/4ca430614daa5fa04730205a302a43bf4accfe9f), [`2c212e7`](https://github.com/mastra-ai/mastra/commit/2c212e704c90e2db83d4109e62c03f0f6ebd2667), [`3bf6c5f`](https://github.com/mastra-ai/mastra/commit/3bf6c5f104c25226cd84e0c77f9dec15f2cac2db)]:
+  - @mastra/core@1.0.0-beta.11
+  - @mastra/deployer@1.0.0-beta.11
+
 ## 1.0.0-beta.8
 
 ### Minor Changes
@@ -484,19 +498,5 @@
 
 - Improve the overall flow of the `create-mastra` CLI by first asking all questions and then creating the project structure. If you skip entering an API key during the wizard, the `your-api-key` placeholder will now be added to an `.env.example` file instead of `.env`. ([#8603](https://github.com/mastra-ai/mastra/pull/8603))
 
-- Updated dependencies [[`0d71771`](https://github.com/mastra-ai/mastra/commit/0d71771f5711164c79f8e80919bc84d6bffeb6bc), [`0d6e55e`](https://github.com/mastra-ai/mastra/commit/0d6e55ecc5a2e689cd4fc9c86525e0eb54d82372)]:
-  - @mastra/core@0.20.2-alpha.0
-  - @mastra/deployer@0.20.2-alpha.0
-
-## 0.15.0
-
-### Minor Changes
-
-- Update peer dependencies to match core package version bump (0.20.1) ([#8589](https://github.com/mastra-ai/mastra/pull/8589))
-
-### Patch Changes
-
-- workflow run thread more visible ([#8539](https://github.com/mastra-ai/mastra/pull/8539))
-
 
-... 6356 more lines hidden. See full changelog in package directory.
+... 6370 more lines hidden. See full changelog in package directory.

package/.docs/raw/agents/guardrails.mdx

@@ -327,9 +327,9 @@ export const privateAgent = new Agent({
 
 ### Handling blocked requests
 
-When a processor blocks a request, the agent will still return successfully without throwing an error. To handle blocked requests, check for `tripwire` or `tripwireReason` in the response.
+When a processor blocks a request, the agent will still return successfully without throwing an error. To handle blocked requests, check for `tripwire` in the response.
 
-For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the request includes a credit card number, it will be blocked and the response will include a `tripwireReason`.
+For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the request includes a credit card number, it will be blocked and the response will include tripwire information.
 
 #### `.generate()` example
 
@@ -338,8 +338,14 @@ const result = await agent.generate(
   "Is this credit card number valid?: 4543 1374 5089 4332",
 );
 
-console.error(result.tripwire);
-console.error(result.tripwireReason);
+if (result.tripwire) {
+  console.error("Blocked:", result.tripwire.reason);
+  console.error("Processor:", result.tripwire.processorId);
+  // Optional: check if retry was requested
+  console.error("Retry requested:", result.tripwire.retry);
+  // Optional: access additional metadata
+  console.error("Metadata:", result.tripwire.metadata);
+}
 ```
 
 #### `.stream()` example
@@ -351,17 +357,48 @@ const stream = await agent.stream(
 
 for await (const chunk of stream.fullStream) {
   if (chunk.type === "tripwire") {
-    console.error(chunk.payload.tripwireReason);
+    console.error("Blocked:", chunk.payload.reason);
+    console.error("Processor:", chunk.payload.processorId);
   }
 }
 ```
 
-In this case, the `tripwireReason` indicates that a credit card number was detected:
+In this case, the `reason` indicates that a credit card number was detected:
 
 ```text
 PII detected. Types: credit-card
 ```
 
+### Requesting retries
+
+Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks:
+
+```typescript showLineNumbers
+export class QualityChecker implements Processor {
+  id = "quality-checker";
+
+  async processOutputStep({ text, abort, retryCount }) {
+    const score = await evaluateQuality(text);
+
+    if (score < 0.7 && retryCount < 3) {
+      // Request retry with feedback for the LLM
+      abort("Response quality too low. Please be more specific.", {
+        retry: true,
+        metadata: { score },
+      });
+    }
+
+    return [];
+  }
+}
+```
+
+The `abort()` function accepts an optional second parameter with:
+- `retry: true` - Request the LLM retry the step
+- `metadata: unknown` - Attach additional data for debugging/logging
+
+Use `retryCount` to track retry attempts and prevent infinite loops.
+
 ## Custom processors
 
 If the built-in processors don’t cover your needs, you can create your own by extending the `Processor` class.

package/.docs/raw/agents/processors.mdx

@@ -12,6 +12,8 @@ Processors are configured as:
 - **`inputProcessors`**: Run before messages reach the language model.
 - **`outputProcessors`**: Run after the language model generates a response, but before it's returned to users.
 
+You can use individual `Processor` objects or compose them into workflows using Mastra's workflow primitives. Workflows give you advanced control over processor execution order, parallel processing, and conditional logic.
+
 Some processors implement both input and output logic and can be used in either array depending on where the transformation should occur.
 
 ## When to use processors
@@ -168,6 +170,81 @@ This is useful for:
 - Filtering or modifying semantic recall content to prevent "prompt too long" errors
 - Dynamically adjusting system instructions based on the conversation
 
+### Per-step processing with processInputStep
+
+While `processInput` runs once at the start of agent execution, `processInputStep` runs at **each step** of the agentic loop (including tool call continuations). This enables per-step configuration changes like dynamic model switching or tool choice modifications.
+
+```typescript title="src/mastra/processors/step-processor.ts" showLineNumbers copy
+import type { Processor, ProcessInputStepArgs, ProcessInputStepResult } from "@mastra/core";
+
+export class DynamicModelProcessor implements Processor {
+  id = "dynamic-model";
+
+  async processInputStep({
+    stepNumber,
+    model,
+    toolChoice,
+    messageList,
+  }: ProcessInputStepArgs): Promise<ProcessInputStepResult> {
+    // Use a fast model for initial response
+    if (stepNumber === 0) {
+      return { model: "openai/gpt-4o-mini" };
+    }
+
+    // Disable tools after 5 steps to force completion
+    if (stepNumber > 5) {
+      return { toolChoice: "none" };
+    }
+
+    // No changes for other steps
+    return {};
+  }
+}
+```
+
+The `processInputStep` method receives:
+- `stepNumber`: Current step in the agentic loop (0-indexed)
+- `steps`: Results from previous steps
+- `messages`: Current messages snapshot (read-only)
+- `systemMessages`: Current system messages (read-only)
+- `messageList`: The full MessageList instance for mutations
+- `model`: Current model being used
+- `tools`: Current tools available for this step
+- `toolChoice`: Current tool choice setting
+- `activeTools`: Currently active tools
+- `providerOptions`: Provider-specific options
+- `modelSettings`: Model settings like temperature
+- `structuredOutput`: Structured output configuration
+
+The method can return any combination of:
+- `model`: Change the model for this step
+- `tools`: Replace or add tools (use spread to merge: `{ tools: { ...tools, newTool } }`)
+- `toolChoice`: Change tool selection behavior
+- `activeTools`: Filter which tools are available
+- `messages`: Replace messages (applied to messageList)
+- `systemMessages`: Replace all system messages
+- `providerOptions`: Modify provider options
+- `modelSettings`: Modify model settings
+- `structuredOutput`: Modify structured output configuration
+
+#### Using prepareStep callback
+
+For simpler per-step logic, you can use the `prepareStep` callback on `generate()` or `stream()` instead of creating a full processor:
+
+```typescript
+await agent.generate({
+  prompt: "Complex task",
+  prepareStep: async ({ stepNumber, model }) => {
+    if (stepNumber === 0) {
+      return { model: "openai/gpt-4o-mini" };
+    }
+    if (stepNumber > 5) {
+      return { toolChoice: "none" };
+    }
+  },
+});
+```
+
 ### Custom output processor
 
 ```typescript title="src/mastra/processors/custom-output.ts" showLineNumbers copy
@@ -273,7 +350,81 @@ const agent = new Agent({
 
 > **Note:** The example above filters tool calls and limits tokens for the LLM, but these filtered messages will still be saved to memory. To also filter messages before they're saved to memory, manually add memory processors before utility processors. See [Memory Processors](/docs/v1/memory/memory-processors#manual-control-and-deduplication) for details.
 
+## Using workflows as processors
+
+You can use Mastra workflows as processors to create complex processing pipelines with parallel execution, conditional branching, and error handling:
+
+```typescript title="src/mastra/processors/moderation-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { ProcessorStepSchema } from "@mastra/core/processors";
+import { Agent } from "@mastra/core/agent";
+
+// Create a workflow that runs multiple checks in parallel
+const moderationWorkflow = createWorkflow({
+  id: "moderation-pipeline",
+  inputSchema: ProcessorStepSchema,
+  outputSchema: ProcessorStepSchema,
+})
+  .then(createStep(new LengthValidator({ maxLength: 10000 })))
+  .parallel([
+    createStep(new PIIDetector({ strategy: "redact" })),
+    createStep(new ToxicityChecker({ threshold: 0.8 })),
+  ])
+  .commit();
+
+// Use the workflow as an input processor
+const agent = new Agent({
+  id: "moderated-agent",
+  name: "Moderated Agent",
+  model: "openai/gpt-4o",
+  inputProcessors: [moderationWorkflow],
+});
+```
+
+When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the playground.
+
+## Retry mechanism
+
+Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks, output validation, or iterative refinement:
+
+```typescript title="src/mastra/processors/quality-checker.ts" showLineNumbers copy
+import type { Processor } from "@mastra/core";
+
+export class QualityChecker implements Processor {
+  id = "quality-checker";
+
+  async processOutputStep({ text, abort, retryCount }) {
+    const qualityScore = await evaluateQuality(text);
+
+    if (qualityScore < 0.7 && retryCount < 3) {
+      // Request a retry with feedback for the LLM
+      abort("Response quality score too low. Please provide a more detailed answer.", {
+        retry: true,
+        metadata: { score: qualityScore },
+      });
+    }
+
+    return [];
+  }
+}
+
+const agent = new Agent({
+  id: "quality-agent",
+  name: "Quality Agent",
+  model: "openai/gpt-4o",
+  outputProcessors: [new QualityChecker()],
+  maxProcessorRetries: 3, // Maximum retry attempts (default: 3)
+});
+```
+
+The retry mechanism:
+- Only works in `processOutputStep` and `processInputStep` methods
+- Replays the step with the abort reason added as context for the LLM
+- Tracks retry count via the `retryCount` parameter
+- Respects `maxProcessorRetries` limit on the agent
+
 ## Related documentation
 
 - [Guardrails](/docs/v1/agents/guardrails) - Security and validation processors
 - [Memory Processors](/docs/v1/memory/memory-processors) - Memory-specific processors and automatic integration
+- [Processor Interface](/reference/v1/processors/processor-interface) - Full API reference for processors

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -75,6 +75,63 @@ If you followed the automatic installation, you'll see a popup when you open cur
 
 [More info on using MCP servers with Cursor](https://cursor.com/de/docs/context/mcp)
 
+### Antigravity
+
+Google Antigravity is an agent-first development platform that supports MCP servers for accessing external documentation, APIs, and project context.
+
+1. Open your Antigravity MCP configuration file:
+   - Click on **Agent session** and select the **“…” dropdown** at the top of the editor’s side panel, then select **MCP Servers** to access the **MCP Store**.
+   - You can access it through the MCP Store interface in Antigravity
+
+   <img
+     src="/img/antigravity_mcp_server.png"
+     alt="Antigravity interface showing configured Mastra MCP server"
+     width={800}
+     className="rounded-lg"
+   />
+
+2. To add a custom MCP server, select **Manage MCP Servers** at the top of the MCP Store and click **View raw config** in the main tab.  
+   <img
+     src="/img/antigravity_managed_mcp.png"
+     alt="Antigravity interface showing configured Mastra MCP server"
+     width={800}
+     className="rounded-lg"
+   />
+
+3. Add the Mastra MCP server configuration:
+
+   ```json copy
+   {
+      "mcpServers": {
+          "mastra-docs": {
+              "command": "npx",
+              "args": [
+                  "-y",
+                  "@mastra/mcp-docs-server"
+              ]
+          }
+      }
+  }
+   ```
+
+4. Save the configuration and restart Antigravity
+    <img
+      src="/img/antigravity_final_interface_mcp.png"
+      alt="Antigravity interface showing configured Mastra MCP server"
+      width={800}
+      className="rounded-lg"
+   />
+
+Once configured, the Mastra MCP server exposes the following to Antigravity agents:
+- Indexed documentation and API schemas for Mastra, enabling programmatic retrieval of relevant context during code generation
+- Access to example code snippets and usage patterns stored in Mastra Docs
+- Structured data for error handling and debugging references in the editor
+- Metadata about current Mastra project patterns for code suggestion and completion
+
+The MCP server will appear in Antigravity's MCP Store, where you can manage its connection status and authentication if needed.
+
+[More info on using MCP servers with Antigravity](https://antigravity.google)
+
 ### Visual Studio Code
 
 1. Create a `.vscode/mcp.json` file in your workspace

package/.docs/raw/getting-started/studio.mdx

@@ -113,7 +113,7 @@ The OpenAPI and Swagger endpoints are disabled in production by default. To enab
 
 ## Configuration
 
-### Port
+### Port and Host
 
 By default, the development server runs at http://localhost:4111. You can change the `host` and `port` in the Mastra server configuration:
 
@@ -128,6 +128,29 @@ export const mastra = new Mastra({
 });
 ```
 
+### Sub-path Hosting
+
+You can host the Mastra Studio on a sub-path of your existing application using the `studioBase` configuration:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  server: {
+    studioBase: "/my-mastra-studio",
+  },
+});
+```
+
+This is particularly useful when:
+- Integrating with existing applications
+- Using authentication tools like Cloudflare Zero Trust that benefit from shared domains
+- Managing multiple services under a single domain
+
+**Example URLs:**
+- Default: `http://localhost:4111/` (studio at root)
+- With `studioBase`: `http://localhost:4111/my-mastra-studio/` (studio at sub-path)
+
 ### Local HTTPS
 
 Mastra supports local HTTPS development through the [`--https`](/reference/v1/cli/mastra#--https) flag, which automatically creates and manages certificates for your project. When you run `mastra dev --https`, a private key and certificate are generated for localhost (or your configured host). For custom certificate management, you can provide your own key and certificate files through the server configuration:

package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx

@@ -313,3 +313,73 @@ To migrate, remove the `TMetrics` generic parameter and configure scorers using
     // ...
   });
 ```
+
+### Tripwire response format changed
+
+The tripwire response format has changed from separate `tripwire` and `tripwireReason` fields to a single `tripwire` object containing all related data.
+
+To migrate, update your code to access tripwire data from the new object structure.
+
+```diff
+  const result = await agent.generate('Hello');
+
+- if (result.tripwire) {
+-   console.log(result.tripwireReason);
+- }
++ if (result.tripwire) {
++   console.log(result.tripwire.reason);
++   // New fields available:
++   // result.tripwire.retry - whether this step should be retried
++   // result.tripwire.metadata - additional metadata from the processor
++   // result.tripwire.processorId - which processor triggered the tripwire
++ }
+```
+
+For streaming responses:
+
+```diff
+  for await (const chunk of stream.fullStream) {
+    if (chunk.type === 'tripwire') {
+-     console.log(chunk.payload.tripwireReason);
++     console.log(chunk.payload.reason);
++     // New fields available:
++     // chunk.payload.retry
++     // chunk.payload.metadata
++     // chunk.payload.processorId
+    }
+  }
+```
+
+The step results now also include tripwire information:
+
+```diff
+  const result = await agent.generate('Hello');
+
+  for (const step of result.steps) {
+-   // No tripwire info on steps
++   if (step.tripwire) {
++     console.log('Step was blocked:', step.tripwire.reason);
++   }
+  }
+```
+
+### `prepareStep` messages format
+
+The `prepareStep` callback now receives messages in `MastraDBMessage` format instead of AI SDK v5 model message format. This change unifies `prepareStep` with the new `processInputStep` processor method, which runs at each step of the agentic loop.
+
+If you need the old AI SDK v5 format, use `messageList.get.all.aiV5.model()`:
+
+```diff
+  agent.generate({
+    prompt: 'Hello',
+    prepareStep: async ({ messages, messageList }) => {
+-     // messages was AI SDK v5 ModelMessage format
+-     console.log(messages[0].content);
++     // messages is now MastraDBMessage format
++     // Use messageList to get AI SDK v5 format if needed:
++     const aiSdkMessages = messageList.get.all.aiV5.model();
+
+      return { toolChoice: 'auto' };
+    },
+  });
+```

package/.docs/raw/reference/agents/agent.mdx

@@ -212,17 +212,24 @@ export const agent = new Agent({
     },
     {
       name: "inputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
+        "Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with `createWorkflow()` using ProcessorStepSchema.",
     },
     {
       name: "outputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Output processors that can modify or validate messages from the agent, before it is sent to the client. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
+        "Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.",
+    },
+    {
+      name: "maxProcessorRetries",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of times a processor can request retrying the LLM step.",
     },
   ]}
 />

package/.docs/raw/reference/core/getServer.mdx

@@ -25,7 +25,7 @@ This method does not accept any parameters.
       name: "server",
       type: "ServerConfig | undefined",
       description:
-        "The configured server configuration including port, timeout, API routes, middleware, CORS settings, and build options, or undefined if no server has been configured.",
+        "The configured server configuration including port, host, studioBase, timeout, API routes, middleware, CORS settings, and build options, or undefined if no server has been configured.",
     },
   ]}
 />