@mastra/mcp-docs-server 0.13.39 → 0.13.40

package/.docs/raw/tools-mcp/advanced-usage.mdx

@@ -1,128 +0,0 @@
----
-title: "Advanced Tool Usage | Tools & MCP | Mastra Docs"
-description: This page covers advanced features for Mastra tools, including abort signals and compatibility with the Vercel AI SDK tool format.
----
-
-# Advanced Tool Usage
-
-This page covers more advanced techniques and features related to using tools in Mastra.
-
-## Abort Signals
-
-When you initiate an agent interaction using `generate()` or `stream()`, you can provide an `AbortSignal`. Mastra automatically forwards this signal to any tool executions that occur during that interaction.
-
-This allows you to cancel long-running operations within your tools, such as network requests or intensive computations, if the parent agent call is aborted.
-
-You access the `abortSignal` in the second parameter of the tool's `execute` function.
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const longRunningTool = createTool({
-  id: "long-computation",
-  description: "Performs a potentially long computation",
-  inputSchema: z.object({ /* ... */ }),
-  execute: async ({ context }, { abortSignal }) => {
-    // Example: Forwarding signal to fetch
-    const response = await fetch("https://api.example.com/data", {
-      signal: abortSignal, // Pass the signal here
-    });
-
-    if (abortSignal?.aborted) {
-      console.log("Tool execution aborted.");
-      throw new Error("Aborted");
-    }
-
-    // Example: Checking signal during a loop
-    for (let i = 0; i < 1000000; i++) {
-      if (abortSignal?.aborted) {
-        console.log("Tool execution aborted during loop.");
-        throw new Error("Aborted");
-      }
-      // ... perform computation step ...
-    }
-
-    const data = await response.json();
-    return { result: data };
-  },\n});
-```
-
-To use this, provide an `AbortController`'s signal when calling the agent:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-// Assume 'agent' is an Agent instance with longRunningTool configured
-
-const controller = new AbortController();
-
-// Start the agent call
-const promise = agent.generate("Perform the long computation.", {
-  abortSignal: controller.signal,
-});
-
-// Sometime later, if needed:
-// controller.abort();
-
-try {
-  const result = await promise;
-  console.log(result.text);
-} catch (error) {
-  if (error.name === "AbortError") {
-    console.log("Agent generation was aborted.");
-  } else {
-    console.error("An error occurred:", error);
-  }
-}
-```
-
-## AI SDK Tool Format
-
-Mastra maintains compatibility with the tool format used by the Vercel AI SDK (`ai` package). You can define tools using the `tool` function from the `ai` package and use them directly within your Mastra agents alongside tools created with Mastra's `createTool`.
-
-First, ensure you have the `ai` package installed:
-
-```bash npm2yarn copy
-npm install ai
-```
-
-Here's an example of a tool defined using the Vercel AI SDK format:
-
-```typescript title="src/mastra/tools/vercelWeatherTool.ts" copy
-import { tool } from "ai";
-import { z } from "zod";
-
-export const vercelWeatherTool = tool({
-  description: "Fetches current weather using Vercel AI SDK format",
-  parameters: z.object({
-    city: z.string().describe("The city to get weather for"),
-  }),
-  execute: async ({ city }) => {
-    console.log(`Fetching weather for ${city} (Vercel format tool)`);
-    // Replace with actual API call
-    const data = await fetch(`https://api.example.com/weather?city=${city}`);
-    return data.json();
-  },
-});
-```
-
-You can then add this tool to your Mastra agent just like any other tool:
-
-```typescript title="src/mastra/agents/mixedToolsAgent.ts"
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK tool
-import { mastraTool } from "../tools/mastraTool"; // Mastra createTool tool
-
-export const mixedToolsAgent = new Agent({
-  name: "Mixed Tools Agent",
-  instructions: "You can use tools defined in different formats.",
-  model: openai("gpt-4o-mini"),
-  tools: {
-    weatherVercel: vercelWeatherTool,
-    someMastraTool: mastraTool,
-  },
-});
-```
-
-Mastra supports both tool formats, allowing you to mix and match as needed.

package/.docs/raw/tools-mcp/overview.mdx

@@ -1,88 +0,0 @@
----
-title: "Using Tools | Tools & MCP | Mastra Docs"
-description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
----
-
-# Using Tools
-
-Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
-
-Each tool typically defines:
-
-- **Inputs:** What information the tool needs to run (defined with an `inputSchema`, often using Zod).
-- **Outputs:** The structure of the data the tool returns (defined with an `outputSchema`).
-- **Execution Logic:** The code that performs the tool's action.
-- **Description:** Text that helps the agent understand what the tool does and when to use it.
-
-## Creating Tools
-
-In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
-
-```typescript title="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
-  console.log(`Fetching weather for ${city}...`);
-  // Example data structure
-  return { temperature: 20, conditions: "Sunny" };
-};
-
-export const weatherTool = createTool({
-  id: "Get Weather Information",
-  description: `Fetches the current weather information for a given city`,
-  inputSchema: z.object({
-    city: z.string().describe("City name"),
-  }),
-  outputSchema: z.object({
-    temperature: z.number(),
-    conditions: z.string(),
-  }),
-  execute: async ({ context: { city } }) => {
-    console.log("Using tool to fetch weather information for", city);
-    return await getWeatherInfo(city);
-  },
-});
-```
-
-This example defines a `weatherTool` with an input schema for the city, an output schema for the weather data, and an `execute` function that contains the tool's logic.
-
-When creating tools, keep tool descriptions simple and focused on **what** the tool does and **when** to use it, emphasizing its primary use case. Technical details belong in the parameter schemas, guiding the agent on _how_ to use the tool correctly with descriptive names, clear descriptions, and explanations of default values.
-
-## Adding Tools to an Agent
-
-To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools with Agents](/docs/agents/using-tools#adding-tools-to-an-agent).
-
-## Using `RuntimeContext`
-
-Use [RuntimeContext](/docs/server-db/runtime-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
-
-```typescript title="src/mastra/tools/test-tool.ts" showLineNumbers
-export type UserTier = {
-  "user-tier": "enterprise" | "pro";
-};
-
-const advancedTools = () => {
-  // ...
-};
-
-const baseTools = () => {
-  // ...
-};
-
-export const testTool = createTool({
-  // ...
-  execute: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
-
-    return userTier === "enterprise" ? advancedTools : baseTools;
-  },
-});
-```
-
-> See [Runtime Context](/docs/server-db/runtime-context) for more information.
-
-## Testing with Studio
-
-Use [Studio](/docs/getting-started/studio) to test tools with different inputs, inspect execution results, and verify tool behavior.