@mastra/mcp-docs-server 0.13.30-alpha.0 → 0.13.30-alpha.2

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/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)