@mastra/mcp-docs-server 0.13.7-alpha.1 → 0.13.7-alpha.2

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

@@ -0,0 +1,268 @@
+---
+title: "Input Processors"
+description: "Learn how to use input processors to intercept and modify agent messages before they reach the language model."
+---
+
+# Input Processors
+
+Input Processors allow you to intercept, modify, validate, or filter messages _before_ they are sent to the language model. This is useful for implementing guardrails, content moderation, message transformation, and security controls.
+
+Processors operate on the messages in your conversation thread. They can modify, filter, or validate content, and even abort the request entirely if certain conditions are met.
+
+## Built-in Processors
+
+Mastra provides several built-in processors for common use cases:
+
+### `UnicodeNormalizer`
+
+This processor normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters.
+
+```typescript copy showLineNumbers {9-11}
+import { Agent } from "@mastra/core/agent";
+import { UnicodeNormalizer } from "@mastra/core/agent/input-processor/processors";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  name: 'normalized-agent',
+  instructions: 'You are a helpful assistant',
+  model: openai("gpt-4o"),
+  inputProcessors: [
+    new UnicodeNormalizer({
+      stripControlChars: true,
+      collapseWhitespace: true,
+    }),
+  ],
+});
+```
+
+Available options:
+- `stripControlChars`: Remove control characters (default: false)
+- `preserveEmojis`: Keep emojis intact (default: true) 
+- `collapseWhitespace`: Collapse multiple spaces/newlines (default: true)
+- `trim`: Remove leading/trailing whitespace (default: true)
+
+### `ModerationInputProcessor`
+
+This processor provides content moderation using an LLM to detect inappropriate content across multiple categories.
+
+```typescript copy showLineNumbers {5-13}
+import { ModerationInputProcessor } from "@mastra/core/agent/input-processor/processors";
+
+const agent = new Agent({
+  inputProcessors: [
+    new ModerationInputProcessor({
+      model: openai("gpt-4.1-nano"), // Use a fast, cost-effective model
+      threshold: 0.7, // Confidence threshold for flagging
+      strategy: 'block', // Block flagged content
+      categories: ['hate', 'harassment', 'violence'], // Custom categories
+    }),
+  ],
+});
+```
+
+Available options:
+- `model`: Language model for moderation analysis (required)
+- `categories`: Array of categories to check (default: ['hate','hate/threatening','harassment','harassment/threatening','self-harm','self-harm/intent','self-harm/instructions','sexual','sexual/minors','violence','violence/graphic'])
+- `threshold`: Confidence threshold for flagging (0-1, default: 0.5)
+- `strategy`: Action when content is flagged (default: 'block')
+- `customInstructions`: Custom instructions for the moderation agent
+
+Strategies available:
+- `block`: Reject the request with an error (default)
+- `warn`: Log warning but allow content through
+- `filter`: Remove flagged messages but continue processing
+
+### `PromptInjectionDetector`
+
+This processor detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts.
+
+```typescript copy showLineNumbers {5-12}
+import { PromptInjectionDetector } from "@mastra/core/agent/input-processor/processors";
+
+const agent = new Agent({
+  inputProcessors: [
+    new PromptInjectionDetector({
+      model: openai("gpt-4.1-nano"),
+      threshold: 0.8, // Higher threshold for fewer false positives
+      strategy: 'rewrite', // Attempt to neutralize while preserving intent
+      detectionTypes: ['injection', 'jailbreak', 'system-override'],
+    }),
+  ],
+});
+```
+
+Available options:
+- `model`: Language model for injection detection (required)
+- `detectionTypes`: Array of injection types to detect (default: ['injection', 'jailbreak', 'system-override'])
+- `threshold`: Confidence threshold for flagging (0-1, default: 0.7)
+- `strategy`: Action when injection is detected (default: 'block')
+- `instructions`: Custom detection instructions for the agent
+- `includeScores`: Whether to include confidence scores in logs (default: false)
+
+Strategies available:
+- `block`: Reject the request (default)
+- `warn`: Log warning but allow through
+- `filter`: Remove flagged messages
+- `rewrite`: Attempt to neutralize the injection while preserving legitimate intent
+
+### `PIIDetector`
+
+This processor detects and optionally redacts personally identifiable information (PII) from messages.
+
+```typescript copy showLineNumbers {5-14}
+import { PIIDetector } from "@mastra/core/agent/input-processor/processors";
+
+const agent = new Agent({
+  inputProcessors: [
+    new PIIDetector({
+      model: openai("gpt-4.1-nano"),
+      threshold: 0.6,
+      strategy: 'redact', // Automatically redact detected PII
+      detectionTypes: ['email', 'phone', 'credit-card', 'ssn', 'api-key', 'crypto-wallet', 'iban'],
+      redactionMethod: 'mask', // Preserve format while masking
+      preserveFormat: true, // Keep original structure in redacted values
+      includeDetections: true, // Log details for compliance auditing
+    }),
+  ],
+});
+```
+
+Available options:
+- `model`: Language model for PII detection (required)
+- `detectionTypes`: Array of PII types to detect (default: ['email', 'phone', 'credit-card', 'ssn', 'api-key', 'ip-address', 'name', 'address', 'date-of-birth', 'url', 'uuid', 'crypto-wallet', 'iban'])
+- `threshold`: Confidence threshold for flagging (0-1, default: 0.6)
+- `strategy`: Action when PII is detected (default: 'block')
+- `redactionMethod`: How to redact PII ('mask', 'hash', 'remove', 'placeholder', default: 'mask')
+- `preserveFormat`: Maintain PII structure during redaction (default: true)
+- `includeDetections`: Include detection details in logs for compliance (default: false)
+- `instructions`: Custom detection instructions for the agent
+
+Strategies available:
+- `block`: Reject requests containing PII (default)
+- `warn`: Log warning but allow through
+- `filter`: Remove messages containing PII
+- `redact`: Replace PII with placeholder values
+
+### `LanguageDetector`
+
+This processor detects the language of incoming messages and can automatically translate them to a target language.
+
+```typescript copy showLineNumbers {5-12}
+import { LanguageDetector } from "@mastra/core/agent/input-processor/processors";
+
+const agent = new Agent({
+  inputProcessors: [
+    new LanguageDetector({
+      model: openai("gpt-4o"),
+      targetLanguages: ['English', 'en'], // Accept English content
+      strategy: 'translate', // Auto-translate non-English content
+      threshold: 0.8, // High confidence threshold
+    }),
+  ],
+});
+```
+
+Available options:
+- `model`: Language model for detection and translation (required)
+- `targetLanguages`: Array of target languages (language names or ISO codes)
+- `threshold`: Confidence threshold for language detection (0-1, default: 0.7)
+- `strategy`: Action when non-target language is detected (default: 'detect')
+- `preserveOriginal`: Keep original content in metadata (default: true)
+- `instructions`: Custom detection instructions for the agent
+
+Strategies available:
+- `detect`: Only detect language, don't translate (default)
+- `translate`: Automatically translate to target language
+- `block`: Reject content not in target language
+- `warn`: Log warning but allow content through
+
+## Applying Multiple Processors
+
+You can chain multiple processors. They execute sequentially in the order they appear in the `inputProcessors` array. The output of one processor becomes the input for the next.
+
+**Order matters!** Generally, it's best practice to place text normalization first, security checks next, and content modification last.
+
+```typescript copy showLineNumbers {9-18}
+import { Agent } from "@mastra/core/agent";
+import { 
+  UnicodeNormalizer, 
+  ModerationInputProcessor, 
+  PromptInjectionDetector,
+  PIIDetector 
+} from "@mastra/core/agent/input-processor/processors";
+
+const secureAgent = new Agent({
+  inputProcessors: [
+    // 1. Normalize text first
+    new UnicodeNormalizer({ stripControlChars: true }),
+    // 2. Check for security threats
+    new PromptInjectionDetector({ model: openai("gpt-4.1-nano") }),
+    // 3. Moderate content
+    new ModerationInputProcessor({ model: openai("gpt-4.1-nano") }),
+    // 4. Handle PII last
+    new PIIDetector({ model: openai("gpt-4.1-nano"), strategy: 'redact' }),
+  ],
+});
+```
+
+## Creating Custom Processors
+
+You can create custom processors by implementing the `InputProcessor` interface.
+
+```typescript copy showLineNumbers {4-19,23-26}
+import type { InputProcessor, MastraMessageV2 } from "@mastra/core/agent";
+
+class MessageLengthLimiter implements InputProcessor {
+  readonly name = 'message-length-limiter';
+  
+  constructor(private maxLength: number = 1000) {}
+
+  process({ messages, abort }: { 
+    messages: MastraMessageV2[]; 
+    abort: (reason?: string) => never 
+  }): MastraMessageV2[] {
+    // Check total message length
+    const totalLength = messages.reduce((sum, msg) => {
+      return sum + msg.content.parts
+        .filter(part => part.type === 'text')
+        .reduce((partSum, part) => partSum + (part as any).text.length, 0);
+    }, 0);
+    
+    if (totalLength > this.maxLength) {
+      abort(`Message too long: ${totalLength} characters (max: ${this.maxLength})`);
+    }
+    
+    return messages;
+  }
+}
+
+// Use the custom processor
+const agent = new Agent({
+  inputProcessors: [
+    new MessageLengthLimiter(2000), // Limit to 2000 characters
+  ],
+});
+```
+
+When creating custom processors:
+- Always return the `messages` array (potentially modified)
+- Use `abort(reason)` to terminate processing early
+- Mutate the input messages directly
+- Keep processors focused on a single responsibility
+
+## Integration with Agent Methods
+
+Input processors work with both `generate()` and `stream()` methods. The entire processor pipeline completes before the agent begins generating or streaming a response.
+
+```typescript copy showLineNumbers
+// Processors run before generate()
+const result = await agent.generate('Hello');
+
+// Processors also run before stream()
+const stream = await agent.stream('Hello');
+for await (const chunk of stream.textStream) {
+  console.log(chunk);
+}
+```
+
+If any processor calls `abort()`, the request terminates immediately and subsequent processors are not executed. The agent returns an error response with details about why the request was blocked. 

