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

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.

package/.docs/raw/networks-vnext/overview.mdx

@@ -0,0 +1,85 @@
+---
+title: "Handling Complex LLM Operations | Networks | Mastra"
+description: "Networks in Mastra help you execute individual or multiple Mastra primitives in a non-deterministic way using a single API."
+---
+
+# Mastra vNext Agent Network
+
+The vNext Agent Network module introduces a flexible, composable and non-deterministic way to orchestrate multiple specialized agents and workflows, enabling complex, reasoning and task completion.
+
+There are two main problem areas that this system is designed to solve:
+
+- Scenarios where a single agent is insufficient, and tasks require collaboration, routing, or sequential/parallel execution across multiple agents and workflows.
+- Scenarios where the task is not fully defined and is initiated with unstructured input. The AgentNetwork can figure out which primitive to call and turn unstructured input into a structured task.
+
+## Differences from Workflows
+
+- Workflows are linear or branched sequences of steps. This creates a deterministic flow of execution.
+- Agent Networks add a layer of non-deterministic LLM-based orchestration, allowing dynamic, multi-agent collaboration and routing. This creates a non-deterministic flow of execution.
+
+## Differences from current experimental implementation
+
+- The current implementation of AgentNetwork relies on tool calls to call other agents in the network. The vNext implementation is using Mastra workflows under the hood to break down the execution to individual tasks.
+- New methods, `.generate()` for a one-off "playbook"-like execution of a single primitive in the network, more suitable for a chat-based interface where you iterate on a solution. The `.loop()` method is still available for more complex tasks and operates much like the current implementation.
+
+## Important details
+
+- Providing memory to the AgentNetwork is _not_ optional when using the `loop` method, as it is required to store the task history. Memory is the core primitive used for any decisions on which primitives to run, as well as determine task completion.
+- Any available primitives (agents, workflows) are used based on their descriptions. The better the description, the better the routing agent will be able to select the right primitive. For workflows, the input schema is also used to determine which inputs to use when calling the workflow. More descriptive naming yields better results.
+- When primitives with overlapping capabilities are available, the routing agent will use the most specific primitive. For example, if both an agent and a workflow can do research, it will use the input schema of the worklfow to determine
+
+## Registering the network in Mastra
+
+```typescript
+const mastra = new Mastra({
+  vnext_networks: {
+    'test-network': network,
+  },
+});
+
+// using the network
+const network = mastra.vnext_getNetwork('test-network');
+
+if (!network) {
+  throw new Error('Network not found');
+}
+
+console.log(await network.generate('What are the biggest cities in France?', { runtimeContext }));
+```
+
+## Using @mastra/client-js
+
+You can use the `@mastra/client-js` package to run the network from the client side.
+
+```typescript
+import { MastraClient } from '@mastra/client-js';
+
+const client = new MastraClient();
+
+const network = client.getVNextNetwork('test-network');
+
+console.log(await network.generate('What are the biggest cities in France?', { runtimeContext }));
+```
+
+You can also stream the response
+
+```typescript
+const stream = await network.stream('What are the biggest cities in France?', { runtimeContext });
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+And for loops
+
+```typescript
+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 },
+  ),
+);
+```
+

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

@@ -0,0 +1,131 @@
+## Unstructured input to structured task
+
+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).
+
+The AgentNetwork is able to route the task to the most appropriate primitive based on the task and the context.
+To ask the AgentNetwork to act on unstructured (text) input, we can use the `generate` method.
+
+```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 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. It writes articles in full paragraphs.',
+  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. You write articles.',
+  model: openai('gpt-4o'),
+});
+
+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.',
+  steps: [],
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+})
+  .then(agentStep1)
+  .then(agentStep2)
+  .commit();
+
+const network = new NewAgentNetwork({
+  id: 'test-network',
+  name: 'Test Network',
+  instructions:
+    'You can research cities. You can also synthesize research material. You can also write a full report based on the researched material.',
+  model: openai('gpt-4o'),
+  agents: {
+    agent1,
+    agent2,
+  },
+  workflows: {
+    workflow1,
+  },
+  memory: memory,
+});
+
+const runtimeContext = new RuntimeContext();
+
+// This will call agent1, as the workflow is meant to be used with individual cities. The best primitive according to the routing agent is thus agent1 which is a general research primitive.
+console.log(await network.generate('What are the biggest cities in France? How are they like?', { runtimeContext }));
+// This will call workflow1, as it is the most suitable primitive according to the routing agent when researching individual cities.
+console.log(await network.generate('Tell me more about Paris', { runtimeContext }));
+```
+
+The AgentNetwork will call the most appropriate primitive based on the task and the context. In the case of researching specific cities, it can figure out how to turn unstructured input into structured workflow inputs based on the workflow's input schema and description. It also knows, that for any other research topic, `agent1` is likely the most appropriate primitive.
+
+### How It Works
+
+- The underlying engine is a Mastra workflow.
+- As a first step, the network uses a **routing agent** to decide which agent or workflow should handle each step.
+- The routing agent will generate a prompt and or structured input for the selected primitive.
+- The next step in the workflow is a `.branch()` that will select the right primitive, calling either an agent step or a workflow step with the input generated by the routing agent.

package/.docs/raw/reference/client-js/agents.mdx

@@ -98,6 +98,47 @@ while (true) {
 }
 ```
 
