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

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,23 +25,23 @@
     "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": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",

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/agents/using-tools-and-mcp.mdx

@@ -75,8 +75,6 @@ Once you have a server you want to use with your agent, import the Mastra `MCPCl
 
 ```typescript filename="src/mastra/mcp.ts" {1,7-16}
 import { MCPClient } from "@mastra/mcp";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 // Configure MCPClient to connect to your server(s)
 export const mcp = new MCPClient({
@@ -96,7 +94,10 @@ export const mcp = new MCPClient({
 Then connect your agent to the server tools:
 
 ```typescript filename="src/mastra/agents/mcpAgent.ts" {7}
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
 import { mcp } from "../mcp";
+
 // Create an agent and add tools from the MCP client
 const agent = new Agent({
   name: "Agent with MCP Tools",

package/.docs/raw/deployment/cloud-providers/digital-ocean.mdx

@@ -0,0 +1,111 @@
+---
+title: "Digital Ocean"
+description: "Deploy your Mastra applications to Digital Ocean."
+---
+
+import { Callout, Steps, Tabs } from "nextra/components";
+import ServerConfig from "@/components/content-blocks/server-config.mdx";
+
+## Digital Ocean
+
+Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
+
+<Callout>
+  This guide assumes your Mastra application has been created using the default
+  `npx create-mastra@latest` command.
+  For more information on how to create a new Mastra application,
+  refer to our [getting started guide](./../../getting-started/installation.mdx)
+</Callout>
+
+<Tabs items={["App Platform", "Droplets"]}>
+
+<Tabs.Tab>
+
+### App Platform
+
+#### Prerequisites [#app-platform-prerequisites]
+
+- A Git repository containing your Mastra application. This can be a GitHub repository, GitLab repository, or any other compatible source provider.
+- A Digital Ocean account
+
+#### Deployment Steps
+
+<Steps>
+
+#### Create a new App
+
+- Log in to your Digital Ocean dashboard.
+- Navigate to the App Platform service.
+- Select your source provider and create a new app.
+
+#### Configure Deployment Source
+
+- Connect and select your repository. You may also choose a container image or a sample app.
+- Select the branch you want to deploy from.
+- Configure the source directory if necessary. If your Mastra application uses the default directory structure, no action is required here.
+- Head to the next step.
+
+#### Configure Resource Settings and Environment Variables
+
+- A Node.js build should be detected automatically.
+- Add any required environment variables for your Mastra application. This includes API keys, database URLs, and other configuration values.
+- You may choose to configure the size of your resource here.
+- Other things you may optionally configure include, the region of your resource, the unique app name, and what project the resource belongs to.
+- Once you're done, you may create the app after reviewing your configuration and pricing estimates.
+
+#### Deployment
+
+- Your app will be built and deployed automatically.
+- Digital Ocean will provide you with a URL to access your deployed application.
+
+</Steps>
+
+You can now access your deployed application at the URL provided by Digital Ocean.
+
+<Callout>
+The Digital Ocean App Platform uses an ephemeral file system,
+meaning that any files written to the file system are short-lived and may be lost.
+Avoid using a Mastra storage provider that uses the file system,
+such as `LibSQLStore` with a file URL.
+</Callout>
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+### Droplets
+
+Deploy your Mastra application to Digital Ocean's Droplets.
+This guide will cover setting up a droplet, a reverse proxy using Nginx, and running your Mastra application.
+
+<Callout>
+The guide assumes your droplet runs Ubuntu 24+.
+</Callout>
+
+#### Prerequisites [#droplets-prerequisites]
+
+- A Digital Ocean account
+- A droplet running Ubuntu 24+
+- A domain name with an A record pointing to your droplet
+
+#### Setting up the droplet
+
+<ServerConfig />
+
+</Tabs.Tab>
+
+</Tabs>
+
+### Connect to your Mastra server
+
+You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.
+
+Refer to the [`MastraClient` documentation](../../client-js/overview.mdx) for more information.
+
+```typescript copy showLineNumbers
+import { MastraClient } from "@mastra/client-js";
+
+const mastraClient = new MastraClient({
+  baseUrl: "https://<your-domain-name>",
+});
+```

package/.docs/raw/deployment/cloud-providers/index.mdx

@@ -0,0 +1,15 @@
+---
+title: "Cloud Providers"
+description: "Deploy your Mastra applications to popular cloud providers."
+asIndexPage: true
+---
+
+import { CardGrid, CardGridItem } from "@/components/cards/card-grid";
+
+## Cloud Providers
+
+Deploy your Mastra applicaitons to popular cloud providers.
+
+<CardGrid>
+  <CardGridItem title="Digital Ocean" description="Deploy your Mastra applications to Digital Ocean" href="./cloud-providers/digital-ocean" />
+</CardGrid>

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