package/.docs/raw/agents/using-tools-and-mcp.mdx

@@ -7,6 +7,10 @@ description: Learn how to create tools, add them to Mastra agents, and integrate
 
 Tools are typed functions that can be executed by agents or workflows. Each tool has a schema defining its inputs, an executor function implementing its logic, and optional access to configured integrations.
 
+Mastra supports two patterns for providing tools to agents:
+- **Direct assignment**: Static tools available at initialization
+- **Function-based**: Dynamic tools resolved based on runtime context  
+
 ## Creating Tools
 
 Here's a basic example of creating a tool:
@@ -107,6 +111,41 @@ const agent = new Agent({
 });
 ```
 
+When creating agents that will consume an MCP server in the same repo they need to connect to, always use function based tools to prevent race conditions.
+
+```typescript filename="src/mastra/agents/selfReferencingAgent.ts"
+import { Agent } from "@mastra/core/agent";
+import { MCPServer } from "@mastra/mcp";
+import { MCPClient } from "@mastra/mcp";
+import { openai } from "@ai-sdk/openai";
+
+const myAgent = new Agent({
+  name: "My Agent",
+  description: "An agent that can use tools from an http MCP server", 
+  instructions: "You can use remote calculation tools.",
+  model: openai("gpt-4o-mini"),
+  tools: async () => {
+    // Tools resolve when needed, not during initialization
+    const mcpClient = new MCPClient({
+      servers: {
+        myServer: {
+          url: new URL("http://localhost:4111/api/mcp/mcpServer/mcp"),
+        },
+      },
+    });
+    return await mcpClient.getTools();
+  },
+});
+
+// This works because tools resolve after server startup
+export const mcpServer = new MCPServer({
+  name: "My MCP Server",
+  agents: {
+    myAgent
+  },
+});
+```
+
 For more details on configuring `MCPClient` and the difference between static and dynamic MCP server configurations, see the [MCP Overview](/docs/tools-mcp/mcp-overview).
 
 ## Accessing MCP Resources

package/.docs/raw/community/contributing-templates.mdx

@@ -68,7 +68,7 @@ Ensure your template meets all requirements outlined in the [Templates Reference
 
 Submit your template using our contribution form:
 
-**[Submit Template Contribution](https://forms.gle/5qcU5UTKYcgFdVfE7)**
+**[Submit Template Contribution](https://docs.google.com/forms/d/e/1FAIpQLSfiqD4oeOVaqoE3t10KZJw4QM3fxAQPIOcZBqUYkewJIsQKFw/viewform)**
 
 ### Required Information
 
@@ -189,4 +189,4 @@ Ready to contribute a template?
 
 <Callout type="info">
 Your contributions help grow the Mastra ecosystem and provide valuable resources for the entire community. We look forward to seeing your innovative templates!
-</Callout>
+</Callout>

package/.docs/raw/observability/tracing.mdx

@@ -135,6 +135,50 @@ sdk.start();
 
 When Mastra finds a custom instrumentation file, it automatically replaces the default instrumentation and bundles it during the build process.
 
+### Tracing Outside Mastra Server Environment
+
+When using `mastra start` or `mastra dev` commands, Mastra automatically provisions and loads the necessary instrumentation files for tracing. However, when using Mastra as a dependency in your own application (outside the Mastra server environment), you'll need to manually provide the instrumentation file.
+
+To enable tracing in this case:
+
+1. Enable Mastra telemetry in your configuration:
+
+```typescript
+export const mastra = new Mastra({
+  telemetry: {
+    enabled: true,
+  },
+});
+```
+
+2. Create an instrumentation file in your project (e.g., `instrumentation.mjs`):
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter(),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+3. Add OpenTelemetry environment variables:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.braintrust.dev/otel
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <Your API Key>, x-bt-parent=project_name:<Your Project Name>"
+```
+
+4. Run the OpenTelemetry SDK before your application:
+
+```bash
+node --import=./instrumentation.mjs --import=@opentelemetry/instrumentation/hook.mjs src/index.js
+```
+
 ### Next.js-specific Tracing steps
 
 If you're using Next.js, you have three additional configuration steps:

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