+### Client tools
+
+Client-side tools allow you to execute custom functions on the client side when the agent requests them.
+
+#### Basic Usage
+
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+const colorChangeTool = createTool({
+  id: 'changeColor',
+  description: 'Changes the background color',
+  inputSchema: z.object({
+    color: z.string(),
+  }),
+  execute: async ({ context }) => {
+    document.body.style.backgroundColor = context.color;
+    return { success: true };
+  }
+})
+
+
+// Use with generate
+const response = await agent.generate({
+  messages: 'Change the background to blue',
+  clientTools: {colorChangeTool},
+});
+
+// Use with stream
+const response = await agent.stream({
+  messages: 'Change the background to green',
+  clientTools: {colorChangeTool},
+});
+
+response.processDataStream({
+  onTextPart: (text) => console.log(text),
+  onToolCallPart: (toolCall) => console.log('Tool called:', toolCall.toolName),
+});
+```
+
 ### Get Agent Tool
 
 Retrieve information about a specific tool available to the agent:

package/.docs/raw/reference/deployer/netlify.mdx

@@ -21,50 +21,10 @@ import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
 const mastra = new Mastra({
   // ...
-  deployer: new NetlifyDeployer({
-    scope: "your-team-slug",
-    projectName: "your-project-name",
-    token: "your-netlify-token",
-  })
+  deployer: new NetlifyDeployer()
 });
 ```
 
-## Parameters
-
-### Constructor Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "scope",
-      type: "string",
-      description: "Your Netlify team slug or ID.",
-      isOptional: false,
-    },
-    {
-      name: "projectName",
-      type: "string",
-      description:
-        "Name of your Netlify site (will be created if it doesn't exist).",
-      isOptional: false,
-    },
-    {
-      name: "token",
-      type: "string",
-      description: "Your Netlify authentication token.",
-      isOptional: false,
-    },
-  ]}
-/>
-
-### Environment Variables
-
-The NetlifyDeployer handles environment variables from multiple sources:
-
-1. **Environment Files**: Variables from `.env.production` and `.env` files.
-2. **Configuration**: Variables passed through the Mastra configuration.
-3. **Netlify Dashboard**: Variables can also be managed through Netlify's web interface.
-
 ## Lint Mastra Project
 
 Lint your Mastra project to make sure it's fine to build
@@ -84,28 +44,29 @@ npx mastra build
 The build process generates the following output structure in the `.mastra/output` directory:
 
 ```
-.mastra/output/
-├── netlify/
-│   └── functions/
-│       └── api/
-│           └── index.mjs    # Application entry point
-└── netlify.toml             # Netlify configuration
+.netlify/
+├── v1/
+    └── functions/
+    │   └── api/
+    │       └── index.mjs    # Application entry point
+    │ config.json            # Netlify configuration
 ```
 
 ### Netlify Configuration
 
-The NetlifyDeployer automatically generates a `netlify.toml` configuration file in `.mastra/output` with the following settings:
-
-```toml
-[functions]
-node_bundler = "esbuild"
-directory = "netlify/functions"
+The NetlifyDeployer automatically generates a `config.json` configuration file in `.netlify/v1` with the following settings:
 
-[[redirects]]
-force = true
-from = "/*"
-status = 200
-to = "/.netlify/functions/api/:splat"
+```json
+{
+  "redirects": [
+    {
+      "force": true,
+      "from": "/*",
+      "to": "/.netlify/functions/api/:splat",
+      "status": 200
+    }
+  ]
+}
 ```
 
 ## Deployment Options
@@ -115,9 +76,8 @@ After building, you can deploy your Mastra application `.mastra/output` to Netli
 1. **Netlify CLI**: Deploy directly using Netlify's official CLI tool
 
    - Install the CLI: `npm install -g netlify-cli`
-   - Navigate to the output directory: `cd .mastra/output`
-   - Deploy with functions directory specified: `netlify deploy --dir . --functions ./netlify/functions`
-   - For production deployment add `--prod` flag: `netlify deploy --prod --dir . --functions ./netlify/functions`
+   - Deploy with functions directory specified: `netlify deploy`
+   - For production deployment add `--prod` flag: `netlify deploy --prod`
 
 2. **Netlify Dashboard**: Connect your Git repository or drag-and-drop the build output through the Netlify dashboard
 
@@ -126,19 +86,13 @@ After building, you can deploy your Mastra application `.mastra/output` to Netli
    ```bash
    # Build command
    npm run build
-
-   # Publish directory 
-   .mastra/output
-
-   # Functions directory
-   .mastra/output/netlify/functions
    ```
 
 
 
 3. **Netlify Dev**: Run your Mastra application locally with Netlify's development environment
 
-> You can also run `netlify dev` in your output directory `.mastra/output` to test your Mastra application locally.
+> You can also run `netlify dev` in your project root to test your Mastra application locally.
 
 ## Platform Documentation