@mastra/mcp-docs-server 0.13.2-alpha.0 → 0.13.2-alpha.1

package/.docs/organized/code-examples/crypto-chatbot.md

@@ -70,7 +70,7 @@
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "usehooks-ts": "^3.1.1",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "pnpm": {
     "overrides": {
@@ -86,10 +86,10 @@
     "@types/d3-scale": "^4.0.9",
     "@types/node": "^22.15.29",
     "@types/pdf-parse": "^1.1.4",
-    "@types/react": "^19.1",
-    "@types/react-dom": "^19.1",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
     "drizzle-kit": "^0.31.0",
-    "eslint": "^9.28.0",
+    "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.10.1",

package/.docs/organized/code-examples/experimental-auth-weather-agent.md

@@ -23,7 +23,7 @@
     "@mastra/auth-auth0": "latest",
     "@mastra/auth-workos": "latest",
     "@mastra/auth-clerk": "latest",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "dotenv-cli": "^8.0.0"

package/.docs/organized/code-examples/fireworks-r1.md

@@ -23,7 +23,7 @@
     "gradient-string": "^3.0.0",
     "ora": "^8.2.0",
     "tinycolor2": "^1.6.0",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "@types/node": "^20.17.57",

package/.docs/organized/code-examples/mcp-configuration.md

@@ -19,9 +19,9 @@
     "@mastra/core": "latest",
     "@mastra/mcp": "latest",
     "@mastra/memory": "latest",
-    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@modelcontextprotocol/sdk": "^1.13.0",
     "chalk": "^5.4.1",
-    "zod": "^3.25.56",
+    "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {

package/.docs/organized/code-examples/mcp-registry-registry.md

@@ -19,7 +19,7 @@
     "@mastra/core": "latest",
     "@mastra/mcp": "latest",
     "@mastra/mcp-registry-registry": "latest",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "pnpm": {
     "overrides": {

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

@@ -0,0 +1,236 @@
+### package.json
+```json
+{
+  "name": "memory-per-resource-example",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/example.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^0.0.68",
+    "@mastra/core": "latest",
+    "@mastra/memory": "latest",
+    "@mastra/libsql": "latest",
+    "chalk": "^5.3.0",
+    "dotenv": "^16.4.7",
+    "ora": "^8.1.1",
+    "tsx": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.8.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "@mastra/core": "link:../../packages/core",
+      "@mastra/memory": "link:../../packages/memory",
+      "@mastra/libsql": "link:../../stores/libsql"
+    }
+  }
+}
+
+```
+
+### example.ts
+```typescript
+import { maskStreamTags } from '@mastra/core/utils';
+import chalk from 'chalk';
+import { randomUUID } from 'crypto';
+import ora from 'ora';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra';
+
+const agent = mastra.getAgent('assistantAgent');
+
+// 🆕 EXAMPLE: Per-Resource Working Memory
+// This demonstrates how working memory persists across different conversation threads
+// for the same user (resourceId), but is separate for different users.
+
+console.log(chalk.bold.blue('\n🆕 Per-Resource Working Memory Example\n'));
+console.log(chalk.gray('This example shows how working memory persists across conversation threads'));
+console.log(chalk.gray('for the same user, but stays separate for different users.\n'));
+
+// Simulate different users
+const USERS = {
+  alice: 'user-alice-123',
+  bob: 'user-bob-456',
+  demo: 'demo-user-789',
+};
+
+// Let user choose which user to simulate
+console.log(chalk.yellow('Choose a user to simulate:'));
+console.log(chalk.cyan('1. Alice (user-alice-123)'));
+console.log(chalk.cyan('2. Bob (user-bob-456)'));
+console.log(chalk.cyan('3. Demo User (demo-user-789)'));
+console.log(chalk.gray('4. Or just press Enter to use a random user\n'));
+
+const rl = Readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const userChoice = await new Promise<string>(resolve => {
+  rl.question(chalk.yellow('Enter choice (1-4 or Enter): '), answer => {
+    resolve(answer.trim());
+  });
+});
+
+let resourceId: string;
+let userName: string;
+
+switch (userChoice) {
+  case '1':
+    resourceId = USERS.alice;
+    userName = 'Alice';
+    break;
+  case '2':
+    resourceId = USERS.bob;
+    userName = 'Bob';
+    break;
+  case '3':
+    resourceId = USERS.demo;
+    userName = 'Demo User';
+    break;
+  default:
+    resourceId = `user-${randomUUID()}`;
+    userName = 'Random User';
+}
+
+// Always generate a new thread ID to demonstrate cross-thread persistence
+const threadId = randomUUID();
+
+console.log(chalk.green(`\n✅ Simulating: ${userName}`));
+console.log(chalk.gray(`📧 Resource ID: ${resourceId}`));
+console.log(chalk.gray(`🧵 Thread ID: ${threadId}`));
+console.log(chalk.bold.yellow('\n💡 TIP: Run this example multiple times with the same user choice'));
+console.log(chalk.bold.yellow('   to see how working memory persists across conversation threads!\n'));
+
+async function logResponse(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(chalk.blue('\n🤖 Assistant:'));
+
+  const memorySpinner = ora('💾 Updating memory...');
+
+  // Mask working memory updates with a spinner
+  const maskedStream = maskStreamTags(res.textStream, 'working_memory', {
+    onStart: () => memorySpinner.start(),
+    onEnd: () => {
+      if (memorySpinner.isSpinning) {
+        memorySpinner.succeed(chalk.green('💾 Memory updated!'));
+      }
+    },
+  });
+
+  for await (const chunk of maskedStream) {
+    process.stdout.write(chunk);
+  }
+  console.log('\n');
+}
+
+async function main() {
+  // Start the conversation
+  await logResponse(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: `New conversation thread started at ${new Date().toISOString()}. 
+        This may be a returning user - check your working memory to see if you know them already.
+        If this is a new user, introduce yourself and learn about them.
+        If this is a returning user, greet them warmly and reference what you remember!`,
+        },
+      ],
+      { threadId, resourceId },
+    ),
+  );
+
+  // Interactive chat loop
+  while (true) {
+    const userInput: string = await new Promise(resolve => {
+      rl.question(chalk.yellow('\n💬 You: '), answer => {
+        resolve(answer);
+      });
+    });
+
+    if (userInput.toLowerCase() === 'exit' || userInput.toLowerCase() === 'quit') {
+      console.log(chalk.gray('\n👋 Goodbye! Run the example again to see memory persistence!\n'));
+      break;
+    }
+
+    await logResponse(await agent.stream(userInput, { threadId, resourceId }));
+  }
+
+  rl.close();
+}
+
+main().catch(console.error);
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { LibSQLStore } from '@mastra/libsql';
+
+// Create LibSQL storage for persistent per-resource working memory
+const storage = new LibSQLStore({
+  url: 'file:./memory-demo.db',
+});
+
+export const memory = new Memory({
+  storage,
+  options: {
+    lastMessages: 5,
+    workingMemory: {
+      enabled: true,
+      scope: 'resource', // 🆕 NEW: Per-resource working memory!
+      template: `# User Profile
+- **Name**: 
+- **Location**: 
+- **Interests**: 
+- **Preferences**: 
+- **Goals**: 
+- **Important Notes**: 
+`,
+    },
+  },
+});
+
+export const assistantAgent = new Agent({
+  name: 'Personal Assistant',
+  instructions: `You are a helpful personal assistant with persistent memory across ALL conversations.
+
+🆕 IMPORTANT: You have resource-scoped working memory! This means:
+- Everything you learn about this user persists across ALL conversation threads
+- Even if they start a completely new conversation, you'll remember them
+- You should build up a comprehensive profile of the user over time
+
+Always use <working_memory> tags to update what you know about the user:
+- Their name and personal details
+- Their interests and preferences  
+- Their goals and what they're working on
+- Any important context from previous conversations
+
+When you first meet someone, ask for their name and learn about them. In subsequent conversations (even new threads), greet them by name and reference what you remember!`,
+  model: openai('gpt-4o-mini'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { assistantAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { assistantAgent },
+});
+
+```

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

@@ -18,7 +18,7 @@
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",
     "@mastra/mem0": "latest",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "pnpm": {
     "overrides": {

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

@@ -20,7 +20,7 @@
     "js-tiktoken": "^1.0.13",
     "tiktoken": "^1.0.13",
     "tsx": "^4.6.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "pnpm": {
     "overrides": {

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

@@ -25,21 +25,21 @@
     "clsx": "^2.1.1",
     "lucide-react": "^0.454.0",
     "next": "15.2.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "react-syntax-highlighter": "^15.6.1",
     "sharp": "^0.33.5",
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "vaul": "^1.1.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "@libsql/client": "^0.15.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.17.57",
-    "@types/react": "^19.0.10",
-    "@types/react-dom": "^19.0.4",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
     "@types/react-syntax-highlighter": "^15.5.13",
     "eslint": "^8.57.1",
     "eslint-config-next": "15.3.3",

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

@@ -16,7 +16,7 @@
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^1.2.12",

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

@@ -16,7 +16,7 @@
   "dependencies": {
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",

package/.docs/organized/code-examples/weather-agent.md

@@ -16,7 +16,7 @@
     "@ai-sdk/openai": "^1.3.22",
     "@mastra/core": "latest",
     "@mastra/libsql": "latest",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "version": "0.0.1",
   "pnpm": {

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

@@ -19,7 +19,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "dependencies": {
     "@ai-sdk/openai": "latest",

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

@@ -17,7 +17,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "dependencies": {
     "@mastra/core": "latest"

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

@@ -16,7 +16,7 @@
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "dependencies": {
     "@ai-sdk/openai": "latest",

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

@@ -19,7 +19,7 @@
     "mastra": "latest",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "zod": "^3.25.56"
+    "zod": "^3.25.67"
   },
   "dependencies": {
     "@mastra/core": "latest"

package/.docs/raw/frameworks/agentic-uis/copilotkit.mdx

@@ -85,24 +85,24 @@ The current version of the integration leverages `MastraClient` to format Mastra
 {/*
 LLM CONTEXT: This Tabs component shows installation commands for the Mastra AGUI package.
 Each tab displays the installation command for that specific package manager.
-This installs the alpha version of @mastra/agui which provides CopilotKit integration capabilities.
-All commands install the same @mastra/agui@alpha package but use different package manager syntax.
+This installs the alpha version of @ag-ui/mastra which provides CopilotKit integration capabilities.
+All commands install the same @ag-ui/mastra package but use different package manager syntax.
 */}
 
 <Tabs items={["npm", "yarn", "pnpm"]}>
   <Tabs.Tab>
     ```bash copy
-    npm install @mastra/agui@alpha
+    npm install @ag-ui/mastra
     ```
   </Tabs.Tab>
   <Tabs.Tab>
     ```bash copy
-    yarn add @mastra/agui@alpha
+    yarn add @ag-ui/mastra
     ```
   </Tabs.Tab>
   <Tabs.Tab>
     ```bash copy
-    pnpm add @mastra/agui@alpha
+    pnpm add @ag-ui/mastra
     ```
   </Tabs.Tab>
 </Tabs>
@@ -114,7 +114,7 @@ import { Mastra } from "@mastra/core/mastra";
 import { PinoLogger } from "@mastra/loggers";
 import { LibSQLStore } from "@mastra/libsql";
 import { CopilotRuntime, copilotRuntimeNodeHttpEndpoint, ExperimentalEmptyAdapter } from "@copilotkit/runtime";
-import { registerCopilotKit } from "@mastra/agui";
+import { registerCopilotKit } from "@ag-ui/mastra";
 import { weatherAgent } from "./agents/weather-agent";
 
 const serviceAdapter = new ExperimentalEmptyAdapter();
@@ -231,6 +231,7 @@ import {
   copilotRuntimeNextJSAppRouterEndpoint,
 } from "@copilotkit/runtime";
 import { NextRequest } from "next/server";
+import { MastraAgent } from "@ag-ui/mastra";
 
 export const POST = async (req: NextRequest) => {
   // Clone the request before reading the body
@@ -238,11 +239,52 @@ export const POST = async (req: NextRequest) => {
   const body = await clonedReq.json();
   const resourceId = body.resourceId || "TEST";
 
-  const mastraAgents = getAGUI({
-    mastra,
+  const mastraAgents = MastraAgent.getLocalAgents({
     resourceId,
+    mastra,
+    runtimeContext,
+  });
+
+  const runtime = new CopilotRuntime({
+    agents: mastraAgents,
+  });
+
+  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
+    runtime,
+    serviceAdapter: new ExperimentalEmptyAdapter(),
+    endpoint: "/api/copilotkit",
+  });
+
+  // Use the original request for handleRequest
+  return handleRequest(req);
+};
+```
+
+## Using with Mastra Client SDK
+
+```typescript copy
+import { MastraClient } from "@mastra/client-js";
+import {
+  CopilotRuntime,
+  ExperimentalEmptyAdapter,
+  copilotRuntimeNextJSAppRouterEndpoint,
+} from "@copilotkit/runtime";
+import { NextRequest } from "next/server";
+import { MastraAgent } from "@ag-ui/mastra";
+
+export const POST = async (req: NextRequest) => {
+  // Clone the request before reading the body
+  const clonedReq = req.clone();
+  const body = await clonedReq.json();
+  const resourceId = body.resourceId || "TEST";
+
+  const baseUrl = process.env.MASTRA_BASE_URL || "http://localhost:4111";
+  const mastraClient = new MastraClient({
+    baseUrl,
   });
 
+  const mastraAgents = await MastraAgent.getRemoteAgents({ mastraClient });
+
   const runtime = new CopilotRuntime({
     agents: mastraAgents,
   });
@@ -258,7 +300,8 @@ export const POST = async (req: NextRequest) => {
 };
 ```
 
-### Using Typed Runtime Context
+
+## Using Typed Runtime Context
 
 For better type safety, you can specify the type of your runtime context:
 
@@ -266,7 +309,7 @@ For better type safety, you can specify the type of your runtime context:
 import { Mastra } from "@mastra/core/mastra";
 import { PinoLogger } from "@mastra/loggers";
 import { LibSQLStore } from "@mastra/libsql";
-import { registerCopilotKit } from "@mastra/agui";
+import { registerCopilotKit } from "@ag-ui/mastra";
 import { weatherAgent } from "./agents";
 
 // Define your runtime context type

package/.docs/raw/mastra-cloud/dashboard.mdx

@@ -0,0 +1,100 @@
+---
+title: Understanding the Mastra Cloud Dashboard
+description: Details of each feature available in Mastra Cloud
+---
+
+import { MastraCloudCallout } from '@/components/mastra-cloud-callout'
+
+# Navigating the Dashboard
+
+This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Playground](/docs/mastra-cloud/dashboard#playground).
+
+<MastraCloudCallout />
+
+## Overview
+
+The **Overview** page provides details about your application, including its domain URL, status, latest deployment, and connected agents and workflows.
+
+![Project dashboard](/image/mastra-cloud/mastra-cloud-project-dashboard.jpg)
+
+Key features:
+
+Each project shows its current deployment status, active domains, and environment variables, so you can quickly understand how your application is running.
+
+## Deployments
+
+The **Deployments** page shows recent builds and gives you quick access to detailed build logs. Click any row to view more information about a specific deployment.
+
+![Dashboard deployment](/image/mastra-cloud/mastra-cloud-dashboard-deployments.jpg)
+
+Key features:
+
+Each deployment includes its current status, the Git branch it was deployed from, and a title generated from the commit hash.
+
+## Logs
+
+The **Logs** page is where you'll find detailed information to help debug and monitor your application's behavior in the production environment.
+
+![Dashboard logs](/image/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
+
+Key features:
+
+Each log includes a severity level and detailed messages showing agent, workflow, and storage activity.
+
+## Settings
+
+On the **Settings** page you can modify the configuration of your application.
+
+![Dashboard settings](/image/mastra-cloud/mastra-cloud-dashboard-settings.jpg)
+
+Key features:
+
+You can manage environment variables, edit key project settings like the name and branch, configure storage with LibSQLStore, and set a stable URL for your endpoints.
+
+> Changes to configuration require a new deployment before taking effect.
+
+## Playground
+
+### Agents
+
+On the **Agents** page you'll see all agents used in your application. Click any agent to interact using the chat interface.
+
+![Dashboard playground agents](/image/mastra-cloud/mastra-cloud-dashboard-playground-agents.jpg)
+
+Key features:
+
+Test your agents in real time using the chat interface, review traces of each interaction, and see evaluation scores for every response.
+
+### Workflows
+
+On the **Workflows** page you'll see all workflows used in your application. Click any workflow to interact using the runner interface.
+
+![Dashboard playground workflows](/image/mastra-cloud/mastra-cloud-dashboard-playground-workflows.jpg)
+
+Key features:
+
+Visualize your workflow with a step-by-step graph, view execution traces, and run workflows directly using the built-in runner.
+
+### Tools
+
+On the **Tools** page you'll see all tools used by your agents. Click any tool to interact using the input interface.
+
+![Dashboard playground tools](/image/mastra-cloud/mastra-cloud-dashboard-playground-tools.jpg)
+
+Key features:
+
+Test your tools by providing an input that matches the schema and viewing the structured output.
+
+## MCP Servers
+
+The **MCP Servers** page lists all MCP Servers included in your application. Click any MCP Server for more information.
+
+![Dashboard playground mcp servers](/image/mastra-cloud/mastra-cloud-dashboard-playground-mcpservers.jpg)
+
+Key features:
+
+Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configuration snippets for tools like Cursor and Windsurf.
+
+## Next steps
+
+- [Understanding Tracing and Logs](/docs/mastra-cloud/observability)