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

package/.docs/organized/code-examples/memory-per-resource-example.md

@@ -13,7 +13,7 @@
     "tsx": "^4.19.2"
   },
   "devDependencies": {
-    "@types/node": "^20.19.0",
+    "@types/node": "22.13.17",
     "typescript": "^5.8.3"
   }
 }

package/.docs/organized/code-examples/memory-with-processors.md

@@ -68,7 +68,7 @@ const agent = new Agent({
   id: 'forgetful-job-interviewer',
   name: 'Forgetful Job Interviewer',
   instructions:
-    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
+    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarrassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
   model: openai('gpt-4o'),
   memory: new Memory({
     processors: [

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -29,7 +29,7 @@
   "devDependencies": {
     "@libsql/client": "^0.15.4",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "@types/react": "^19.1.9",
     "@types/react-dom": "^19.1.7",
     "@types/react-syntax-highlighter": "^15.5.13",

package/.docs/organized/code-examples/processors-with-ai-sdk.md

@@ -0,0 +1,14 @@
+### package.json
+```json
+{
+  "name": "examples-processors-with-ai-sdk",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/ai-sdk": "latest",
+    "@mastra/core": "latest",
+    "@mastra/libsql": "latest",
+    "ai": "latest",
+    "zod": "^3.25.76"
+  }
+}
+```

package/.docs/organized/code-examples/quick-start.md

@@ -3,7 +3,7 @@
 {
   "name": "examples-quick-start",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
     "zod": "^3.25.76"
@@ -64,7 +64,7 @@ export const catOne = new Agent({
   id: 'cat-one',
   name: 'Cat One',
   instructions:
-    'You are a feline expert with comprehensive knowledge of all cat species, from domestic breeds to wild big cats. As a lifelong cat specialist, you understand their behavior, biology, social structures, and evolutionary history in great depth. If you are asked for a specie name, do not return a paragraph, a succint two or three letter name of the species will suffice.',
+    'You are a feline expert with comprehensive knowledge of all cat species, from domestic breeds to wild big cats. As a lifelong cat specialist, you understand their behavior, biology, social structures, and evolutionary history in great depth. If you are asked for a specie name, do not return a paragraph, a succinct two or three letter name of the species will suffice.',
   model: openai('gpt-4o'),
 });
 

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 { HonoBindings, HonoVariables, 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<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+  const adapter = new MastraServer({ app, 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/organized/code-examples/server-express-adapter.md

@@ -0,0 +1,87 @@
+### package.json
+```json
+{
+  "name": "examples-server-express-adapter",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/express": "latest",
+    "express": "^5.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### mastra/agents/assistant.ts
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+export const assistantAgent = new Agent({
+  id: 'assistantAgent',
+  name: 'Assistant',
+  instructions: 'You are a helpful assistant. Answer questions concisely.',
+  model: openai('gpt-4o-mini'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { assistantAgent } from './agents/assistant';
+
+export const mastra = new Mastra({
+  agents: { assistantAgent },
+});
+
+```
+
+### server.ts
+```typescript
+/**
+ * Express Server Adapter Example
+ *
+ * This demonstrates how to use @mastra/express to run Mastra with Express.
+ *
+ * Features shown:
+ * - Basic server setup with MastraServer
+ * - Required express.json() middleware
+ * - Custom routes added after init()
+ * - Accessing Mastra context via res.locals
+ */
+
+import express from 'express';
+import { MastraServer } from '@mastra/express';
+
+import { mastra } from './mastra';
+
+const app = express();
+app.use(express.json()); // Required for body parsing
+
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+// Custom route with access to Mastra context via res.locals
+app.get('/health', (req, res) => {
+  const mastraInstance = res.locals.mastra;
+  const agents = Object.keys(mastraInstance.listAgents());
+  res.json({ status: 'ok', agents });
+});
+
+const port = 4111;
+
+app.listen(port, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+
+```

package/.docs/organized/code-examples/server-hono-adapter.md

@@ -0,0 +1,85 @@
+### package.json
+```json
+{
+  "name": "examples-server-hono-adapter",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/hono": "latest",
+    "@hono/node-server": "^1.14.3",
+    "hono": "^4.10.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### mastra/agents/assistant.ts
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+export const assistantAgent = new Agent({
+  id: 'assistantAgent',
+  name: 'Assistant',
+  instructions: 'You are a helpful assistant. Answer questions concisely.',
+  model: openai('gpt-4o-mini'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { assistantAgent } from './agents/assistant';
+
+export const mastra = new Mastra({
+  agents: { assistantAgent },
+});
+
+```
+
+### server.ts
+```typescript
+/**
+ * Hono Server Adapter Example
+ *
+ * This demonstrates how to use @mastra/hono to run Mastra with Hono.
+ *
+ * Features shown:
+ * - Basic server setup with MastraServer
+ * - Custom routes added after init()
+ * - Accessing Mastra context in custom routes
+ */
+
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
+
+import { mastra } from './mastra';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+// Custom route with access to Mastra context
+app.get('/health', c => {
+  const mastraInstance = c.get('mastra');
+  const agents = Object.keys(mastraInstance.listAgents());
+  return c.json({ status: 'ok', agents });
+});
+
+const port = 4111;
+
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+
+```

package/.docs/organized/code-examples/stock-price-tool.md

@@ -8,10 +8,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@jest/globals": "^29.7.0",
-    "jest": "^29.7.0",
-    "mastra": "latest",
-    "ts-jest": "^29.2.6"
+    "mastra": "latest"
   }
 }
 ```
@@ -93,20 +90,3 @@ export const stockPrices = createTool({
 });
 
 ```
-
-### mastra/tools/tools.test.ts
-```typescript
-import { describe, it, expect } from 'vitest';
-
-import { getStockPrice } from './stock-price';
-
-describe('Test Tools', () => {
-  it('should run the stockPrices', async () => {
-    const result = await getStockPrice('AAPL');
-
-    console.log(result);
-    expect(result).toBeDefined();
-  });
-});
-
-```

package/.docs/organized/code-examples/workflow-ai-recruiter.md

@@ -3,7 +3,7 @@
 {
   "name": "examples-workflow-ai-recruiter",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",

package/.docs/organized/code-examples/workflow-with-inline-steps.md

@@ -3,7 +3,7 @@
 {
   "name": "workflow-with-inline-steps",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",

package/.docs/organized/code-examples/workflow-with-memory.md

@@ -3,7 +3,7 @@
 {
   "name": "examples-workflow-with-memory",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",
     "zod": "^3.25.76"

package/.docs/organized/code-examples/workflow-with-separate-steps.md

@@ -3,7 +3,7 @@
 {
   "name": "examples-workflow-with-separate-steps",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",

package/.docs/organized/code-examples/workflow-with-suspend-resume.md

@@ -3,7 +3,7 @@
 {
   "name": "examples-workflow-with-suspend-resume",
   "devDependencies": {
-    "@types/node": "^20.17.57",
+    "@types/node": "22.13.17",
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",