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

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
 

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

@@ -21,52 +21,10 @@ import { VercelDeployer } from "@mastra/deployer-vercel";
 
 const mastra = new Mastra({
   // ...
-  deployer: new VercelDeployer({
-    teamSlug: "your-team-slug",
-    projectName: "your-project-name",
-    token: "your-vercel-token",
-  })
+  deployer: new VercelDeployer()
 });
 ```
 
-## Parameters
-
-### Constructor Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "teamSlug",
-      type: "string",
-      description: "Your Vercel team slug",
-      isOptional: false,
-    },
-    {
-      name: "projectName",
-      type: "string",
-      description:
-        "Name of your Vercel project (will be created if it doesn't exist).",
-      isOptional: false,
-    },
-    {
-      name: "token",
-      type: "string",
-      description: "Your Vercel authentication token.",
-      isOptional: false,
-    },
-  ]}
-/>
-
-### Environment Variables
-
-The VercelDeployer 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. **Vercel Dashboard**: Variables can also be managed through Vercel's web interface.
-
-The deployer automatically synchronizes environment variables between your local development environment and Vercel's environment variable system, ensuring consistency across all deployment environments (production, preview, and development).
-
 ## Lint Mastra Project
 
 Lint your Mastra project to make sure it's fine to build
@@ -83,54 +41,26 @@ To build your Mastra project for Vercel deployment:
 npx mastra build
 ```
 
-The build process generates the following output structure in the `.mastra/output` directory:
+The build process generates the following output structure in the `.vercel/output` directory:
 
 ```
-.mastra/output/
-├── vercel.json     # Vercel configuration
+.vercel/output/functions/index.func
 └── index.mjs       # Application entry point
 ```
 
-### Vercel Configuration
-
-The VercelDeployer automatically generates a `vercel.json` configuration file in `.mastra/output` with the following settings:
-
-```json
-{
-  "version": 2,
-  "installCommand": "npm install --omit=dev",
-  "builds": [
-    {
-      "src": "index.mjs",
-      "use": "@vercel/node",
-      "config": {
-        "includeFiles": ["**"]
-      }
-    }
-  ],
-  "routes": [
-    {
-      "src": "/(.*)",
-      "dest": "index.mjs"
-    }
-  ]
-}
-```
-
 ## Deployment Options
 
-After building, you can deploy your Mastra application `.mastra/output` to Vercel using any of these methods:
+After building, you can deploy your Mastra application to Vercel using any of these methods:
 
 1. **Vercel CLI**: Deploy directly using Vercel's official CLI tool
 
    - Install the CLI: `npm install -g vercel`
-   - Navigate to the output directory: `cd .mastra/output`
-   - Deploy to preview environment: `vercel`
-   - For production deployment: `vercel --prod`
+   - Deploy to preview environment: `vercel --prebuilt`
+   - For production deployment: `vercel --prod --prebuilt`
 
 2. **Vercel Dashboard**: Connect your Git repository or drag-and-drop the build output through the Vercel dashboard
 
-> You can also run `vercel dev` in your output directory `.mastra/output` to test your Mastra application locally.
+> You can also run `vercel dev` in your project directory to test your Mastra application locally. (Make sure you configured your dev command to `mastra dev`)
 
 ## Platform Documentation