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

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

@@ -50,21 +50,147 @@
 ### client.ts
 ```typescript
 import { MCPClient } from '@mastra/mcp';
+// import type { ElicitationHandler } from '@mastra/mcp';
+import { createInterface } from 'readline';
+
+// Create readline interface for user input
+const readline = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// Helper function to prompt user for input
+function askQuestion(question: string): Promise<string> {
+  return new Promise(resolve => {
+    readline.question(question, answer => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Elicitation handler that prompts the user for input
+const elicitationHandler = async request => {
+  console.log('\n🔔 Elicitation Request Received:');
+  console.log(`Message: ${request.message}`);
+  console.log('Requested Schema:');
+  console.log(JSON.stringify(request.requestedSchema, null, 2));
+
+  const schema = request.requestedSchema;
+  const properties = schema.properties;
+  const required = schema.required || [];
+
+  console.log('\nPlease provide the following information:');
+
+  const content: Record<string, unknown> = {};
+
+  // Collect input for each field
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    const field = fieldSchema as {
+      type?: string;
+      title?: string;
+      description?: string;
+      format?: string;
+    };
+
+    const isRequired = required.includes(fieldName);
+    let prompt = `${field.title || fieldName}`;
+
+    // Add helpful information to the prompt
+    if (field.description) {
+      prompt += ` (${field.description})`;
+    }
+    if (field.format) {
+      prompt += ` [format: ${field.format}]`;
+    }
+    if (isRequired) {
+      prompt += ' *required*';
+    }
+
+    prompt += ': ';
+
+    const answer = await askQuestion(prompt);
+
+    // Check for cancellation
+    if (answer.toLowerCase() === 'cancel' || answer.toLowerCase() === 'c') {
+      return { action: 'cancel' as const };
+    }
+
+    // Handle empty responses
+    if (answer === '' && isRequired) {
+      console.log(`❌ Error: ${fieldName} is required`);
+      return { action: 'reject' as const };
+    } else if (answer !== '') {
+      content[fieldName] = answer;
+    }
+  }
+
+  // Show the collected data and ask for confirmation
+  console.log('\n✅ Collected data:');
+  console.log(JSON.stringify(content, null, 2));
+
+  const confirmAnswer = await askQuestion('\nSubmit this information? (yes/no/cancel): ');
+
+  if (confirmAnswer.toLowerCase() === 'yes' || confirmAnswer.toLowerCase() === 'y') {
+    return {
+      action: 'accept' as const,
+      content,
+    };
+  } else if (confirmAnswer.toLowerCase() === 'cancel' || confirmAnswer.toLowerCase() === 'c') {
+    return { action: 'cancel' as const };
+  } else {
+    return { action: 'reject' as const };
+  }
+};
 
 async function main() {
   const mcpClient = new MCPClient({
     servers: {
-      myMcpServer: {
-        url: new URL('http://localhost:4111/api/mcp/myMcpServer/mcp'),
+      myMcpServerTwo: {
+        url: new URL('http://localhost:4111/api/mcp/myMcpServerTwo/mcp'),
       },
     },
   });
 
-  const tools = await mcpClient.getTools();
-  console.log('Tools:', tools);
+  mcpClient.elicitation.onRequest('myMcpServerTwo', elicitationHandler);
+
+  try {
+    console.log('Connecting to MCP server...');
+    const tools = await mcpClient.getTools();
+    console.log('Available tools:', Object.keys(tools));
+
+    // Test the elicitation functionality
+    console.log('\n🧪 Testing elicitation functionality...');
+
+    // Find the collectContactInfo tool
+    const collectContactInfoTool = tools['myMcpServerTwo_collectContactInfo'];
+    if (collectContactInfoTool) {
+      console.log('\nCalling collectContactInfo tool...');
+
+      try {
+        const result = await collectContactInfoTool.execute({
+          context: {
+            reason: 'We need your contact information to send you updates about our service.',
+          },
+        });
+
+        console.log('\n📋 Tool Result:');
+        console.log(result);
+      } catch (error) {
+        console.error('❌ Error calling collectContactInfo tool:', error);
+      }
+    } else {
+      console.log('❌ collectContactInfo tool not found');
+      console.log('Available tools:', Object.keys(tools));
+    }
+  } catch (error) {
+    console.error('❌ Error:', error);
+  } finally {
+    readline.close();
+    await mcpClient.disconnect();
+  }
 }
 
-main();
+main().catch(console.error);
 
 ```
 
