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

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