@mastra/mcp-docs-server 0.0.3 → 0.0.4-alpha.0

package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md

@@ -1,5 +1,23 @@
 # @mastra/voice-speechify
 
+## 0.1.8-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [fb68a80]
+- Updated dependencies [b56a681]
+- Updated dependencies [248cb07]
+  - @mastra/core@0.6.4-alpha.0
+
+## 0.1.7
+
+### Patch Changes
+
+- 404640e: AgentNetwork changeset
+- Updated dependencies [404640e]
+- Updated dependencies [3bce733]
+  - @mastra/core@0.6.3
+
 ## 0.1.7-alpha.1
 
 ### Patch Changes
@@ -281,22 +299,4 @@
 
 ### Patch Changes
 
-- bb4f447: Add support for commonjs
-- Updated dependencies [0d185b1]
-- Updated dependencies [ed55f1d]
-- Updated dependencies [06aa827]
-- Updated dependencies [0fd78ac]
-- Updated dependencies [2512a93]
-- Updated dependencies [e62de74]
-- Updated dependencies [0d25b75]
-- Updated dependencies [fd14a3f]
-- Updated dependencies [8d13b14]
-- Updated dependencies [3f369a2]
-- Updated dependencies [3ee4831]
-- Updated dependencies [4d4e1e1]
-- Updated dependencies [bb4f447]
-- Updated dependencies [108793c]
-- Updated dependencies [5f28f44]
-- Updated dependencies [dabecf4]
-
-... 104 more lines hidden. See full changelog in package directory.
+... 122 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/create-mastra.md

@@ -1,5 +1,20 @@
 # create-mastra
 
+## 0.2.2-alpha.0
+
+### Patch Changes
+
+- 933ea4d: Fix messages in thread not showing latest when switching between threads
+- 9cba774: Fix new thread title not reflecting until refresh or new message is sent
+- 248cb07: Allow ai-sdk Message type for messages in agent generate and stream
+  Fix sidebar horizontal overflow in playground
+
+## 0.2.1
+
+### Patch Changes
+
+- 404640e: AgentNetwork changeset
+
 ## 0.2.1-alpha.0
 
 ### Patch Changes
@@ -283,20 +298,5 @@
 
 ## 0.1.0-alpha.39
 
-### Patch Changes
-
-- b97ca96: Tracing into default storage
-- fee6d63: Republish
-
-## 0.1.0-alpha.38
-
-### Patch Changes
-
-- 4f1d1a1: Enforce types ann cleanup package.json
-
-## 0.1.0-alpha.37
-
-### Patch Changes
-
 
-... 253 more lines hidden. See full changelog in package directory.
+... 268 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,33 @@
 # mastra
 
+## 0.4.3-alpha.0
+
+### Patch Changes
+
+- 933ea4d: Fix messages in thread not showing latest when switching between threads
+- 9cba774: Fix new thread title not reflecting until refresh or new message is sent
+- 248cb07: Allow ai-sdk Message type for messages in agent generate and stream
+  Fix sidebar horizontal overflow in playground
+- Updated dependencies [e764fd1]
+- Updated dependencies [fb68a80]
+- Updated dependencies [e764fd1]
+- Updated dependencies [05ef3e0]
+- Updated dependencies [95c5745]
+- Updated dependencies [b56a681]
+- Updated dependencies [248cb07]
+  - @mastra/deployer@0.2.4-alpha.0
+  - @mastra/core@0.6.4-alpha.0
+
+## 0.4.2
+
+### Patch Changes
+
+- 404640e: AgentNetwork changeset
+- Updated dependencies [404640e]
+- Updated dependencies [3bce733]
+  - @mastra/deployer@0.2.3
+  - @mastra/core@0.6.3
+
 ## 0.4.2-alpha.1
 
 ### Patch Changes
@@ -270,33 +298,5 @@
 
 ## 0.3.0-alpha.10
 
-### Minor Changes
-
-- dd7a09a: Added new MCPConfiguration class for managing multiple MCP server tools/toolsets. Fixed a bug where MCPClient env would overwrite PATH env var. Fixed a bug where MCP servers would be killed non-gracefully leading to printing huge errors on every code save when running mastra dev
-
-### Patch Changes
-
-- Updated dependencies [a910463]
-  - @mastra/core@0.5.0-alpha.10
-  - @mastra/deployer@0.1.8-alpha.10
-
-## 0.2.9-alpha.9
-
-### Patch Changes
-
-- Updated dependencies [e9fbac5]
-- Updated dependencies [1e8bcbc]
-- Updated dependencies [aeb5e36]
-- Updated dependencies [f2301de]
-  - @mastra/deployer@0.1.8-alpha.9
-  - @mastra/core@0.5.0-alpha.9
-
-## 0.2.9-alpha.8
-
-### Patch Changes
-
-- Updated dependencies [506f1d5]
-  - @mastra/core@0.5.0-alpha.8
-  - @mastra/deployer@0.1.8-alpha.8
 
-... 2046 more lines hidden. See full changelog in package directory.
+... 2074 more lines hidden. See full changelog in package directory.

package/.docs/organized/code-examples/ai-sdk-useChat.md

@@ -16,7 +16,8 @@
     "@mastra/core": "workspace:*",
     "next": "15.1.7",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "zod": "^3.24.2"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.0",

package/.docs/raw/agents/02-adding-tools.mdx

@@ -222,3 +222,9 @@ Tools are more likely to be used effectively when:
 - Unclear parameter descriptions or missing examples
 
 Following these practices helps ensure your tools are discoverable and usable by agents while maintaining clean separation between purpose (main description) and implementation details (parameter schemas).
+
+## Model Context Protocol (MCP) Tools
+
+Mastra also supports tools from MCP-compatible servers through the `@mastra/mcp` package. MCP provides a standardized way for AI models to discover and interact with external tools and resources. This makes it easy to integrate third-party tools into your agents without writing custom integrations.
+
+For detailed information about using MCP tools, including configuration options and best practices, see our [MCP guide](/docs/agents/02a-mcp-guide).

package/.docs/raw/agents/02a-mcp-guide.mdx

@@ -0,0 +1,192 @@
+---
+title: "Using MCP With Mastra | Agents | Mastra Docs"
+description: "Use MCP in Mastra to integrate third party tools and resources in your AI agents."
+---
+
+# Using MCP With Mastra
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is a standardized way for AI models to discover and interact with external tools and resources.
+
+## Overview
+
+MCP in Mastra provides a standardized way to connect to tool servers and supports both stdio and SSE-based connections.
+
+## Installation
+
+Using pnpm:
+
+```bash
+pnpm add @mastra/mcp@latest
+```
+
+Using npm:
+
+```bash
+npm install @mastra/mcp@latest
+```
+
+## Using MCP in Your Code
+
+The `MCPConfiguration` class provides a way to manage multiple tool servers in your Mastra applications without managing multiple MCP clients. You can configure both stdio-based and SSE-based servers:
+
+```typescript
+import { MCPConfiguration } from "@mastra/mcp";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const mcp = new MCPConfiguration({
+  servers: {
+    // stdio example
+    sequential: {
+      name: "sequential-thinking",
+      server: {
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      },
+    },
+    // SSE example
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+### Tools vs Toolsets
+
+The `MCPConfiguration` class provides two ways to access MCP tools, each suited for different use cases:
+
+#### Using Tools (`getTools()`)
+
+Use this approach when:
+
+- You have a single MCP connection
+- The tools are used by a single user/context
+- Tool configuration (API keys, credentials) remains constant
+- You want to initialize an Agent with a fixed set of tools
+
+```typescript
+const agent = new Agent({
+  name: "CLI Assistant",
+  instructions: "You help users with CLI tasks",
+  model: openai("gpt-4o-mini"),
+  tools: await mcp.getTools(), // Tools are fixed at agent creation
+});
+```
+
+#### Using Toolsets (`getToolsets()`)
+
+Use this approach when:
+
+- You need per-request tool configuration
+- Tools need different credentials per user
+- Running in a multi-user environment (web app, API, etc)
+- Tool configuration needs to change dynamically
+
+```typescript
+const mcp = new MCPConfiguration({
+  servers: {
+    example: {
+      command: "npx",
+      args: ["-y", "@example/fakemcp"],
+      env: {
+        API_KEY: "your-api-key",
+      },
+    },
+  },
+});
+
+// Get the current toolsets configured for this user
+const toolsets = await mcp.getToolsets();
+
+// Use the agent with user-specific tool configurations
+const response = await agent.stream(
+  "What's new in Mastra and how's the weather?",
+  {
+    toolsets,
+  },
+);
+```
+
+## MCP Registries
+
+MCP servers can be accessed through registries that provide curated collections of tools. Here's how to use tools from different registries:
+
+### Composio.dev Registry
+
+[Composio.dev](https://composio.dev) provides a registry of [SSE-based MCP servers](https://mcp.composio.dev) that can be easily integrated with Mastra. The SSE URL that's generated for Cursor is compatible with Mastra - you can use it directly in your configuration:
+
+```typescript
+const mcp = new MCPConfiguration({
+  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]"),
+    },
+  },
+});
+```
+
+When using Composio-provided tools, you can authenticate with services (like Google Sheets or Gmail) directly through conversation with your agent. The tools include authentication capabilities that guide you through the process while chatting.
+
+Note: The Composio.dev integration is best suited for single-user scenarios like personal automation, as the SSE URL is tied to your account and can't be used for multiple users. Each URL represents a single account's authentication context.
+
+### Smithery.ai Registry
+
+[Smithery.ai](https://smithery.ai) provides a registry of MCP servers that you can easily use with Mastra:
+
+```typescript
+// Unix/Mac
+const mcp = new MCPConfiguration({
+  servers: {
+    sequentialThinking: {
+      command: "npx",
+      args: [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@smithery-ai/server-sequential-thinking",
+        "--config",
+        "{}",
+      ],
+    },
+  },
+});
+
+// Windows
+const mcp = new MCPConfiguration({
+  servers: {
+    sequentialThinking: {
+      command: "cmd",
+      args: [
+        "/c",
+        "npx",
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@smithery-ai/server-sequential-thinking",
+        "--config",
+        "{}",
+      ],
+    },
+  },
+});
+```
+
+This example is adapted from the Claude integration example in the Smithery documentation.
+
+## Using the Mastra Documentation Server
+
+Looking to use Mastra's MCP documentation server in your IDE? Check out our [MCP Documentation Server guide](/docs/getting-started/mcp-docs-server) to get started.
+
+## Next Steps
+
+- Learn more about [MCPConfiguration](/docs/reference/tools/mcp-configuration)
+- Check out our [example projects](/examples) that use MCP

package/.docs/raw/agents/03-adding-voice.mdx

@@ -25,7 +25,7 @@ export const agent = new Agent({
 });
 
 // The agent can now use voice for interaction
-await agent.speak("Hello, I'm your AI assistant!");
+await agent.voice.speak("Hello, I'm your AI assistant!");
 
 // Read audio file and transcribe
 const audioFilePath = path.join(process.cwd(), "/audio.m4a");
@@ -135,17 +135,17 @@ export const agent = new Agent({
 });
 
 // Establish a WebSocket connection
-await voice.connect();
+await agent.voice.connect();
 
 // Start a conversation
-await voice.speak("Hello, I'm your AI assistant!");
+agent.voice.speak("Hello, I'm your AI assistant!");
 
 // Stream audio from a microphone
 const microphoneStream = getMicrophoneStream();
-await voice.send(microphoneStream);
+agent.voice.send(microphoneStream);
 
 // When done with the conversation
-voice.close();
+agent.voice.close();
 ```
 
 ### Event System
@@ -154,17 +154,17 @@ The realtime voice provider emits several events you can listen for:
 
 ```typescript
 // Listen for speech audio data sent from voice provider
-voice.on('speaking', ({ audio }) => {
+agent.voice.on('speaking', ({ audio }) => {
   // audio contains ReadableStream or Int16Array audio data
 });
 
 // Listen for transcribed text sent from both voice provider and user
-voice.on('writing', ({ text, role }) => {
+agent.voice.on('writing', ({ text, role }) => {
   console.log(`${role} said: ${text}`);
 });
 
 // Listen for errors
-voice.on('error', (error) => {
+agent.voice.on('error', (error) => {
   console.error('Voice error:', error);
 });
 ```

package/.docs/raw/evals/00-overview.mdx

@@ -81,8 +81,8 @@ Once you're hitting your targets:
 3. Test edge cases - Add examples that cover unusual scenarios
 4. Fine-tune - Look for ways to improve efficiency
 
-See [Textual Evals](/docs/evals/textual-evals) for more info on what evals can do.
+See [Textual Evals](/docs/evals/01-textual-evals) for more info on what evals can do.
 
 For more info on how to create your own evals, see the [Custom Evals](/docs/evals/02-custom-eval) guide.
 
-For running evals in your CI pipeline, see the [Running in CI](/docs/evals/running-in-ci) guide.
+For running evals in your CI pipeline, see the [Running in CI](/docs/evals/03-running-in-ci) guide.

package/.docs/raw/evals/03-running-in-ci.mdx

@@ -13,7 +13,8 @@ We support any testing framework that supports ESM modules. For example, you can
 
 ```typescript copy showLineNumbers filename="src/mastra/agents/index.test.ts"
 import { describe, it, expect } from 'vitest';
-import { evaluate } from '@mastra/core/eval';
+import { evaluate } from "@mastra/evals";
+import { ToneConsistencyMetric } from "@mastra/evals/nlp";
 import { myAgent } from './index';
 
 describe('My Agent', () => {
@@ -32,7 +33,7 @@ You will need to configure a testSetup and globalSetup script for your testing f
 
 ### Vitest Setup
 
-Add these files to your project to run evals in your CI/CD pipeline and capture results in the Mastra dashboard:
+Add these files to your project to run evals in your CI/CD pipeline:
 
 ```typescript copy showLineNumbers filename="globalSetup.ts"
 import { globalSetup } from '@mastra/evals';
@@ -64,9 +65,11 @@ export default defineConfig({
 
 ## Storage Configuration
 
-To store eval results in Mastra Storage:
+To store eval results in Mastra Storage and capture results in the Mastra dashboard:
 
-```typescript
+```typescript copy showLineNumbers filename="testSetup.ts"
+import { beforeAll } from 'vitest';
+import { attachListeners } from '@mastra/evals';
 import { mastra } from './your-mastra-setup';
 
 beforeAll(async () => {

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -1,14 +1,18 @@
 ---
-title: "Mastra Tools for Cursor, Windsurf, and other IDE's | Getting Started | Mastra Docs"
+title: "Using with Cursor/Windsurf | Getting Started | Mastra Docs"
 description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
 ---
 
+import YouTube from "../../../components/youtube";
+
 # Mastra Tools for your agentic IDE
 
 `@mastra/mcp-docs-server` provides direct access to Mastra's complete knowledge base in Cursor, Windsurf, Cline, or any other IDE that supports MCP.
 
 It has access to documentation, code examples, technical blog posts / feature announcements, and package changelogs which your IDE can read to help you build with Mastra.
 
+<YouTube id="vciV57lF0og" />
+
 The MCP server tools have been designed to allow an agent to query the specific information it needs to complete a Mastra related task - for example: adding a Mastra feature to an agent, scaffolding a new project, or helping you understand how something works.
 
 ## How it works
@@ -135,4 +139,3 @@ Track updates for Mastra and `@mastra/*` packages:
 2. **Tool Calls Failing**
    - Restart the MCP server and/or your IDE
    - Update to the latest version of your IDE
-