@mastra/mcp-docs-server 0.0.1-alpha.1

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

@@ -0,0 +1,224 @@
+---
+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
+});
+```
+
+## 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).

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

@@ -0,0 +1,170 @@
+# 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.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.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({
+    listenProvider: new OpenAIVoice(),
+    speakProvider: 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.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.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 voice.connect();
+
+// Start a conversation
+await voice.speak("Hello, I'm your AI assistant!");
+
+// Stream audio from a microphone
+const microphoneStream = getMicrophoneStream();
+await voice.send(microphoneStream);
+
+// When done with the conversation
+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
+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 }) => {
+  console.log(`${role} said: ${text}`);
+});
+
+// Listen for errors
+voice.on('error', (error) => {
+  console.error('Voice error:', error);
+});
+```

package/.docs/raw/deployment/deployment.mdx

@@ -0,0 +1,156 @@
+---
+title: "Deployment"
+description: "Build and deploy Mastra applications using platform-specific deployers or standard HTTP servers"
+---
+
+# Deploying Mastra Applications
+
+Mastra applications can be deployed in two ways:
+
+1. **Direct Platform Deployment**: Using platform-specific deployers for Cloudflare Workers, Vercel, or Netlify
+2. **Universal Deployment**: Using `mastra build` to generate a standard Node.js server that can run anywhere
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Node.js** installed (version 18 or higher is recommended)
+- If using a platform-specific deployer:
+  - An account with your chosen platform
+  - Required API keys or credentials
+
+## Direct Platform Deployment
+
+Platform-specific deployers handle configuration and deployment for:
+- **[Cloudflare Workers](/docs/reference/deployer/cloudflare)**
+- **[Vercel](/docs/reference/deployer/vercel)**
+- **[Netlify](/docs/reference/deployer/netlify)**
+
+### Installing Deployers
+
+```bash copy
+# For Cloudflare
+npm install @mastra/deployer-cloudflare
+
+# For Vercel
+npm install @mastra/deployer-vercel
+
+# For Netlify
+npm install @mastra/deployer-netlify
+```
+
+### Configuring Deployers
+
+Configure the deployer in your entry file:
+
+```typescript copy showLineNumbers
+import { Mastra, createLogger } from '@mastra/core';
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare';
+
+export const mastra = new Mastra({
+  agents: { /* your agents here */ },
+  logger: createLogger({ name: 'MyApp', level: 'debug' }),
+  deployer: new CloudflareDeployer({
+    scope: 'your-cloudflare-scope',
+    projectName: 'your-project-name',
+    // See complete configuration options in the reference docs
+  }),
+});
+```
+
+### Deployer Configuration
+
+Each deployer has specific configuration options. Below are basic examples, but refer to the reference documentation for complete details.
+
+#### Cloudflare Deployer
+
+```typescript copy showLineNumbers
+new CloudflareDeployer({
+  scope: 'your-cloudflare-account-id',
+  projectName: 'your-project-name',
+  // For complete configuration options, see the reference documentation
+})
+```
+
+[View Cloudflare Deployer Reference →](/docs/reference/deployer/cloudflare)
+
+#### Vercel Deployer
+
+```typescript copy showLineNumbers
+new VercelDeployer({
+  teamId: 'your-vercel-team-id',
+  projectName: 'your-project-name',
+  token: 'your-vercel-token'
+  // For complete configuration options, see the reference documentation
+})
+```
+
+[View Vercel Deployer Reference →](/docs/reference/deployer/vercel)
+
+#### Netlify Deployer
+
+```typescript copy showLineNumbers
+new NetlifyDeployer({
+  scope: 'your-netlify-team-slug',
+  projectName: 'your-project-name',
+  token: 'your-netlify-token'
+})
+```
+
+[View Netlify Deployer Reference →](/docs/reference/deployer/netlify)
+
+## Universal Deployment
+
+Since Mastra builds to a standard Node.js server, you can deploy to any platform that runs Node.js applications:
+- Cloud VMs (AWS EC2, DigitalOcean Droplets, GCP Compute Engine)
+- Container platforms (Docker, Kubernetes)
+- Platform as a Service (Heroku, Railway)
+- Self-hosted servers
+
+### Building
+
+Build the application:
+
+```bash copy
+# Build from current directory
+mastra build
+
+# Or specify a directory
+mastra build --dir ./my-project
+```
+
+The build process:
+1. Locates entry file (`src/mastra/index.ts` or `src/mastra/index.js`)
+2. Creates `.mastra` output directory
+3. Bundles code using Rollup with tree shaking and source maps
+4. Generates [Hono](https://hono.dev) HTTP server
+
+See [`mastra build`](/docs/reference/cli/build) for all options.
+
+### Running the Server
+
+Start the HTTP server:
+
+```bash copy
+node .mastra/index.js
+```
+
+## Environment Variables
+
+Required variables:
+
+1. Platform deployer variables (if using platform deployers):
+   - Platform credentials
+2. Agent API keys:
+   - `OPENAI_API_KEY`
+   - `ANTHROPIC_API_KEY`
+3. Server configuration (for universal deployment):
+   - `PORT`: HTTP server port (default: 3000)
+   - `HOST`: Server host (default: 0.0.0.0)
+
+## Platform Documentation
+
+Platform deployment references:
+- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
+- [Vercel](https://vercel.com/docs)
+- [Netlify](https://docs.netlify.com/)