@@ -664,6 +790,57 @@ export const myMcpServerTwo = new MCPServer({
         return `Hello, ${context.name}! Welcome to the MCP server.`;
       },
     }),
+    collectContactInfo: createTool({
+      id: 'collectContactInfo',
+      description: 'Collects user contact information through elicitation.',
+      inputSchema: z.object({
+        reason: z.string().optional().describe('Optional reason for collecting contact info'),
+      }),
+      execute: async ({ context }, options) => {
+        const { reason } = context;
+
+        try {
+          // Use the session-aware elicitation functionality
+          const result = await options.elicitation.sendRequest({
+            message: reason
+              ? `Please provide your contact information. ${reason}`
+              : 'Please provide your contact information',
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  title: 'Full Name',
+                  description: 'Your full name',
+                },
+                email: {
+                  type: 'string',
+                  title: 'Email Address',
+                  description: 'Your email address',
+                  format: 'email',
+                },
+                phone: {
+                  type: 'string',
+                  title: 'Phone Number',
+                  description: 'Your phone number (optional)',
+                },
+              },
+              required: ['name', 'email'],
+            },
+          });
+
+          if (result.action === 'accept') {
+            return `Thank you! Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
+          } else if (result.action === 'reject') {
+            return 'Contact information collection was declined by the user.';
+          } else {
+            return 'Contact information collection was cancelled by the user.';
+          }
+        } catch (error) {
+          return `Error collecting contact information: ${error}`;
+        }
+      },
+    }),
   },
 });
 

package/.docs/organized/code-examples/assistant-ui.md

@@ -30,7 +30,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "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/bird-checker-with-nextjs-and-eval.md

@@ -39,7 +39,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
-    "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/bird-checker-with-nextjs.md

@@ -38,7 +38,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "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/crypto-chatbot.md

@@ -91,8 +91,8 @@
     "drizzle-kit": "^0.31.0",
     "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-import-resolver-typescript": "^3.10.1",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-import-resolver-typescript": "^4.4.3",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-tailwindcss": "^3.18.0",
     "postcss": "^8.5.3",

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

@@ -41,7 +41,7 @@
     "@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/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/memory/working-memory.mdx

@@ -208,6 +208,61 @@ const paragraphMemory = new Memory({
 });
 ```
 
+## Structured Working Memory
+
+Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
+
+**Important:** You must specify either `template` or `schema`, but not both.
+
+### Example: Schema-Based Working Memory
+
+```typescript
+import { z } from 'zod';
+import { Memory } from '@mastra/memory';
+
+const userProfileSchema = z.object({
+  name: z.string().optional(),
+  location: z.string().optional(),
+  timezone: z.string().optional(),
+  preferences: z.object({
+    communicationStyle: z.string().optional(),
+    projectGoal: z.string().optional(),
+    deadlines: z.array(z.string()).optional(),
+  }).optional(),
+});
+
+const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+      schema: userProfileSchema,
+      // template: ... (do not set)
+    },
+  },
+});
+```
+
+When a schema is provided, the agent receives the working memory as a JSON object. For example:
+
+```json
+{
+  "name": "Sam",
+  "location": "Berlin",
+  "timezone": "CET",
+  "preferences": {
+    "communicationStyle": "Formal",
+    "projectGoal": "Launch MVP",
+    "deadlines": ["2025-07-01"]
+  }
+}
+```
+
+## Choosing Between Template and Schema
+
+- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad.
+- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON.
+- Only one mode can be active at a time: setting both `template` and `schema` is not supported.
+
 ## Example: Multi-step Retention
 
 Below is a simplified view of how the `User Profile` template updates across a short user
@@ -247,4 +302,5 @@ instructions on _how_ and _when_ to use this template in your agent's `instructi
 
 - [Streaming working memory](/examples/memory/streaming-working-memory)
 - [Using a working memory template](/examples/memory/streaming-working-memory-advanced)
+- [Using a working memory schema](/examples/memory/streaming-working-memory-structured)
 - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/.docs/raw/networks-vnext/complex-task-execution.mdx

@@ -0,0 +1,137 @@
+## Complex tasks requiring multiple primitives
+
+As an example, we have an AgentNetwork with 3 primitives at its disposal:
+
+- `agent1`: A general research agent that can do research on a given topic.
+- `agent2`: A general writing agent that can write a full report based on the researched material.
+- `workflow1`: A workflow that can research a given city and write a full report based on the researched material (using both agent1 and agent2).
+
+We use the `loop` method to create a task that requires multiple primitives. The AgentNetwork will, using memory, figure out which primitives to call and in which order, as well as when the task is complete.
+
+```typescript
+import { NewAgentNetwork } from '@mastra/core/network/vNext';
+import { Agent } from '@mastra/core/agent';
+import { createStep, createWorkflow } from '@mastra/core/workflows';
+import { Memory } from '@mastra/memory';
+import { openai } from '@ai-sdk/openai';
+import { LibSQLStore } from '@mastra/libsql';
+import { z } from 'zod';
+import { RuntimeContext } from '@mastra/core/runtime-context';
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    url: 'file:../mastra.db', // Or your database URL
+  }),
+});
+
+const agentStep1 = createStep({
+  id: 'agent-step',
+  description: 'This step is used to do research and text synthesis.',
+  inputSchema: z.object({
+    city: z.string().describe('The city to research'),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const resp = await agent1.generate(inputData.city, {
+      output: z.object({
+        text: z.string(),
+      }),
+    });
+
+    return { text: resp.object.text };
+  },
+});
+
+const agentStep2 = createStep({
+  id: 'agent-step-two',
+  description: 'This step is used to do research and text synthesis.',
+  inputSchema: z.object({
+    text: z.string().describe('The city to research'),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const resp = await agent2.generate(inputData.text, {
+      output: z.object({
+        text: z.string(),
+      }),
+    });
+
+    return { text: resp.object.text };
+  },
+});
+
+const workflow1 = createWorkflow({
+  id: 'workflow1',
+  description:
+    'This workflow is perfect for researching a specific city. It should be used when you have a city in mind to research.',
+  steps: [],
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+})
+  .then(agentStep1)
+  .then(agentStep2)
+  .commit();
+
+const agent1 = new Agent({
+  name: 'agent1',
+  instructions:
+    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
+  description:
+    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
+  model: openai('gpt-4o'),
+});
+
+const agent2 = new Agent({
+  name: 'agent2',
+  description:
+    'This agent is used to do text synthesis on researched material. Write a full report based on the researched material. Writes reports in full paragraphs. Should be used to synthesize text from different sources together as a final report.',
+  instructions:
+    'This agent is used to do text synthesis on researched material. Write a full report based on the researched material. Do not use bullet points. Write full paragraphs. There should not be a single bullet point in the final report.',
+  model: openai('gpt-4o'),
+});
+
+const network = new NewAgentNetwork({
+  id: 'test-network',
+  name: 'Test Network',
+  instructions:
+    'You are a network of writers and researchers. The user will ask you to research a topic. You always need to answer with a full report. Bullet points are NOT a full report. WRITE FULL PARAGRAPHS like this is a blog post or something similar. You should not rely on partial information.',
+  model: openai('gpt-4o'),
+  agents: {
+    agent1,
+    agent2,
+  },
+  workflows: {
+    workflow1,
+  },
+  memory: memory,
+});
+
+const runtimeContext = new RuntimeContext();
+
+console.log(
+  // specifying the task, note that there is a mention here about using an agent for synthesis. This is because the routing agent can actually do some synthesis on results on its own, so this will force it to use agent2 instead
+  await network.loop(
+    'What are the biggest cities in France? Give me 3. How are they like? Find cities, then do thorough research on each city, and give me a final full report synthesizing all that information. Make sure to use an agent for synthesis.',
+    { runtimeContext },
+  ),
+);
+```
+
+For the given task (research 3 biggest cities in France and write a full report), the AgentNetwork will call the following primitives:
+
+1. `agent1` to find the 3 biggest cities in France.
+2. `workflow1` to research each city one by one. The workflow uses `memory` to figure out which cities have already been researched and makes sure it has researched all of them before proceeding.
+3. `agent2` to synthesize the final report.
+
+### How It Works
+
+- The underlying engine is a Mastra workflow that wraps the single call `generate` workflow.
+- The workflow will repeatedly call the network execution workflow with a `dountil` structure, until the routing model determines the task is complete. This check is used as the `dountil` condition.