@mastra/mcp-docs-server 0.13.7-alpha.0 → 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

@@ -0,0 +1,192 @@
+---
+title: "Contributing Templates"
+description: "How to contribute your own templates to the Mastra ecosystem"
+---
+
+import { Callout } from "nextra/components";
+
+# Contributing Templates
+
+The Mastra community plays a vital role in creating templates that showcase innovative application patterns. This guide explains how to contribute your own templates to the Mastra ecosystem.
+
+## Template Contribution Process
+
+### 1. Review Requirements
+
+Before creating a template, ensure you understand:
+
+- [Templates Reference](/reference/templates) - Technical requirements and conventions
+- [Project Structure](/docs/getting-started/project-structure) - Standard Mastra project organization
+- Community guidelines and quality standards
+
+### 2. Develop Your Template
+
+Create your template following the established patterns:
+
+- Focus on a specific use case or pattern
+- Include comprehensive documentation
+- Test thoroughly with fresh installations
+- Follow all technical requirements
+
+### 3. Submit for Review
+
+Once your template is ready, submit it through our contribution form. Templates undergo an approval process to ensure quality and consistency.
+
+## Submission Guidelines
+
+### Template Criteria
+
+We accept templates that:
+
+- **Demonstrate unique value** - Show innovative use cases or patterns not covered by existing templates
+- **Follow conventions** - Adhere to all technical requirements and structural guidelines
+- **Include quality documentation** - Provide clear setup instructions and usage examples
+- **Work reliably** - Function correctly with minimal setup after installation
+
+### Quality Standards
+
+Templates must meet these quality benchmarks:
+
+- **Code quality** - Clean, well-commented, and maintainable code
+- **Error handling** - Proper error handling for external APIs and user inputs
+- **Type safety** - Full TypeScript typing with Zod validation where appropriate
+- **Documentation** - Comprehensive README with setup and usage instructions
+- **Testing** - Verified to work with fresh installations
+
+## Submission Process
+
+### 1. Prepare Your Template
+
+Ensure your template meets all requirements outlined in the [Templates Reference](/reference/templates):
+
+- Proper project structure in `src/mastra/` directory
+- Standard TypeScript configuration
+- Comprehensive `.env.example` file
+- Detailed README with setup instructions
+
+### 2. Submit Your Template
+
+Submit your template using our contribution form:
+
+**[Submit Template Contribution](https://docs.google.com/forms/d/e/1FAIpQLSfiqD4oeOVaqoE3t10KZJw4QM3fxAQPIOcZBqUYkewJIsQKFw/viewform)**
+
+### Required Information
+
+When submitting your template, provide:
+
+- **Template Name** - Clear, descriptive name indicating the use case
+- **Template Author Name** - Your name or organization name
+- **Template Author Email** - Contact email for communication about your submission
+- **GitHub URL** - Link to your template repository
+- **Description** - Detailed explanation of what the template does and its value
+- **Optional Image** - Screenshot or diagram showing the template in action
+- **Optional Demo Video** - Link to a video demonstrating the template's functionality
+
+## Review Process
+
+### Review Criteria
+
+Templates are evaluated on:
+
+- **Technical compliance** - Adherence to template rules and conventions
+- **Code quality** - Clean, maintainable, and well-documented code
+- **Uniqueness** - Novel use cases or innovative implementation patterns
+- **Educational value** - Ability to teach Mastra concepts effectively
+- **Community benefit** - Potential value to the broader Mastra community
+
+### Feedback and Iteration
+
+If your template needs improvements:
+
+- You'll receive specific feedback on required changes
+- Make the requested modifications and resubmit
+- The review process continues until the template meets standards
+
+## Community Guidelines
+
+### Template Ideas
+
+Consider creating templates for:
+
+- **Industry-specific use cases** - Healthcare, finance, education, etc.
+- **Integration patterns** - Specific API or service integrations
+- **Advanced techniques** - Complex workflows, multi-agent systems, or novel patterns
+- **Learning resources** - Step-by-step tutorials for specific concepts
+
+### Development Best Practices
+
+- **Start simple** - Begin with a minimal working example and add complexity gradually
+- **Document thoroughly** - Include detailed comments and comprehensive README
+- **Test extensively** - Verify your template works across different environments
+- **Seek feedback** - Share with the community for early feedback before submission
+
+### Community Engagement
+
+- **Join Discord** - Participate in the [Mastra Discord community](https://discord.gg/BTYqqHKUrf)
+- **Share progress** - Update the community on your template development
+- **Help others** - Assist other contributors with their templates
+- **Stay updated** - Keep track of new Mastra features and conventions
+
+## Template Maintenance
+
+### Ongoing Responsibilities
+
+As a template contributor, you may be asked to:
+
+- **Update dependencies** - Keep templates current with latest Mastra versions
+- **Fix issues** - Address bugs or compatibility problems
+- **Improve documentation** - Enhance instructions based on user feedback
+- **Add features** - Extend templates with new capabilities
+
+### Community Support
+
+The Mastra team and community provide:
+
+- **Technical guidance** - Help with complex implementation challenges
+- **Review feedback** - Detailed feedback to improve template quality
+- **Promotion** - Showcase approved templates to the community
+- **Maintenance assistance** - Support for keeping templates up-to-date
+
+## Validation Checklist
+
+Before submitting a template, verify:
+
+- [ ] All code organized in `src/mastra/` directory
+- [ ] Uses standard Mastra TypeScript configuration
+- [ ] Includes comprehensive `.env.example`
+- [ ] Has detailed README with setup instructions
+- [ ] No monorepo or web framework boilerplate
+- [ ] Successfully runs after fresh install and environment setup
+- [ ] Follows all code quality standards
+- [ ] Demonstrates clear, valuable use case
+
+## Community Showcase
+
+### Template Gallery
+
+Approved templates will be featured in:
+
+- **mastra.ai/templates** - Community template gallery (coming soon)
+- **Documentation** - Referenced in relevant documentation sections
+- **Community highlights** - Featured in newsletters and community updates
+
+### Recognition
+
+Template contributors receive:
+
+- **Attribution** - Your name and contact information with the template
+- **Community recognition** - Acknowledgment in community channels
+
+## Getting Started
+
+Ready to contribute a template?
+
+1. **Explore existing templates** - Review current templates for inspiration and patterns
+2. **Plan your template** - Define the use case and value proposition
+3. **Follow the requirements** - Ensure compliance with all technical requirements
+4. **Build and test** - Create a working, well-documented template
+5. **Submit for review** - Use the contribution form to submit your 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>

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

@@ -68,6 +68,22 @@ You can also run the Mastra CLI in non-interactive mode by passing all required
 npx create-mastra@latest --project-name hello-mastra --example --components tools,agents,workflows --llm openai
 ```
 
+**Install with a template**
+
+Start with a pre-built template that demonstrates specific use cases:
+
+```bash copy
+npx create-mastra@latest --template template-name
+```
+
+For example, to create a text-to-SQL application:
+
+```bash copy
+npx create-mastra@latest --template text-to-sql
+```
+
+> Browse available templates and learn more in [Templates](/docs/getting-started/templates).
+
 > See the [create-mastra](/reference/cli/create-mastra) documentation for a full list of available CLI options.
 
 ### Add your API key

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

@@ -0,0 +1,95 @@
+---
+title: "Templates | Getting Started | Mastra Docs"
+description: Pre-built project structures that demonstrate common Mastra use cases and patterns
+---
+
+import { Callout } from "nextra/components";
+import { Tabs, Tab } from "@/components/tabs";
+
+# Templates
+
+Templates are pre-built Mastra projects that demonstrate specific use cases and patterns. They provide working examples you can run immediately and customize for your needs.
+
+## What Templates Offer
+
+Templates include:
+
+- **Complete working examples** - Functional code demonstrating specific patterns
+- **Best practices** - Proper project structure and Mastra conventions  
+- **Educational value** - Learn different Mastra features through examples
+- **Quick start** - Bootstrap projects faster than starting from scratch
+
+## Using Templates
+
+Install a template using the `create-mastra` command:
+
+<Tabs items={["npx", "npm", "yarn", "pnpm", "bun"]}>
+  <Tab>
+    ```bash copy
+    npx create-mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    npm create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    yarn create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    pnpm create mastra@latest --template template-name
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    bun create mastra@latest --template template-name
+    ```
+  </Tab>
+</Tabs>
+
+For example, to create a text-to-SQL application:
+
+```bash copy
+npx create-mastra@latest --template text-to-sql
+```
+
+## Setting Up a Template
+
+After installation:
+
+1. **Navigate to your project**:
+   ```bash copy
+   cd your-project-name
+   ```
+
+2. **Configure environment variables**:
+   ```bash copy
+   cp .env.example .env
+   ```
+   Edit `.env` with your API keys as specified in the template's README.
+
+3. **Start development**:
+   ```bash copy
+   npm run dev
+   ```
+
+<Callout type="info">
+  Each template includes a comprehensive README with specific setup instructions and usage examples.
+</Callout>
+
+## Available Templates
+
+Browse available templates in the [templates directory](https://github.com/mastra-ai/mastra/tree/main/templates) on GitHub.
+
+## Next Steps
+
+- **Explore code** - Understand how templates implement functionality
+- **Customize** - Modify agents, tools, and workflows for your use case
+- **Learn patterns** - Study templates to understand Mastra best practices
+- **Contribute** - Create your own templates for the community
+
+For detailed information on creating templates, see the [Templates Reference](/reference/templates).

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: