@mastra/core 1.2.0 → 1.2.1-alpha.0

package/dist/docs/{evals/01-overview.md → references/docs-evals-overview.md}

@@ -1,12 +1,3 @@
-> Overview of scorers in Mastra, detailing their capabilities for evaluating AI outputs and measuring performance.
-
-> **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-5HDIPOLV.js:17701
-- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-5HDIPOLV.js:8436
-- `createStep`: dist/workflows/index.d.ts → dist/chunk-5HDIPOLV.js:7750
-- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-5HDIPOLV.js:8452
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-EY3WXGUD.js:24
-
 # Scorers overview
 
 While traditional software tests have clear pass/fail conditions, AI outputs are non-deterministic — they can vary with the same input. **Scorers** help bridge this gap by providing quantifiable metrics for measuring agent quality.
@@ -27,10 +18,30 @@ There are different kinds of scorers, each serving a specific purpose. Here are
 
 To access Mastra's scorers feature install the `@mastra/evals` package.
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/evals@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/evals@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/evals@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/evals@latest
+```
+
 ## Live evaluations
 
 **Live evaluations** allow you to automatically score AI outputs in real-time as your agents and workflows operate. Instead of running evaluations manually or in batches, scorers run asynchronously alongside your AI systems, providing continuous quality monitoring.
@@ -39,7 +50,7 @@ npm install @mastra/evals@latest
 
 You can add built-in scorers to your agents to automatically evaluate their outputs. See the [full list of built-in scorers](https://mastra.ai/docs/evals/built-in-scorers) for all available options.
 
-```typescript title="src/mastra/agents/evaluated-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import {
   createAnswerRelevancyScorer,