@@ -61,6 +61,13 @@ constructor(config: AgentConfig<TAgentId, TTools, TMetrics>)
       description:
         "Tools that the agent can use. Can be a static object or a function that returns tools.",
     },
+    {
+      name: "inputProcessors",
+      type: "InputProcessor[] | ({ runtimeContext: RuntimeContext }) => InputProcessor[] | Promise<InputProcessor[]>",
+      isOptional: true,
+      description:
+        "Input processors that run sequentially before messages are sent to the language model. These middleware components can intercept, modify, validate, or filter messages. Each processor receives an array of MastraMessageV2 objects and an abort function for early termination. Can be a static array or a function that returns processors based on runtime context.",
+    },
     {
       name: "defaultGenerateOptions",
       type: "AgentGenerateOptions",

package/.docs/raw/reference/cli/dev.mdx

@@ -60,6 +60,12 @@ mastra dev [options]
       description: "Start the dev server in inspect mode and break at the beginning of the script (cannot be used with --inspect)",
       isOptional: true,
     },
+    {
+      name: "--custom-args",
+      type: "string",
+      description: "Comma-separated list of custom arguments to pass to the dev server. IE: --experimental-transform-types",
+      isOptional: true,
+    },
     {
       name: "--help",
       type: "boolean",

package/.docs/raw/reference/client-js/memory.mdx

@@ -103,6 +103,24 @@ const { messages } = await thread.getMessages();
 const { messages } = await thread.getMessages({ limit: 10 });
 ```
 
+### Delete a Message
+
+Delete a specific message from a thread:
+
+```typescript
+const result = await thread.deleteMessage("message-id");
+// Returns: { success: true, message: "Message deleted successfully" }
+```
+
+### Delete Multiple Messages
+
+Delete multiple messages from a thread in a single operation:
+
+```typescript
+const result = await thread.deleteMessages(["message-1", "message-2", "message-3"]);
+// Returns: { success: true, message: "3 messages deleted successfully" }
+```
+
 ### Get Memory Status
 
 Check the status of the memory system:

package/.docs/raw/reference/memory/Memory.mdx

@@ -310,3 +310,4 @@ Mastra supports many embedding models through the [Vercel AI SDK](https://sdk.ve
 - [query](/reference/memory/query.mdx)
 - [getThreadById](/reference/memory/getThreadById.mdx)
 - [getThreadsByResourceId](/reference/memory/getThreadsByResourceId.mdx)
+- [deleteMessages](/reference/memory/deleteMessages.mdx)

package/.docs/raw/reference/memory/deleteMessages.mdx

@@ -0,0 +1,95 @@
+---
+section: Memory
+title: deleteMessages
+slug: reference/memory/deleteMessages
+categorySlug: reference
+layout: guide
+---
+
+# `deleteMessages`
+
+Deletes one or more messages from the memory storage. This method accepts arrays to delete multiple messages in a single operation.
+
+## Syntax
+
+```typescript
+memory.deleteMessages(input: MessageDeleteInput): Promise<void>
+
+type MessageDeleteInput = 
+  | string[]                  // Array of message IDs
+  | { id: string }[]         // Array of message objects
+```
+
+## Parameters
+
+- `input` (required): An array of messages to delete. Must be either:
+  - An array of message IDs (strings)
+  - An array of message objects with `id` properties
+
+## Returns
+
+A Promise that resolves when all messages have been successfully deleted.
+
+## Examples
+
+### Delete a single message
+
+```typescript
+// Using an array with a single string ID
+await memory.deleteMessages(['msg-123']);
+
+// Using an array with a single message object
+await memory.deleteMessages([{ id: 'msg-123' }]);
+```
+
+### Delete multiple messages
+
+```typescript
+// Using an array of string IDs
+await memory.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
+
+// Using an array of message objects
+await memory.deleteMessages([
+  { id: 'msg-1' },
+  { id: 'msg-2' },
+  { id: 'msg-3' }
+]);
+```
+
+### Using with client SDK
+
+```typescript
+// Get a thread instance
+const thread = client.getAgent('my-agent').getThread('thread-123');
+
+// Delete a single message
+await thread.deleteMessages(['msg-123']);
+
+// Delete multiple messages
+await thread.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
+
+// Delete using message objects (useful when you have message data)
+const messagesToDelete = messages.map(msg => ({ id: msg.id }));
+await thread.deleteMessages(messagesToDelete);
+```
+
+### Error handling
+
+```typescript
+try {
+  await memory.deleteMessages(['msg-1', 'msg-2', 'msg-3']);
+  console.log('Messages deleted successfully');
+} catch (error) {
+  console.error('Failed to delete messages:', error);
+}
+```
+
+## Notes
+
+- This method requires an array as input, even when deleting a single message
+- Thread timestamps are automatically updated when messages are deleted
+- The method automatically extracts message IDs from message objects
+- All message IDs must be non-empty strings
+- An empty array will result in no operation (no error thrown)
+- Messages from different threads can be deleted in the same operation
+- When using message objects, only the `id` property is required

package/.docs/raw/reference/memory/getThreadsByResourceId.mdx

@@ -1,6 +1,6 @@
 # getThreadsByResourceId Reference
 
-The `getThreadsByResourceId` function retrieves all threads associated with a specific resource ID from storage.
+The `getThreadsByResourceId` function retrieves all threads associated with a specific resource ID from storage. Threads can be sorted by creation or modification time in ascending or descending order.
 
 ## Usage Example
 
@@ -9,9 +9,17 @@ import { Memory } from "@mastra/core/memory";
 
 const memory = new Memory(config);
 
+// Basic usage - returns threads sorted by createdAt DESC (default)
 const threads = await memory.getThreadsByResourceId({
   resourceId: "resource-123",
 });
+
+// Custom sorting by updatedAt in ascending order
+const threadsByUpdate = await memory.getThreadsByResourceId({
+  resourceId: "resource-123",
+  orderBy: "updatedAt",
+  sortDirection: "ASC",
+});
 ```
 
 ## Parameters
@@ -24,9 +32,33 @@ const threads = await memory.getThreadsByResourceId({
       description: "The ID of the resource whose threads are to be retrieved.",
       isOptional: false,
     },
+    {
+      name: "orderBy",
+      type: "ThreadOrderBy",
+      description: "Field to sort threads by. Accepts 'createdAt' or 'updatedAt'. Default: 'createdAt'",
+      isOptional: true,
+    },
+    {
+      name: "sortDirection",
+      type: "ThreadSortDirection", 
+      description: "Sort order direction. Accepts 'ASC' or 'DESC'. Default: 'DESC'",
+      isOptional: true,
+    },
   ]}
 />
 
+## Type Definitions
+
+```typescript
+type ThreadOrderBy = 'createdAt' | 'updatedAt';
+type ThreadSortDirection = 'ASC' | 'DESC';
+
+interface ThreadSortOptions {
+  orderBy?: ThreadOrderBy;
+  sortDirection?: ThreadSortDirection;
+}
+```
+
 ## Returns
 
 <PropertiesTable