@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.6

package/.docs/organized/code-examples/server-app-access.md

@@ -0,0 +1,342 @@
+### package.json
+```json
+{
+  "name": "examples-server-app-access",
+  "dependencies": {
+    "@mastra/core": "latest",
+    "@mastra/hono": "latest",
+    "hono": "^4.10.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### demo-cli-batch.ts
+```typescript
+/**
+ * Demo: Direct Server App Access
+ *
+ * This demonstrates how to use mastra.getServerApp() to call routes
+ * directly without running an HTTP server.
+ *
+ * Use case: CLI scripts, batch processing, testing, background jobs
+ *
+ * NOTE: The base URL (http://internal) is just a placeholder - Hono's app.fetch()
+ * processes requests in-memory and only uses the path. The hostname is ignored.
+ */
+
+import { MastraServer } from '@mastra/hono';
+import { Hono } from 'hono';
+import type { Hono as HonoType } from 'hono';
+
+import { mastra } from './mastra';
+
+// Base URL is a placeholder - only the path matters for in-memory routing
+const BASE_URL = 'http://internal';
+
+async function main() {
+  // Create and initialize server (no port binding)
+  const app = new Hono();
+  const adapter = new MastraServer({ app: app as any, mastra });
+  await adapter.init();
+
+  // Get the server app - works because MastraServer auto-registers with mastra
+  const serverApp = mastra.getServerApp<HonoType>();
+  if (!serverApp) throw new Error('Server app not initialized');
+
+  // List tools
+  console.log('--- List Tools ---');
+  const toolsResponse = await serverApp.fetch(new Request(`${BASE_URL}/api/tools`));
+  const tools = (await toolsResponse.json()) as Record<string, unknown>;
+  console.log(`Tools: ${Object.keys(tools).join(', ') || '(none registered by key)'}`);
+
+  // Execute a tool
+  console.log('\n--- Execute Tool ---');
+  const calcResponse = await serverApp.fetch(
+    new Request(`${BASE_URL}/api/tools/calculator/execute`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ data: { operation: 'multiply', a: 7, b: 6 } }),
+    }),
+  );
+  console.log(`Result: ${JSON.stringify(await calcResponse.json())}`);
+
+  // List workflows
+  console.log('\n--- List Workflows ---');
+  const workflowsResponse = await serverApp.fetch(new Request(`${BASE_URL}/api/workflows`));
+  const workflows = (await workflowsResponse.json()) as Record<string, unknown>;
+  console.log(`Workflows: ${Object.keys(workflows).join(', ')}`);
+}
+
+main().catch(console.error);
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { calculatorTool, timestampTool } from './tools';
+import { dailyReportWorkflow, paymentProcessorWorkflow, processMessageWorkflow } from './workflows';
+
+/**
+ * Main Mastra instance configured with tools and workflows
+ * for demonstrating server app access patterns.
+ */
+export const mastra = new Mastra({
+  tools: {
+    calculatorTool,
+    timestampTool,
+  },
+  workflows: {
+    processMessageWorkflow,
+    dailyReportWorkflow,
+    paymentProcessorWorkflow,
+  },
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+/**
+ * Calculator tool - performs basic arithmetic operations
+ */
+export const calculatorTool = createTool({
+  id: 'calculator',
+  description: 'Performs basic arithmetic operations',
+  inputSchema: z.object({
+    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+    a: z.number(),
+    b: z.number(),
+  }),
+  execute: async ({ operation, a, b }) => {
+    if (operation === 'divide' && b === 0) {
+      throw new Error('Cannot divide by zero');
+    }
+
+    let result: number;
+    switch (operation) {
+      case 'add':
+        result = a + b;
+        break;
+      case 'subtract':
+        result = a - b;
+        break;
+      case 'multiply':
+        result = a * b;
+        break;
+      case 'divide':
+        result = a / b;
+        break;
+      default:
+        throw new Error(`Unsupported operation: ${operation}`);
+    }
+
+    return { result, operation, operands: { a, b } };
+  },
+});
+
+/**
+ * Timestamp tool - returns current timestamp in various formats
+ */
+export const timestampTool = createTool({
+  id: 'timestamp',
+  description: 'Returns the current timestamp in various formats',
+  inputSchema: z.object({
+    format: z.enum(['iso', 'unix', 'readable']).default('iso'),
+  }),
+  execute: async ({ format }) => {
+    const now = new Date();
+
+    let timestamp: string;
+    switch (format) {
+      case 'unix':
+        timestamp = Math.floor(now.getTime() / 1000).toString();
+        break;
+      case 'readable':
+        timestamp = now.toLocaleString();
+        break;
+      case 'iso':
+      default:
+        timestamp = now.toISOString();
+        break;
+    }
+
+    return { timestamp, format };
+  },
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { createStep, createWorkflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+// --- Process Message Workflow ---
+
+const validateStep = createStep({
+  id: 'validate',
+  description: 'Validates the incoming message',
+  inputSchema: z.object({
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  outputSchema: z.object({
+    valid: z.boolean(),
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  execute: async ({ inputData }) => {
+    const valid = inputData.message.length > 0 && inputData.message.length < 1000;
+    return {
+      valid,
+      message: inputData.message,
+      priority: inputData.priority,
+    };
+  },
+});
+
+const processStep = createStep({
+  id: 'process',
+  description: 'Processes the validated message',
+  inputSchema: z.object({
+    valid: z.boolean(),
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  outputSchema: z.object({
+    processed: z.boolean(),
+    result: z.string(),
+    timestamp: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    if (!inputData.valid) {
+      return {
+        processed: false,
+        result: 'Invalid message',
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    const result = `Processed [${inputData.priority}]: ${inputData.message.substring(0, 50)}...`;
+
+    return {
+      processed: true,
+      result,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+
+export const processMessageWorkflow = createWorkflow({
+  id: 'process-message',
+  description: 'Validates and processes a message',
+  inputSchema: z.object({
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  outputSchema: z.object({
+    processed: z.boolean(),
+    result: z.string(),
+    timestamp: z.string(),
+  }),
+})
+  .then(validateStep)
+  .then(processStep)
+  .commit();
+
+// --- Daily Report Workflow ---
+
+const generateReportStep = createStep({
+  id: 'generate-report',
+  description: 'Generates a daily report',
+  inputSchema: z.object({
+    date: z.string(),
+    reportType: z.enum(['summary', 'detailed']).default('summary'),
+  }),
+  outputSchema: z.object({
+    reportId: z.string(),
+    status: z.string(),
+    generatedAt: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const reportId = `RPT-${Date.now()}`;
+
+    return {
+      reportId,
+      status: `Generated ${inputData.reportType} report for ${inputData.date}`,
+      generatedAt: new Date().toISOString(),
+    };
+  },
+});
+
+export const dailyReportWorkflow = createWorkflow({
+  id: 'daily-report',
+  description: 'Generates daily reports',
+  inputSchema: z.object({
+    date: z.string(),
+    reportType: z.enum(['summary', 'detailed']).default('summary'),
+  }),
+  outputSchema: z.object({
+    reportId: z.string(),
+    status: z.string(),
+    generatedAt: z.string(),
+  }),
+})
+  .then(generateReportStep)
+  .commit();
+
+// --- Payment Processor Workflow ---
+
+const processPaymentStep = createStep({
+  id: 'process-payment',
+  description: 'Processes a payment transaction',
+  inputSchema: z.object({
+    amount: z.number(),
+    currency: z.string(),
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    transactionId: z.string(),
+    status: z.string(),
+    processedAt: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const transactionId = `TXN-${Date.now()}`;
+
+    return {
+      transactionId,
+      status: `Processed ${inputData.currency} ${inputData.amount} for customer ${inputData.customerId}`,
+      processedAt: new Date().toISOString(),
+    };
+  },
+});
+
+export const paymentProcessorWorkflow = createWorkflow({
+  id: 'payment-processor',
+  description: 'Processes payment transactions',
+  inputSchema: z.object({
+    amount: z.number(),
+    currency: z.string(),
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    transactionId: z.string(),
+    status: z.string(),
+    processedAt: z.string(),
+  }),
+})
+  .then(processPaymentStep)
+  .commit();
+
+```

package/.docs/raw/agents/agent-approval.mdx

@@ -0,0 +1,189 @@
+---
+title: "Agent Approval | Agents"
+description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+---
+
+# Agent Approval
+
+Agents sometimes require the same [human-in-the-loop](/docs/v1/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or performing running long processes. With agent approval you can suspend a tool call and provide feedback to the user, or approve or decline a tool call based on targeted application conditions.
+
+## Tool call approval
+
+Tool call approval can be enabled at the agent level and apply to every tool the agent uses, or at the tool level providing more granular control over individual tool calls.
+
+### Storage
+
+Agent approval uses a snapshot to capture the state of the request. Ensure you've enabled a storage provider in your main Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core/mastra";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  // ...
+  storage: new LibSQLStore({
+    id: "mastra-storage",
+    url: ":memory:"
+  })
+});
+```
+
+
+## Agent-level approval
+
+When calling an agent using `.stream()` set `requireToolApproval` to `true` which will prevent the agent from calling any of the tools defined in its configuration.
+
+```typescript showLineNumbers
+const stream = await agent.stream("What's the weather in London?", {
+  requireToolApproval: true
+});
+```
+
+### Approving tool calls
+
+To approve a tool call, access `approveToolCall` from the `agent`, passing in the `runId` of the stream. This will let the agent know its now OK to call its tools.
+
+```typescript showLineNumbers
+const handleApproval = async () => {
+  const approvedStream = await agent.approveToolCall({ runId: stream.runId });
+
+  for await (const chunk of approvedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+### Declining tool calls
+
+To decline a tool call, access the `declineToolCall` from the `agent`. You will see the streamed response from the agent, but it won't call its tools.
+
+```typescript showLineNumbers
+const handleDecline = async () => {
+  const declinedStream = await agent.declineToolCall({ runId: stream.runId });
+
+  for await (const chunk of declinedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+## Tool-level approval
+
+There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.
+
+### Tool approval using `requireToolApproval`
+
+In this approach, `requireApproval` is configured on the tool definition (shown below) rather than on the agent.
+
+```typescript
+export const testTool = createTool({
+  id: "test-tool",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  execute: async ({ location }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  },
+  requireApproval: true
+});
+```
+
+When `requireApproval` is true for a tool, the stream will include chunks of type `tool-call-approval` to indicate that the call is paused. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-approval") {
+    console.log("Approval required.");
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+
+### Tool approval using `suspend`
+
+With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool implementation calls `suspend` to pause execution and return context or confirmation prompts to the user.
+
+```typescript
+
+export const testToolB = createTool({
+  id: "test-tool-b",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  execute: async ({ location }, { agent } = {}) => {
+    const { resumeData: { approved } = {}, suspend } = agent ?? {};
+
+    if (!approved) {
+      return suspend?.({ reason: "Approval required." });
+    }
+
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  }
+});
+```
+
+With this approach the stream will include a `tool-call-suspended` chunk, and the `suspendPayload` will contain the `reason` defined by the tool's `suspendSchema`. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-suspended") {
+    console.log(chunk.payload.suspendPayload);
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+
+```
+
+## Related
+
+- [Using Tools](./using-tools)
+- [Agent Overview](./overview)
+- [Tools Overview](../mcp/overview)
+- [Agent Memory](./agent-memory)
+- [Request Context](/docs/v1/server-db/request-context)

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

@@ -33,7 +33,7 @@ export const moderatedAgent = new Agent({
   model: "openai/gpt-5.1",
   inputProcessors: [
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       categories: ["hate", "harassment", "violence"],
       threshold: 0.7,
       strategy: "block",
@@ -82,7 +82,7 @@ export const secureAgent = new Agent({
   // ...
   inputProcessors: [
     new PromptInjectionDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.8,
       strategy: "rewrite",
       detectionTypes: ["injection", "jailbreak", "system-override"],
@@ -106,7 +106,7 @@ export const multilingualAgent = new Agent({
   // ...
   inputProcessors: [
     new LanguageDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       targetLanguages: ["English", "en"],
       strategy: "translate",
       threshold: 0.8,
@@ -179,7 +179,7 @@ const scrubbedAgent = new Agent({
   name: "Scrubbed Agent",
   outputProcessors: [
     new SystemPromptScrubber({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "redact",
       customPatterns: ["system prompt", "internal instructions"],
       includeDetections: true,
@@ -194,6 +194,10 @@ const scrubbedAgent = new Agent({
 
 > See [SystemPromptScrubber](/reference/v1/processors/system-prompt-scrubber) for a full list of configuration options.
 
+:::note
+When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](/docs/v1/server-db/mastra-server#stream-data-redaction) for details.
+:::
+
 ## Hybrid processors
 
 Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They are useful for tasks like content moderation and PII redaction.
@@ -211,7 +215,7 @@ export const moderatedAgent = new Agent({
   // ...
   inputProcessors: [
     new ModerationProcessor({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.7,
       strategy: "block",
       categories: ["hate", "harassment", "violence"],
@@ -240,7 +244,7 @@ export const privateAgent = new Agent({
   // ...
   inputProcessors: [
     new PIIDetector({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.6,
       strategy: "redact",
       redactionMethod: "mask",
@@ -364,6 +368,6 @@ If the built-in processors don’t cover your needs, you can create your own by
 
 Available examples:
 
-- [Message Length Limiter](/examples/v1/processors/message-length-limiter)
-- [Response Length Limiter](/examples/v1/processors/response-length-limiter)
-- [Response Validator](/examples/v1/processors/response-validator)
+- [Message Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-message-length-limiter)
+- [Response Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-length-limiter)
+- [Response Validator](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-validator)

package/.docs/raw/agents/networks.mdx

@@ -240,3 +240,4 @@ network-execution-event-step-finish
 - [Agent Memory](./agent-memory)
 - [Workflows Overview](../workflows/overview)
 - [Request Context](/docs/v1/server-db/request-context)
+- [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)