@@ -64,7 +75,7 @@ export const evaluatedAgent = new Agent({
 
 You can also add scorers to individual workflow steps to evaluate outputs at specific points in your process:
 
-```typescript title="src/mastra/workflows/content-generation.ts"
+```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 import { customStepScorer } from "../scorers/custom-step-scorer";
@@ -103,11 +114,9 @@ export const contentWorkflow = createWorkflow({ ... })
 
 In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows. This is particularly useful for analyzing past performance, debugging issues, or running batch evaluations.
 
-> **Note:**
-
-**Observability Required**
-
-To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](../observability/tracing/overview) for setup instructions.
+> **Info:** **Observability Required**
+>
+> To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
 
 ### Scoring traces with Studio
 

package/dist/docs/{evals/03-running-in-ci.md → references/docs-evals-running-in-ci.md}

@@ -1,5 +1,3 @@
-> Learn how to run scorer experiments in your CI/CD pipeline using the runEvals function.
-
 # Running Scorers in CI
 
 Running scorers in your CI pipeline provides quantifiable metrics for measuring agent quality over time. The `runEvals` function processes multiple test cases through your agent or workflow and returns aggregate scores.
@@ -12,7 +10,7 @@ You can use any testing framework that supports ESM modules, such as [Vitest](ht
 
 Use `runEvals` to evaluate your agent against multiple test cases. The function accepts an array of data items, each containing an `input` and optional `groundTruth` for scorer validation.
 
-```typescript title="src/mastra/agents/weather-agent.test.ts"
+```typescript
 import { describe, it, expect } from 'vitest';
 import { createScorer, runEvals } from "@mastra/core/evals";
 import { weatherAgent } from "./weather-agent";
@@ -69,7 +67,7 @@ The `runEvals` function returns an object with:
 
 Create separate test cases for different evaluation scenarios:
 
-```typescript title="src/mastra/agents/weather-agent.test.ts"
+```typescript
 describe('Weather Agent Tests', () => {
   const locationScorer = createScorer({ /* ... */ });
 

package/dist/docs/{mcp/01-overview.md → references/docs-mcp-overview.md}

@@ -1,9 +1,3 @@
-> Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
-
-> **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-5HDIPOLV.js:17701
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-EY3WXGUD.js:24
-
 # MCP Overview
 
 Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It serves as a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
@@ -19,15 +13,35 @@ Mastra currently supports two MCP classes:
 
 To use MCP, install the required dependency:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/mcp@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/mcp@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mcp@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mcp@latest
+```
+
 ## Configuring `MCPClient`
 
 The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
 
-```typescript title="src/mastra/mcp/test-mcp-client.ts"
+```typescript
 import { MCPClient } from "@mastra/mcp";
 
 export const testMcpClient = new MCPClient({
@@ -46,19 +60,15 @@ export const testMcpClient = new MCPClient({
 });
 ```
 
-> **Note:**
-
-Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
-
-> **Note:** Authentication
+> **Info:** Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
 
-For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client#oauth-authentication) section.
+> **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
 
 ## Using `MCPClient` with an agent
 
 To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
 
-```typescript {2,15} title="src/mastra/agents/test-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { testMcpClient } from "../mcp/test-mcp-client";
 
@@ -77,15 +87,13 @@ export const testAgent = new Agent({
 });
 ```
 
-> **Note:**
-
-Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+> **Info:** Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
 
 ## Configuring `MCPServer`
 
 To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
 
-```typescript title="src/mastra/mcp/test-mcp-server.ts"
+```typescript
 import { MCPServer } from "@mastra/mcp";
 
 import { testAgent } from "../agents/test-agent";
@@ -102,19 +110,15 @@ export const testMcpServer = new MCPServer({
 });
 ```
 
-> **Note:**
+> **Info:** Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
 
-Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
-
-> **Note:** Authentication
-
-To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/tools/mcp-server#oauth-protection) section.
+> **Authentication:** To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/tools/mcp-server) section.
 
 ## Registering an `MCPServer`
 
 To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core/mastra";
 
 import { testMcpServer } from "./mcp/test-mcp-server";
@@ -129,7 +133,7 @@ export const mastra = new Mastra({
 `MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
 
 | Feature           | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`)   |
-| :---------------- | :--------------------------------------------- | :--------------------------------------------------- |
+| ----------------- | ---------------------------------------------- | ---------------------------------------------------- |
 | **Use Case**      | Single-user, static config (e.g., CLI tool)    | Multi-user, dynamic config (e.g., SaaS app)          |
 | **Configuration** | Fixed at agent initialization                  | Per-request, dynamic                                 |
 | **Credentials**   | Shared across all uses                         | Can vary per user/request                            |
@@ -139,11 +143,9 @@ export const mastra = new Mastra({
 
 Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
 
-> **Note:**
+> **Info:** Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
 
-Visit [listTools()](https://mastra.ai/reference/tools/mcp-client#listtools) for more information.
-
-```typescript {6} title="src/mastra/agents/test-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -158,7 +160,7 @@ export const testAgent = new Agent({
 
 Use the `.listToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
 
-```typescript {5-16,21}
+```typescript
 import { MCPClient } from "@mastra/mcp";
 import { mastra } from "./mastra";
 
@@ -190,132 +192,127 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 }
 ```
 
-> **Note:**
-
-Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client#listtoolsets) for more information.
+> **Info:** Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client) for more information.
 
 ## Connecting to an MCP registry
 
 MCP servers can be discovered through registries. Here's how to connect to some popular ones using `MCPClient`:
 
-  **klavis:**
+**Klavis AI**:
 
-    [Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+[Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
 
-    ```typescript
-    import { MCPClient } from "@mastra/mcp";
+```typescript
+import { MCPClient } from "@mastra/mcp";
 
-    const mcp = new MCPClient({
-      servers: {
-        salesforce: {
-          url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
-        },
-        hubspot: {
-          url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
-        },
-      },
-    });
-    ```
+const mcp = new MCPClient({
+  servers: {
+    salesforce: {
+      url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+    },
+    hubspot: {
+      url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+    },
+  },
+});
+```
 
-    Klavis AI offers enterprise-grade authentication and security for production deployments.
+Klavis AI offers enterprise-grade authentication and security for production deployments.
 
-    For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
 
-  
-  **mcp-run:**
+**mcp.run**:
 
-    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+[mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
 
-    ```typescript
-    import { MCPClient } from "@mastra/mcp";
+```typescript
+import { MCPClient } from "@mastra/mcp";
 
-    const mcp = new MCPClient({
-      servers: {
-        marketing: { // Example profile name
-          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
-        },
-      },
-    });
-    ```
+const mcp = new MCPClient({
+  servers: {
+    marketing: { // Example profile name
+      url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+    },
+  },
+});
+```
 
-    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
-    > ```bash title=".env"
-    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
-    > ```
+> **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+>
+> ```bash
+> MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+> ```
 
-  
-  **composio:**
+**Composio.dev**:
 
-    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+[Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
 
-    ```typescript
-    import { MCPClient } from "@mastra/mcp";
+```typescript
+import { MCPClient } from "@mastra/mcp";
 
-    const mcp = new MCPClient({
-      servers: {
-        googleSheets: {
-          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
-        },
-        gmail: {
-          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
-        },
-      },
-    });
-    ```
-
-    Authentication with services like Google Sheets often happens interactively through the agent conversation.
-
-    *Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications.*
-
-  
-  **smithery:**
-
-    [Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
-
-    ```typescript
-    // Unix/Mac
-    import { MCPClient } from "@mastra/mcp";
-
-    const mcp = new MCPClient({
-      servers: {
-        sequentialThinking: {
-          command: "npx",
-          args: [
-            "-y",
-            "@smithery/cli@latest",
-            "run",
-            "@smithery-ai/server-sequential-thinking",
-            "--config",
-            "{}",
-          ],
-        },
-      },
-    });
-    ```
-
-    ```typescript
-    // Windows
-    import { MCPClient } from "@mastra/mcp";
-
-    const mcp = new MCPClient({
-      servers: {
-        sequentialThinking: {
-          command: "npx",
-          args: [
-            "-y",
-            "@smithery/cli@latest",
-            "run",
-            "@smithery-ai/server-sequential-thinking",
-            "--config",
-            "{}",
-          ],
-        },
-      },
-    });
-    ```
+const mcp = new MCPClient({
+  servers: {
+    googleSheets: {
+      url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+    },
+    gmail: {
+      url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+    },
+  },
+});
+```
+
+Authentication with services like Google Sheets often happens interactively through the agent conversation.
 
-  
-  **ampersand:**
+_Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications._
+
+**Smithery.ai**:
+
+[Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+```typescript
+// Unix/Mac
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    sequentialThinking: {
+      command: "npx",
+      args: [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@smithery-ai/server-sequential-thinking",
+        "--config",
+        "{}",
+      ],
+    },
+  },
+});
+```
+
+```typescript
+// Windows
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    sequentialThinking: {
+      command: "npx",
+      args: [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@smithery-ai/server-sequential-thinking",
+        "--config",
+        "{}",
+      ],
+    },
+  },
+});
+```
+
+**Ampersand**:
 
 [Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.
 
@@ -366,8 +363,6 @@ export const mcp = new MCPClient({
 
 As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so you can [directly import Ampersand tools](https://docs.withampersand.com/ai-sdk#use-with-mastra) for your agent to access.
 
-  
-
 ## Related
 
 - [Using Tools](https://mastra.ai/docs/agents/using-tools)

package/dist/docs/references/docs-mcp-publishing-mcp-server.md

@@ -0,0 +1,95 @@
+# Publishing an MCP Server
+
+This example guides you through setting up a basic Mastra MCPServer using the stdio transport, building it, and preparing it for publishing to NPM.
+
+## Install dependencies
+
+Install the necessary packages:
+
+```bash
+pnpm add @mastra/mcp @mastra/core tsup
+```
+
+## Setting up an MCP Server
+
+1. Create a file for your stdio server, for example, `/src/mastra/stdio.ts`.
+
+2. Add the following code to the file. Remember to import your actual Mastra tools and name the server appropriately.
+
+   ```typescript
+   #!/usr/bin/env node
+   import { MCPServer } from "@mastra/mcp";
+   import { weatherTool } from "./tools";
+
+   const server = new MCPServer({
+     name: "my-mcp-server",
+     version: "1.0.0",
+     tools: { weatherTool },
+   });
+
+   server.startStdio().catch((error) => {
+     console.error("Error running MCP server:", error);
+     process.exit(1);
+   });
+   ```
+
+3. Update your `package.json` to include the `bin` entry pointing to your built server file and a script to build the server with both ESM and CJS outputs.
+
+   ```json
+   {
+     "bin": "dist/stdio.mjs",
+     "scripts": {
+       "build:mcp": "tsup src/mastra/stdio.ts --format esm,cjs --no-splitting --dts && echo '#!/usr/bin/env node' | cat - dist/stdio.mjs > temp && mv temp dist/stdio.mjs && chmod +x dist/stdio.mjs"
+     }
+   }
+   ```
+
+   The build command generates both ESM (`.mjs`) and CJS (`.cjs`) outputs for maximum compatibility. The shebang (`#!/usr/bin/env node`) is prepended to the ESM artifact to make it directly executable, and the `bin` entry points to this file.
+
+4. Run the build command:
+
+   ```bash
+   pnpm run build:mcp
+   ```
+
+   This will compile your server code into both ESM and CJS formats and make the ESM output file executable. On Unix-like systems, the `chmod +x` step makes the file directly executable. Windows users may need to use WSL or handle execution through Node.js directly.
+
+## Publishing to NPM
+
+To make your MCP server available for others (or yourself) to use via `npx` or as a dependency, you can publish it to NPM.
+
+1. Ensure you have an NPM account and are logged in (`npm login`).
+
+2. Make sure your package name in `package.json` is unique and available.
+
+3. Run the publish command from your project root after building:
+
+   ```bash
+   npm publish --access public
+   ```
+
+   For more details on publishing packages, refer to the [NPM documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages).
+
+## Using a published MCP Server
+
+Once published, your MCP server can be used by an `MCPClient` by specifying the command to run your package. You can also use any other MCP client like Claude desktop, Cursor, or Windsurf.
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    // Give this MCP server instance a name
+    yourServerName: {
+      command: "npx",
+      args: ["-y", "@your-org-name/your-package-name@latest"], // Replace with your package name
+    },
+  },
+});
+
+// You can then get tools or toolsets from this configuration to use in your agent
+const tools = await mcp.listTools();
+const toolsets = await mcp.listToolsets();
+```
+
+Note: If you published without an organization scope, the `args` might just be `["-y", "your-package-name@latest"]`.

package/dist/docs/{memory/05-memory-processors.md → references/docs-memory-memory-processors.md}

@@ -1,5 +1,3 @@
-> Learn how to use memory processors in Mastra to filter, trim, and transform messages before they
-
 # Memory Processors
 
 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
@@ -200,7 +198,7 @@ Understanding the execution order is important when combining guardrails with me
 
 ### Input Processors
 
-```
+```text
 [Memory Processors] → [Your inputProcessors]
 ```
 
@@ -211,7 +209,7 @@ This means memory loads message history before your processors can validate or f
 
 ### Output Processors
 
-```
+```text
 [Your outputProcessors] → [Memory Processors]
 ```
 
@@ -302,10 +300,10 @@ const agent = new Agent({
 
 ### Summary
 
-| Guardrail Type | When it runs | If it aborts |
-| -------------- | ------------ | ------------ |
-| Input | After memory loads history | LLM not called, nothing saved |
-| Output | Before memory saves | Nothing saved to storage |
+| Guardrail Type | When it runs               | If it aborts                  |
+| -------------- | -------------------------- | ----------------------------- |
+| Input          | After memory loads history | LLM not called, nothing saved |
+| Output         | Before memory saves        | Nothing saved to storage      |
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory