@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,317 @@
+---
+title: "Agent Tool Selection | Agent Documentation | Mastra"
+description: Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.
+---
+
+# Agent Tool Selection
+
+Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.
+
+## Creating Tools
+
+In this section, we'll walk through the process of creating a tool that can be used by your agents. Let's create a simple tool that fetches current weather information for a given city.
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const getWeatherInfo = async (city: string) => {
+  // Replace with an actual API call to a weather service
+  const data = await fetch(`https://api.example.com/weather?city=${city}`).then(
+    (r) => r.json(),
+  );
+  return data;
+};
+
+export const weatherInfo = createTool({
+  id: "Get Weather Information",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  description: `Fetches the current weather information for a given city`,
+  execute: async ({ context: { city } }) => {
+    console.log("Using tool to fetch weather information for", city);
+    return await getWeatherInfo(city);
+  },
+});
+```
+
+## Adding Tools to an Agent
+
+Now we'll add the tool to an agent. We'll create an agent that can answer questions about the weather and configure it to use our `weatherInfo` tool.
+
+```typescript filename="src/mastra/agents/weatherAgent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import * as tools from "../tools/weatherInfo";
+
+export const weatherAgent = new Agent<typeof tools>({
+  name: "Weather Agent",
+  instructions:
+    "You are a helpful assistant that provides current weather information. When asked about the weather, use the weather information tool to fetch the data.",
+  model: openai("gpt-4o-mini"),
+  tools: {
+    weatherInfo: tools.weatherInfo,
+  },
+});
+```
+
+## Registering the Agent
+
+We need to initialize Mastra with our agent.
+
+```typescript filename="src/index.ts"
+import { Mastra } from "@mastra/core";
+import { weatherAgent } from "./agents/weatherAgent";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+});
+```
+
+This registers your agent with Mastra, making it available for use.
+
+## Abort Signals
+
+The abort signals from `generate` and `stream` (text generation) are forwarded to the tool execution. You can access them in the second parameter of the execute function and e.g. abort long-running computations or forward them to fetch calls inside tools.
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const agent = new Agent({
+  name: "Weather agent",
+  tools: {
+    weather: createTool({
+      id: "Get Weather Information",
+      description: "Get the weather in a location",
+      inputSchema: z.object({ location: z.string() }),
+      execute: async ({ context: { location } }, { abortSignal }) => {
+        return fetch(
+          `https://api.weatherapi.com/v1/current.json?q=${location}`,
+          { signal: abortSignal }, // forward the abort signal to fetch
+        );
+      },
+    }),
+  },
+});
+
+const result = await agent.generate("What is the weather in San Francisco?", {
+  abortSignal: myAbortSignal, // signal that will be forwarded to tools
+});
+```
+
+## Injecting Request/User-Specific Variables
+
+We support dependency injection for tools and workflows. You can pass a container directly to your `generate` or `stream` function calls, or inject it using [server middleware](/docs/deployment/server#Middleware).
+
+Here's an example where we change the temperature scale between Fahrenheit and Celsius:
+
+```typescript filename="src/agents/weather-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const agent = new Agent({
+  name: "Weather agent",
+  tools: {
+    weather: createTool({
+      id: "Get Weather Information",
+      description: "Get the weather in a location",
+      inputSchema: z.object({ location: z.string() }),
+      execute: async ({ context: { location }, container }) => {
+        const scale = container.get("temperature-scale");
+
+        const result = await fetch(
+          `https://api.weatherapi.com/v1/current.json?q=${location}`,
+        );
+
+        const json = await result.json();
+
+        return {
+          temperature: scale === "celsius" ? json.temp_c : json.temp_f,
+        };
+      },
+    }),
+  },
+});
+```
+
+```typescript
+import { agent } from "./agents/weather";
+
+type MyContainer = {"temperature-scale", "celsius" | "farenheit"}
+
+const container = new Container<MyContainer>();
+container.set("temperature-scale", "celsius");
+
+const result = await agent.generate("What is the weather in San Francisco?", {
+  container,
+});
+```
+
+Let's derive temperature from the user's country using cloudflare ` CF-IPCountry` header. We're keeping the same agent code as the example above
+
+```typescript filename="src/index.ts"
+import { Mastra } from "@mastra/core";
+import { Container } from "@mastra/core/di";
+import { agent as weatherAgent } from "./agents/weather";
+
+type MyContainer = {"temperature-scale", "celsius" | "farenheit"}
+
+export const mastra = new Mastra({
+  agents: {
+    weather: weatherAgent,
+  },
+  server: {
+    middleware: [
+      (c, next) => {
+        const country = c.req.header("CF-IPCountry");
+        const container: MyContainer = c.get("container");
+
+        container.set(
+          "temperature-scale",
+          country === "US" ? "farenheit" : "celsius",
+        );
+      },
+    ],
+  },
+});
+```
+
+## Debugging Tools
+
+You can test tools using Vitest or any other testing framework. Writing unit tests for your tools ensures they behave as expected and helps catch errors early.
+
+## Calling an Agent with a Tool
+
+Now we can call the agent, and it will use the tool to fetch the weather information.
+
+## Example: Interacting with the Agent
+
+```typescript filename="src/index.ts"
+import { mastra } from "./index";
+
+async function main() {
+  const agent = mastra.getAgent("weatherAgent");
+  const response = await agent.generate(
+    "What's the weather like in New York City today?",
+  );
+
+  console.log(response.text);
+}
+
+main();
+```
+
+The agent will use the `weatherInfo` tool to get the current weather in New York City and respond accordingly.
+
+## Vercel AI SDK Tool Format
+
+Mastra supports tools created using the Vercel AI SDK format. You can import and use these tools directly:
+
+```typescript filename="src/mastra/tools/vercelTool.ts" copy
+import { tool } from "ai";
+import { z } from "zod";
+
+export const weatherInfo = tool({
+  description: "Fetches the current weather information for a given city",
+  parameters: z.object({
+    city: z.string().describe("The city to get weather for"),
+  }),
+  execute: async ({ city }) => {
+    // Replace with actual API call
+    const data = await fetch(`https://api.example.com/weather?city=${city}`);
+    return data.json();
+  },
+});
+```
+
+You can use Vercel tools alongside Mastra tools in your agents:
+
+```typescript filename="src/mastra/agents/weatherAgent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { weatherInfo } from "../tools/vercelTool";
+import * as mastraTools from "../tools/mastraTools";
+
+export const weatherAgent = new Agent({
+  name: "Weather Agent",
+  instructions:
+    "You are a helpful assistant that provides weather information.",
+  model: openai("gpt-4"),
+  tools: {
+    weatherInfo, // Vercel tool
+    ...mastraTools, // Mastra tools
+  },
+});
+```
+
+Both tool formats will work seamlessly within your agent's workflow.
+
+## Tool Design Best Practices
+
+When creating tools for your agents, following these guidelines will help ensure reliable and intuitive tool usage:
+
+### Tool Descriptions
+
+Your tool's main description should focus on its purpose and value:
+
+- Keep descriptions simple and focused on **what** the tool does
+- Emphasize the tool's primary use case
+- Avoid implementation details in the main description
+- Focus on helping the agent understand **when** to use the tool
+
+```typescript
+createTool({
+  id: "documentSearch",
+  description:
+    "Access the knowledge base to find information needed to answer user questions",
+  // ... rest of tool configuration
+});
+```
+
+### Parameter Schemas
+
+Technical details belong in the parameter schemas, where they help the agent use the tool correctly:
+
+- Make parameters self-documenting with clear descriptions
+- Include default values and their implications
+- Provide examples where helpful
+- Describe the impact of different parameter choices
+
+```typescript
+inputSchema: z.object({
+  query: z.string().describe("The search query to find relevant information"),
+  limit: z.number().describe(
+    "Number of results to return. Higher values provide more context, lower values focus on best matches"
+  ),
+  options: z.string().describe(
+    "Optional configuration. Example: '{'filter': 'category=news'}'"
+  ),
+}),
+```
+
+### Agent Interaction Patterns
+
+Tools are more likely to be used effectively when:
+
+- Queries or tasks are complex enough to clearly require tool assistance
+- Agent instructions provide clear guidance on tool usage
+- Parameter requirements are well-documented in the schema
+- The tool's purpose aligns with the query's needs
+
+### Common Pitfalls
+
+- Overloading the main description with technical details
+- Mixing implementation details with usage guidance
+- 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/mcp-guide).

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

@@ -0,0 +1,175 @@
+# Adding Voice to Agents
+
+Mastra agents can be enhanced with voice capabilities, allowing them to speak responses and listen to user input. You can configure an agent to use either a single voice provider or combine multiple providers for different operations.
+
+## Using a Single Provider
+
+The simplest way to add voice to an agent is to use a single provider for both speaking and listening:
+
+```typescript
+import { createReadStream } from "fs";
+import path from "path";
+import { Agent } from "@mastra/core/agent";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { openai } from "@ai-sdk/openai";
+
+// Initialize the voice provider with default settings
+const voice = new OpenAIVoice();
+
+// Create an agent with voice capabilities
+export const agent = new Agent({
+  name: "Agent",
+  instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
+  model: openai("gpt-4o"),
+  voice,
+});
+
+// The agent can now use voice for interaction
+await agent.voice.speak("Hello, I'm your AI assistant!");
+
+// Read audio file and transcribe
+const audioFilePath = path.join(process.cwd(), "/audio.m4a");
+const audioStream = createReadStream(audioFilePath);
+
+try {
+  const transcription = await agent.voice.listen(audioStream, {
+    filetype: "m4a",
+  });
+} catch (error) {
+  console.error("Error transcribing audio:", error);
+}
+```
+
+## Using Multiple Providers
+
+For more flexibility, you can use different providers for speaking and listening using the CompositeVoice class:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+import { openai } from "@ai-sdk/openai";
+
+export const agent = new Agent({
+  name: "Agent",
+  instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
+  model: openai("gpt-4o"),
+
+  // Create a composite voice using OpenAI for listening and PlayAI for speaking
+  voice: new CompositeVoice({
+    input: new OpenAIVoice(),
+    output: new PlayAIVoice(),
+  }),
+});
+```
+
+## Working with Audio Streams
+
+The `speak()` and `listen()` methods work with Node.js streams. Here's how to save and load audio files:
+
+### Saving Speech Output
+
+```typescript
+import { createWriteStream } from "fs";
+import path from "path";
+
+// Generate speech and save to file
+const audio = await agent.voice.speak("Hello, World!");
+const filePath = path.join(process.cwd(), "agent.mp3");
+const writer = createWriteStream(filePath);
+
+audio.pipe(writer);
+
+await new Promise<void>((resolve, reject) => {
+  writer.on("finish", () => resolve());
+  writer.on("error", reject);
+});
+```
+
+### Transcribing Audio Input
+
+```typescript
+import { createReadStream } from "fs";
+import path from "path";
+
+// Read audio file and transcribe
+const audioFilePath = path.join(process.cwd(), "/agent.m4a");
+const audioStream = createReadStream(audioFilePath);
+
+try {
+  console.log("Transcribing audio file...");
+  const transcription = await agent.voice.listen(audioStream, {
+    filetype: "m4a",
+  });
+  console.log("Transcription:", transcription);
+} catch (error) {
+  console.error("Error transcribing audio:", error);
+}
+```
+
+## Real-time Voice Interactions
+
+For more dynamic and interactive voice experiences, you can use real-time voice providers that support speech-to-speech capabilities:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import { search, calculate } from "../tools";
+
+// Initialize the realtime voice provider
+const voice = new OpenAIRealtimeVoice({
+  chatModel: {
+    apiKey: process.env.OPENAI_API_KEY,
+    model: "gpt-4o-mini-realtime",
+  },
+  speaker: "alloy",
+});
+
+// Create an agent with speech-to-speech voice capabilities
+export const agent = new Agent({
+  name: "Agent",
+  instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
+  model: openai("gpt-4o"),
+  tools: {
+    // Tools configured on Agent are passed to voice provider
+    search,
+    calculate,
+  },
+  voice,
+});
+
+// Establish a WebSocket connection
+await agent.voice.connect();
+
+// Start a conversation
+agent.voice.speak("Hello, I'm your AI assistant!");
+
+// Stream audio from a microphone
+const microphoneStream = getMicrophoneStream();
+agent.voice.send(microphoneStream);
+
+// When done with the conversation
+agent.voice.close();
+```
+
+### Event System
+
+The realtime voice provider emits several events you can listen for:
+
+```typescript
+// Listen for speech audio data sent from voice provider
+agent.voice.on("speaking", ({ audio }) => {
+  // audio contains ReadableStream or Int16Array audio data
+});
+
+// Listen for transcribed text sent from both voice provider and user
+agent.voice.on("writing", ({ text, role }) => {
+  console.log(`${role} said: ${text}`);
+});
+
+// Listen for errors
+agent.voice.on("error", (error) => {
+  console.error("Voice error:", error);
+});
+```

package/.docs/raw/agents/agent-memory.mdx

@@ -0,0 +1,62 @@
+---
+title: "Using Agent Memory | Agents | Mastra Docs"
+description: Documentation on how agents in Mastra use memory to store conversation history and contextual information.
+---
+
+# Agent Memory
+
+Agents in Mastra can leverage a powerful memory system to store conversation history, recall relevant information, and maintain persistent context across interactions. This allows agents to have more natural, stateful conversations.
+
+## Enabling Memory for an Agent
+
+To enable memory, simply instantiate the `Memory` class and pass it to your agent's configuration. You also need to install the memory package:
+
+```bash npm2yarn copy
+npm install @mastra/memory
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+// Basic memory setup
+const memory = new Memory();
+
+const agent = new Agent({
+  name: "MyMemoryAgent",
+  instructions: "You are a helpful assistant with memory.",
+  model: openai("gpt-4o"),
+  memory: memory, // Attach the memory instance
+});
+```
+
+This basic setup uses default settings, including LibSQL for storage and FastEmbed for embeddings. For detailed setup instructions, see [Memory](/docs/memory/overview).
+
+## Using Memory in Agent Calls
+
+To utilize memory during interactions, you **must** provide `resourceId` and `threadId` when calling the agent's `stream()` or `generate()` methods.
+
+- `resourceId`: Typically identifies the user or entity (e.g., `user_123`).
+- `threadId`: Identifies a specific conversation thread (e.g., `support_chat_456`).
+
+```typescript
+// Example agent call using memory
+await agent.stream("Remember my favorite color is blue.", {
+  resourceId: "user_alice",
+  threadId: "preferences_thread",
+});
+
+// Later in the same thread...
+const response = await agent.stream("What's my favorite color?", {
+  resourceId: "user_alice",
+  threadId: "preferences_thread",
+});
+// Agent will use memory to recall the favorite color.
+```
+
+These IDs ensure that conversation history and context are correctly stored and retrieved for the appropriate user and conversation.
+
+## Next Steps
+
+Keep exploring Mastra's [memory capabilities](/docs/memory/overview) like threads, conversation history, semantic recall, and working memory.