@mastra/mcp-docs-server 0.13.29 → 0.13.30-alpha.1

package/.docs/raw/agents/using-tools-and-mcp.mdx

@@ -1,241 +0,0 @@
----
-title: "Tools and MCP | Agents | Mastra Docs"
-description: Learn how to create tools, add them to Mastra agents, and integrate tools from MCP servers.
----
-
-# Tools and MCP
-
-Tools are typed functions that can be executed by agents or workflows to help them carry out specific tasks like sending a message, querying a database, or calling an external API. Each tool defines its expected inputs, contains the logic to perform its operation, and may delegate execution to an MCP client for accessing external systems. They give agents a structured way to move beyond language generation and enable deterministic outcomes through well-defined interfaces.
-
-Mastra supports two patterns for providing tools to agents:
-
-- **Direct assignment**: Static tools available at initialization
-- **Function-based**: Dynamic tools resolved based on runtime context
-
-## Creating a tool
-
-This example shows how to create a simple tool that asynchronously fetches data from a weather API:
-
-```typescript filename="src/mastra/tools/weather-tool.ts" showLineNumbers copy
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const weatherTool = createTool({
-  id: "weather-tool",
-  description: "Fetches the current weather for a given city",
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  execute: async ({ context }) => {
-    const { city } = context;
-    const response = await fetch(`https://weather.service?city=${city}`);
-
-    const { temperature, conditions } = await response.json();
-
-    return { temperature, conditions };
-  },
-});
-```
-
-For details on creating and designing tools, see the [Tools Overview](../tools-mcp/overview.mdx).
-
-## Adding tools to an agent
-
-To make a tool available to an agent, add it to the `tools` property in the agent's configuration.
-
-```typescript {3,12} filename="src/mastra/agents/weather-agent.ts" showLineNumbers copy
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-import { weatherTool } from "../tools/weather-tool";
-
-export const weatherAgent = new Agent({
-  name: "Weather Agent",
-  instructions: `
-    You are a helpful assistant that provides weather information.
-    When asked about the weather, use the weatherTool to fetch the data.`,
-  model: openai("gpt-4o-mini"),
-  tools: {
-    weatherTool,
-  },
-});
-```
-
-When you call the agent, it can now decide to use the configured tool based on its instructions and the user's prompt.
-
-## Adding MCP tools to an agent
-
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) provides a standardized way for AI models to discover and interact with external tools and resources. You can connect your Mastra agent to MCP servers to use tools provided by third parties.
-
-For more details on MCP concepts and how to set up MCP clients and servers, see the [MCP Overview](/docs/tools-mcp/mcp-overview).
-
-### Installation
-
-First, install the Mastra MCP package:
-
-```bash npm2yarn copy
-npm install @mastra/mcp@latest
-```
-
-### Using MCP tools
-
-Because there are so many MCP server registries to choose from, we've created an [MCP Registry Registry](https://mastra.ai/mcp-registry-registry) to help you find MCP servers.
-
-Once you have a server you want to use with your agent, import the Mastra `MCPClient` and add the server configuration.
-
-```typescript filename="src/mastra/mcp.ts" {1,7-16}
-import { MCPClient } from "@mastra/mcp";
-
-// Configure MCPClient to connect to your server(s)
-export const mcp = new MCPClient({
-  servers: {
-    filesystem: {
-      command: "npx",
-      args: [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "/Users/username/Downloads",
-      ],
-    },
-  },
-});
-```
-
-Then connect your agent to the server tools:
-
-```typescript filename="src/mastra/agents/mcpAgent.ts" {7}
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-import { mcp } from "../mcp";
-
-// Create an agent and add tools from the MCP client
-const agent = new Agent({
-  name: "Agent with MCP Tools",
-  instructions: "You can use tools from connected MCP servers.",
-  model: openai("gpt-4o-mini"),
-  tools: await mcp.getTools(),
-});
-```
-
-When creating agents that will consume an MCP server in the same repo they need to connect to, always use function based tools to prevent race conditions.
-
-```typescript filename="src/mastra/agents/selfReferencingAgent.ts"
-import { Agent } from "@mastra/core/agent";
-import { MCPServer } from "@mastra/mcp";
-import { MCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
-
-const myAgent = new Agent({
-  name: "My Agent",
-  description: "An agent that can use tools from an http MCP server",
-  instructions: "You can use remote calculation tools.",
-  model: openai("gpt-4o-mini"),
-  tools: async () => {
-    // Tools resolve when needed, not during initialization
-    const mcpClient = new MCPClient({
-      servers: {
-        myServer: {
-          url: new URL("http://localhost:4111/api/mcp/mcpServer/mcp"),
-        },
-      },
-    });
-    return await mcpClient.getTools();
-  },
-});
-
-// This works because tools resolve after server startup
-export const mcpServer = new MCPServer({
-  name: "My MCP Server",
-  agents: {
-    myAgent
-  },
-});
-```
-
-For more details on configuring `MCPClient` and the difference between static and dynamic MCP server configurations, see the [MCP Overview](/docs/tools-mcp/mcp-overview).
-
-## Accessing MCP resources
-
-In addition to tools, MCP servers can also expose resources - data or content that can be retrieved and used in your application.
-
-```typescript filename="src/mastra/resources.ts" {3-8}
-import { mcp } from "./mcp";
-
-// Get resources from all connected MCP servers
-const resources = await mcp.getResources();
-
-// Access resources from a specific server
-if (resources.filesystem) {
-  const resource = resources.filesystem.find(
-    (r) => r.uri === "filesystem://Downloads",
-  );
-  console.log(`Resource: ${resource?.name}`);
-}
-```
-
-Each resource has a URI, name, description, and MIME type. The `getResources()` method handles errors gracefully - if a server fails or doesn't support resources, it will be omitted from the results.
-
-## Accessing MCP prompts
-
-MCP servers can also expose prompts, which represent structured message templates or conversational context for agents.
-
-### Listing prompts
-
-```typescript filename="src/mastra/prompts.ts"
-import { mcp } from "./mcp";
-
-// Get prompts from all connected MCP servers
-const prompts = await mcp.prompts.list();
-
-// Access prompts from a specific server
-if (prompts.weather) {
-  const prompt = prompts.weather.find(
-    (p) => p.name === "current"
-  );
-  console.log(`Prompt: ${prompt?.name}`);
-}
-```
-
-Each prompt has a name, description, and (optional) version.
-
-### Retrieving a prompt and its messages
-
-```typescript filename="src/mastra/prompts.ts"
-const { prompt, messages } = await mcp.prompts.get({ serverName: "weather", name: "current" });
-console.log(prompt);    // { name: "current", version: "v1", ... }
-console.log(messages);  // [ { role: "assistant", content: { type: "text", text: "..." } }, ... ]
-```
-
-## Exposing agents as tools via `MCPServer`
-
-In addition to using tools from MCP servers, your Mastra Agents themselves can be exposed as tools to any MCP-compatible client using Mastra's `MCPServer`.
-
-When an `Agent` instance is provided to an `MCPServer` configuration:
-
-- It is automatically converted into a callable tool.
-- The tool is named `ask_<agentKey>`, where `<agentKey>` is the identifier you used when adding the agent to the `MCPServer`'s `agents` configuration.
-- The agent's `description` property (which must be a non-empty string) is used to generate the tool's description.
-
-This allows other AI models or MCP clients to interact with your Mastra Agents as if they were standard tools, typically by "asking" them a question.
-
-**Example `MCPServer` Configuration with an Agent:**
-
-```typescript filename="src/mastra/mcp.ts"
-import { Agent } from "@mastra/core/agent";
-import { MCPServer } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
-import { weatherInfo } from "../tools/weatherInfo";
-import { generalHelper } from "../agents/generalHelper";
-
-const server = new MCPServer({
-  name: "My Custom Server with Agent-Tool",
-  version: "1.0.0",
-  tools: {
-    weatherInfo,
-  },
-  agents: { generalHelper }, // Exposes 'ask_generalHelper' tool
-});
-```
-
-For an agent to be successfully converted into a tool by `MCPServer`, its `description` property must be set to a non-empty string in its constructor configuration. If the description is missing or empty, `MCPServer` will throw an error during initialization.
-
-For more details on setting up and configuring `MCPServer`, refer to the [MCPServer reference documentation](/reference/tools/mcp-server).

package/.docs/raw/getting-started/model-providers.mdx

@@ -1,63 +0,0 @@
----
-title: "Model Providers | Getting Started | Mastra Docs"
-description: "Learn how to configure and use different model providers with Mastra."
----
-
-import { Callout } from "nextra/components"
-
-# Model Providers
-
-Mastra's unified model router gives you access to 541+ models from 38 providers with a single API. Switch between models and providers without changing your code. Automatic environment variable detection handles authentication, while TypeScript provides full autocomplete for every model.
-
-## Quick Start
-
-Simply use the `provider/model` string pattern:
-
-```typescript showLineNumbers copy filename="src/mastra/agents/weather-agent.ts"
-import { Agent } from "@mastra/core";
-
-const agent = new Agent({
-  name: "WeatherAgent",
-  instructions: "You are a helpful weather assistant",
-  model: "openai/gpt-4o"
-});
-
-const result = await agent.generate("What is the weather like?");
-```
-
-## Browse Providers
-
-<Callout>
-  **[→ View all 38 providers and 7 gateways](../../models)**
-
-  Explore our complete catalog with logos, model counts, and documentation for each provider.
-</Callout>
-
-## Configuration
-
-Models automatically detect API keys from environment variables.
-
-## AI SDK Compatibility
-
-While Mastra provides built-in support for 541+ models, you can also use [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) model providers for additional flexibility:
-
-```typescript
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core";
-
-const agent = new Agent({
-  name: "AISDKAgent",
-  model: openai("gpt-4-turbo")  // AI SDK model provider
-});
-```
-
-<Callout type="info">
-**Recommendation**: Use Mastra's built-in model router (`"provider/model"` strings) for simplicity. Use AI SDK providers only when you need specific features not available in the built-in providers.
-</Callout>
-
-## Learn More
-
-- [📚 Browse All Model Providers](../../models) - Complete list with examples
-- [🚀 Agent Documentation](../../reference/agents/agent.mdx) - Using models with agents
-- [⚙️ Environment Variables](../getting-started/installation.mdx#add-your-api-key) - Configuration guide
-- [🔧 Tool Configuration](../agents/using-tools-and-mcp.mdx#adding-tools-to-an-agent) - Adding tools to agents

package/.docs/raw/reference/agents/migration-guide.mdx

@@ -1,291 +0,0 @@
-# Migration Guide: VNext to Standard APIs
-
-## Overview
-
-As of `v 0.20.00`, the `streamVNext()` and `generateVNext()` methods in Mastra agents have been renamed to `stream()` and `generate()` respectively. These are now the standard APIs with full AI SDK v5 compatibility. The original `stream()` and `generate()` methods have been renamed to `streamLegacy()` and `generateLegacy()` to maintain backward compatibility with AI SDK v4.
-
-### Continue using AI SDK v4 models
-- Rename all your `stream()` and `generate()` calls to `streamLegacy()` and `generateLegacy()` respectively. No other change is needed.
-
-### Continue using AI SDK v5 models
-- Rename all your `streamVNext()` and `generateVNext()` calls to `stream()` and `generate()` respectively. No other change is needed.
-
-### Upgrade from AI SDK v4 models to v5 models
-
-First bump all your model provider packages by a major version. This will ensure that they are all v5 models now. Follow the guide below to understand the differences.
-
-## Key Differences
-
-### 1. Model version support
-
-- **Legacy APIs (`generateLegacy`, `streamLegacy`)**: Only support AI SDK v4 models (specificationVersion: 'v1')
-- **Current APIs (`generate`, `stream`)**: Only support AI SDK v5 models (specificationVersion: 'v2')
-- This is enforced at runtime with clear error messages
-
-### 2. Return types
-
-#### Legacy methods return AI SDK v4 types
-
-- **`generateLegacy()`**:
-  - `GenerateTextResult` or `GenerateObjectResult`
-
-- **`streamLegacy()`**:
-  - `StreamTextResult` or `StreamObjectResult`
-
-#### New stream methods return Mastra/AI SDK v5 types
-
-- **`generate()`**:
-  - When `format: 'mastra'` (default): Returns `MastraModelOutput.getFullOutput()` result
-  - When `format: 'aisdk'`: Returns `AISDKV5OutputStream.getFullOutput()` result (AI SDK v5 compatible)
-  - Internally calls `stream()` and awaits `getFullOutput()`
-
-- **`stream()`**:
-  - When `format: 'mastra'` (default): Returns `MastraModelOutput<OUTPUT>`
-  - When `format: 'aisdk'`: Returns `AISDKV5OutputStream<OUTPUT>` (AI SDK v5 compatible)
-
-#### Format Control
-
-- **Legacy**: No format control, always returns AI SDK v4 types
-- **New stream**: Can choose format via `format` option ('mastra' or 'aisdk')
-
-```typescript
-// Mastra native format (default)
-const result = await agent.stream(messages, {
-  format: 'mastra'
-});
-
-// AI SDK v5 compatibility
-const result = await agent.stream(messages, {
-  format: 'aisdk'
-});
-```
-
-### 3. New Options in Non-Legacy APIs
-
-The following options are available in `stream()` and `generate()` but NOT in their legacy counterparts:
-
-1. **`format`** - Choose between 'mastra' or 'aisdk' output format
-
-```typescript
-const result = await agent.stream(messages, {
-  format: 'aisdk' // or 'mastra' (default)
-});
-```
-
-2. **`system`** - Custom system message (separate from instructions)
-
-```typescript
-const result = await agent.stream(messages, {
-  system: 'You are a helpful assistant'
-});
-```
-
-3. **`structuredOutput`** - Enhanced structured output with model override and custom options
-
-- If no model is added it will use the agent's default model.
-- Error strategy when the object does not conform to the schema is `warn` (log a warning), `error` (throw an error), or `fallback` (return a default fallback value of your choice).
-
-```typescript
-const result = await agent.generate(messages, {
-  structuredOutput: {
-    schema: z.object({
-      name: z.string(),
-      age: z.number()
-    }),
-    model: openai('gpt-4o-mini'), // Optional model override for structuring
-    errorStrategy: 'fallback',
-    fallbackValue: { name: 'unknown', age: 0 },
-    instructions: 'Extract user information' // Override default structuring instructions
-  }
-});
-```
-
-4. **`stopWhen`** - Flexible stop conditions (step count, token limit, etc.)
-
-```typescript
-const result = await agent.stream(messages, {
-  stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000
-});
-```
-
-5. **`providerOptions`** - Provider-specific options (e.g., OpenAI-specific settings)
-
-```typescript
-const result = await agent.stream(messages, {
-  providerOptions: {
-    openai: {
-      store: true,
-      metadata: { userId: '123' }
-    }
-  }
-});
-```
-
-6. **`onChunk`** - Callback for each streaming chunk
-
-```typescript
-const result = await agent.stream(messages, {
-  onChunk: (chunk) => {
-    console.log('Received chunk:', chunk);
-  }
-});
-```
-
-7. **`onError`** - Error callback
-
-```typescript
-const result = await agent.stream(messages, {
-  onError: (error) => {
-    console.error('Stream error:', error);
-  }
-});
-```
-
-8. **`onAbort`** - Abort callback
-
-```typescript
-const result = await agent.stream(messages, {
-  onAbort: () => {
-    console.log('Stream aborted');
-  }
-});
-```
-
-9. **`activeTools`** - Specify which tools are active for this execution
-
-```typescript
-const result = await agent.stream(messages, {
-  activeTools: ['search', 'calculator'] // Only these tools will be available
-});
-```
-
-10. **`abortSignal`** - AbortSignal for cancellation
-
-```typescript
-const controller = new AbortController();
-const result = await agent.stream(messages, {
-  abortSignal: controller.signal
-});
-
-// Later: controller.abort();
-```
-
-11. **`prepareStep`** - Callback before each step in multi-step execution
-
-```typescript
-const result = await agent.stream(messages, {
-  prepareStep: ({ step, state }) => {
-    console.log('About to execute step:', step);
-    return { /* modified state */ };
-  }
-});
-```
-
-12. **`requireToolApproval`** - Require approval for all tool calls
-
-```typescript
-const result = await agent.stream(messages, {
-  requireToolApproval: true
-});
-```
-
-### 4. Options That Still Exist But Have Been Moved
-
-#### `temperature` and Other Model Settings
-
-Unified in `modelSettings`
-
-```typescript
-const result = await agent.stream(messages, {
-  modelSettings: {
-    temperature: 0.7,
-    maxTokens: 1000,
-    topP: 0.9
-  }
-});
-```
-
-#### `resourceId` and `threadId`
-
-Moved to memory object.
-
-```typescript
-const result = await agent.stream(messages, {
-  memory: {
-    resource: 'user-123',
-    thread: 'thread-456'
-  }
-});
-```
-
-### 5. Options That Are Deprecated or Removed
-
-#### `experimental_output`
-
-Use `structuredOutput` instead to allow for tool calls and an object return.
-
-```typescript
-const result = await agent.generate(messages, {
-  structuredOutput: {
-    schema: z.object({
-      summary: z.string()
-    })
-  }
-});
-```
-
-#### `output`
-
-The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results use maxSteps 1 with `structuredOutput`.
-
-```typescript
-const result = await agent.generate(messages, {
-  structuredOutput: {
-    schema: {
-      z.object({
-        name: z.string()
-      })
-    }
-  },
-  maxSteps: 1
-});
-```
-
-#### `memoryOptions` was removed
-
-Use `memory` instead
-```typescript
-const result = await agent.generate(messages, {
-  memory: {
-    ...
-  }
-});
-```
-
-### 6. Type Changes
-
-#### `context`
-
-- **Legacy**: `CoreMessage[]`
-- **New format**: `ModelMessage[]`
-
-#### `toolChoice` uses the AI SDK v5 `ToolChoice` type
-
-```typescript
-type ToolChoice<TOOLS extends Record<string, unknown>> = 'auto' | 'none' | 'required' | {
-    type: 'tool';
-    toolName: Extract<keyof TOOLS, string>;
-};
-```
-
-
-## Migration Checklist
-
-### If you're already using `streamVNext` and `generateVNext`
-
-Just find/replace the methods to `stream` and `generate` respectively.
-
-### If you're using the old `stream` and `generate`
-
-Decide whether you want to upgrade or not. If you don't, just find/replace to `streamLegacy` and `generateLegacy`.
-

package/.docs/raw/tools-mcp/runtime-context.mdx

@@ -1,63 +0,0 @@
----
-title: "Runtime context | Tools & MCP | Mastra Docs"
-description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to tools.
----
-
-import { Callout } from "nextra/components";
-
-# Tool Runtime Context
-
-Mastra provides `RuntimeContext`, a dependency injection system that lets you configure tools with runtime variables. If you find yourself creating multiple tools that perform similar tasks, runtime context allows you to consolidate them into a single, more flexible tool.
-
-## Overview
-
-The dependency injection system allows you to:
-
-1. Pass runtime configuration variables to tools through a type-safe `runtimeContext`.
-2. Access these variables within tool execution context.
-3. Modify tool behavior without changing the underlying code.
-4. Share configuration across multiple tools within the same agent.
-
-<Callout>
-  **Note:** `RuntimeContext` is primarily used for passing data *into* tool
-  executions. It's distinct from agent memory, which handles conversation
-  history and state persistence across multiple calls.
-</Callout>
-
-
-## Accessing `runtimeContext` in tools
-
-Tools can access the same `runtimeContext` used by their parent agent, allowing them to adjust behavior based on runtime configuration. In this example, the `temperature-unit` is retrieved within the tool’s `execute` function to ensure consistent formatting with the agent’s instructions.
-
-```typescript {14-15} filename="src/mastra/tools/test-weather-tool" showLineNumbers copy
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-type WeatherRuntimeContext = {
-  "temperature-unit": "celsius" | "fahrenheit";
-};
-
-export const testWeatherTool = createTool({
-  id: "getWeather",
-  description: "Get the current weather for a location",
-  inputSchema: z.object({
-    location: z.string().describe("The location to get weather for")
-  }),
-  execute: async ({ context, runtimeContext }) => {
-    const temperatureUnit = runtimeContext.get("temperature-unit") as WeatherRuntimeContext["temperature-unit"];
-
-    const weather = await fetchWeather(context.location, temperatureUnit);
-
-    return { result: weather };
-  }
-});
-
-async function fetchWeather(location: string, temperatureUnit: WeatherRuntimeContext["temperature-unit"]) {
-  // ...
-}
-```
-
-
-## Related
-
-[Agent Runtime Context](../agents/runtime-context.mdx)