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

package/.docs/raw/reference/agents/createTool.mdx

@@ -0,0 +1,229 @@
+---
+title: "Reference: createTool() | Tools | Agents | Mastra Docs"
+description: Documentation for the createTool function in Mastra, which creates custom tools for agents and workflows.
+---
+
+# `createTool()`
+
+The `createTool()` function creates typed tools that can be executed by agents or workflows. Tools have built-in schema validation, execution context, and integration with the Mastra ecosystem.
+
+## Overview
+
+Tools are a fundamental building block in Mastra that allow agents to interact with external systems, perform computations, and access data. Each tool has:
+
+- A unique identifier
+- A description that helps the AI understand when and how to use the tool
+- Optional input and output schemas for validation
+- An execution function that implements the tool's logic
+
+## Example Usage
+
+```ts filename="src/tools/stock-tools.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// Helper function to fetch stock data
+const getStockPrice = async (symbol: string) => {
+  const response = await fetch(
+    `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`
+  );
+  const data = await response.json();
+  return data.prices["4. close"];
+};
+
+// Create a tool to get stock prices
+export const stockPriceTool = createTool({
+  id: "getStockPrice",
+  description: "Fetches the current stock price for a given ticker symbol",
+  inputSchema: z.object({
+    symbol: z.string().describe("The stock ticker symbol (e.g., AAPL, MSFT)")
+  }),
+  outputSchema: z.object({
+    symbol: z.string(),
+    price: z.number(),
+    currency: z.string(),
+    timestamp: z.string()
+  }),
+  execute: async ({ context }) => {
+    const price = await getStockPrice(context.symbol);
+    
+    return {
+      symbol: context.symbol,
+      price: parseFloat(price),
+      currency: "USD",
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+
+// Create a tool that uses the thread context
+export const threadInfoTool = createTool({
+  id: "getThreadInfo",
+  description: "Returns information about the current conversation thread",
+  inputSchema: z.object({
+    includeResource: z.boolean().optional().default(false)
+  }),
+  execute: async ({ context, threadId, resourceId }) => {
+    return {
+      threadId,
+      resourceId: context.includeResource ? resourceId : undefined,
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+```
+
+## API Reference
+
+### Parameters
+
+`createTool()` accepts a single object with the following properties:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      description: "Unique identifier for the tool. This should be descriptive of the tool's function."
+    },
+    {
+      name: "description",
+      type: "string",
+      required: true,
+      description: "Detailed description of what the tool does, when it should be used, and what inputs it requires. This helps the AI understand how to use the tool effectively."
+    },
+    {
+      name: "execute",
+      type: "(context: ToolExecutionContext, options?: any) => Promise<any>",
+      required: false,
+      description: "Async function that implements the tool's logic. Receives the execution context and optional configuration.",
+      properties: [
+        {
+          type: "ToolExecutionContext",
+          parameters: [
+            {
+              name: "context",
+              type: "object",
+              description: "The validated input data that matches the inputSchema"
+            },
+            {
+              name: "threadId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the conversation thread, if available"
+            },
+            {
+              name: "resourceId",
+              type: "string",
+              isOptional: true,
+              description: "Identifier for the user or resource interacting with the tool"
+            },
+            {
+              name: "mastra",
+              type: "Mastra",
+              isOptional: true,
+              description: "Reference to the Mastra instance, if available"
+            },
+          ]
+        },
+        {
+          type: "ToolOptions",
+          parameters: [
+            {
+              name: "toolCallId",
+              type: "string",
+              description: "The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data."
+            },
+            {
+              name: "messages",
+              type: "CoreMessage[]",
+              description: "Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call."
+            },
+            {
+              name: "abortSignal",
+              type: "AbortSignal",
+              isOptional: true,
+              description: "An optional abort signal that indicates that the overall operation should be aborted."
+            },
+          ]
+        }
+      ]
+    },
+    {
+      name: "inputSchema",
+      type: "ZodSchema",
+      required: false,
+      description: "Zod schema that defines and validates the tool's input parameters. If not provided, the tool will accept any input."
+    },
+    {
+      name: "outputSchema",
+      type: "ZodSchema",
+      required: false,
+      description: "Zod schema that defines and validates the tool's output. Helps ensure the tool returns data in the expected format."
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "Tool",
+      type: "Tool<TSchemaIn, TSchemaOut>",
+      description: "A Tool instance that can be used with agents, workflows, or directly executed.",
+      properties: [
+        {
+          type: "Tool",
+          parameters: [
+            {
+              name: "id",
+              type: "string",
+              description: "The tool's unique identifier"
+            },
+            {
+              name: "description",
+              type: "string",
+              description: "Description of the tool's functionality"
+            },
+            {
+              name: "inputSchema",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating inputs"
+            },
+            {
+              name: "outputSchema",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating outputs"
+            },
+            {
+              name: "execute",
+              type: "Function",
+              description: "The tool's execution function"
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+## Type Safety
+
+The `createTool()` function provides full type safety through TypeScript generics:
+
+- Input types are inferred from the `inputSchema`
+- Output types are inferred from the `outputSchema`
+- The execution context is properly typed based on the input schema
+
+This ensures that your tools are type-safe throughout your application.
+
+## Best Practices
+
+1. **Descriptive IDs**: Use clear, action-oriented IDs like `getWeatherForecast` or `searchDatabase`
+2. **Detailed Descriptions**: Provide comprehensive descriptions that explain when and how to use the tool
+3. **Input Validation**: Use Zod schemas to validate inputs and provide helpful error messages
+4. **Error Handling**: Implement proper error handling in your execute function
+5. **Idempotency**: When possible, make your tools idempotent (same input always produces same output)
+6. **Performance**: Keep tools lightweight and fast to execute

package/.docs/raw/reference/agents/generate.mdx

@@ -0,0 +1,334 @@
+---
+title: "Reference: Agent.generate() | Agents | Mastra Docs"
+description: "Documentation for the `.generate()` method in Mastra agents, which produces text or structured responses."
+---
+
+# Agent.generate()
+
+The `generate()` method is used to interact with an agent to produce text or structured responses. This method accepts `messages` and an optional `options` object as parameters.
+
+## Parameters
+
+### `messages`
+
+The `messages` parameter can be:
+
+- A single string
+- An array of strings
+- An array of message objects with `role` and `content` properties
+
+The message object structure:
+
+```typescript
+interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+```
+
+### `options` (Optional)
+
+An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more. 
+
+<PropertiesTable
+  content={[
+    {
+      name: "abortSignal",
+      type: "AbortSignal",
+      isOptional: true,
+      description: "Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.",
+    },
+    {
+      name: "context",
+      type: "CoreMessage[]",
+      isOptional: true,
+      description: "Additional context messages to provide to the agent.",
+    },
+    {
+      name: "experimental_output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description: "Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.",
+    },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description: "Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.",
+    },
+    {
+      name: "output",
+      type: "Zod schema | JsonSchema7",
+      isOptional: true,
+      description: "Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
+    },
+    {
+      name: "maxSteps",
+      type: "number",
+      isOptional: true,
+      defaultValue: "5",
+      description: "Maximum number of execution steps allowed.",
+    },
+    {
+      name: "maxRetries",
+      type: "number",
+      isOptional: true,
+      defaultValue: "2",
+      description: "Maximum number of retries. Set to 0 to disable retries.",
+    },
+    {
+      name: "memoryOptions",
+      type: "MemoryConfig",
+      isOptional: true,
+      description: "Configuration options for memory management. See MemoryConfig section below for details.",
+    },
+    {
+      name: "onStepFinish",
+      type: "GenerateTextOnStepFinishCallback<any> | never",
+      isOptional: true,
+      description: "Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.",
+    },
+    {
+      name: "telemetry",
+      type: "TelemetrySettings",
+      isOptional: true,
+      description: "Settings for telemetry collection during generation. See TelemetrySettings section below for details.",
+    },
+    {
+      name: "temperature",
+      type: "number",
+      isOptional: true,
+      description: "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
+    },
+    {
+      name: "threadId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.",
+    },
+    {
+      name: "toolChoice",
+      type: "'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }",
+      isOptional: true,
+      defaultValue: "'auto'",
+      description: "Controls how the agent uses tools during generation.",
+    },
+    {
+      name: "toolsets",
+      type: "ToolsetsInput",
+      isOptional: true,
+      description: "Additional toolsets to make available to the agent during generation.",
+    },
+  ]}
+/>
+
+#### MemoryConfig
+
+Configuration options for memory management:
+
+<PropertiesTable
+  content={[
+    {
+      name: "lastMessages",
+      type: "number | false",
+      isOptional: true,
+      description: "Number of most recent messages to include in context. Set to false to disable.",
+    },
+    {
+      name: "semanticRecall",
+      type: "boolean | object",
+      isOptional: true,
+      description: "Configuration for semantic memory recall. Can be boolean or detailed config.",
+      properties: [
+        {
+          type: "number",
+          parameters: [
+            {
+              name: "topK",
+              type: "number",
+              isOptional: true,
+              description: "Number of most semantically similar messages to retrieve.",
+            }
+          ]
+        },
+        {
+          type: "number | object",
+          parameters: [
+            {
+              name: "messageRange",
+              type: "number | { before: number; after: number }",
+              isOptional: true,
+              description: "Range of messages to consider for semantic search. Can be a single number or before/after configuration.",
+            }
+          ]
+        }
+      ]
+    },
+    {
+      name: "workingMemory",
+      type: "object",
+      isOptional: true,
+      description: "Configuration for working memory.",
+      properties: [
+        {
+          type: "boolean",
+          parameters: [
+            {
+              name: "enabled", 
+              type: "boolean", 
+              isOptional: true, 
+              description: "Whether to enable working memory."
+            }
+          ]
+        },
+        {
+          type: "string",
+          parameters: [
+            {
+              name: "template",
+              type: "string",
+              isOptional: true,
+              description: "Template to use for working memory.",
+            }
+          ]
+        },
+        {
+          type: "'text-stream' | 'tool-call'",
+          parameters: [
+            {
+              name: "type",
+              type: "'text-stream' | 'tool-call'",
+              isOptional: true,
+              description: "Type of content to use for working memory.",
+            }
+          ]
+        }
+      ]
+    },
+    {
+      name: "threads",
+      type: "object",
+      isOptional: true,
+      description: "Thread-specific memory configuration.",
+      properties: [
+        {
+          type: "boolean",
+          parameters: [
+            {
+              name: "generateTitle",
+              type: "boolean",
+              isOptional: true,
+              description: "Whether to automatically generate titles for new threads.",
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+#### TelemetrySettings
+
+Settings for telemetry collection during generation:
+
+<PropertiesTable
+  content={[
+    {
+      name: "isEnabled",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Enable or disable telemetry. Disabled by default while experimental.",
+    },
+    {
+      name: "recordInputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Enable or disable input recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "recordOutputs",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "true",
+      description: "Enable or disable output recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
+    },
+    {
+      name: "functionId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for this function. Used to group telemetry data by function.",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, AttributeValue>",
+      isOptional: true,
+      description: "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
+    },
+    {
+      name: "tracer",
+      type: "Tracer",
+      isOptional: true,
+      description: "A custom OpenTelemetry tracer instance to use for the telemetry data. See OpenTelemetry documentation for details.",
+    }
+  ]}
+/>
+
+## Returns
+
+The return value of the `generate()` method depends on the options provided, specifically the `output` option.
+
+### PropertiesTable for Return Values
+
+<PropertiesTable
+  content={[
+    {
+      name: "text",
+      type: "string",
+      isOptional: true,
+      description: "The generated text response. Present when output is 'text' (no schema provided).",
+    },
+    {
+      name: "object",
+      type: "object",
+      isOptional: true,
+      description: "The generated structured response. Present when a schema is provided via `output` or `experimental_output`.",
+    },
+    {
+      name: "toolCalls",
+      type: "Array<ToolCall>",
+      isOptional: true,
+      description: "The tool calls made during the generation process. Present in both text and object modes.",
+    }
+  ]}
+/>
+
+#### ToolCall Structure
+
+<PropertiesTable
+  content={[
+    {
+      name: "toolName",
+      type: "string",
+      required: true,
+      description: "The name of the tool invoked.",
+    },
+    {
+      name: "args",
+      type: "any",
+      required: true,
+      description: "The arguments passed to the tool.",
+    }
+  ]}
+/>
+
+## Related Methods
+
+For real-time streaming responses, see the [`stream()`](./stream.mdx) method documentation.

package/.docs/raw/reference/agents/getAgent.mdx

@@ -0,0 +1,54 @@
+---
+title: "Reference: getAgent() | Agent Config | Agents | Mastra Docs"
+description: API Reference for getAgent.
+---
+
+# `getAgent()`
+
+Retrieve an agent based on the provided configuration
+
+```ts showLineNumbers copy
+async function getAgent({
+  connectionId,
+  agent,
+  apis,
+  logger,
+}: {
+  connectionId: string;
+  agent: Record<string, any>;
+  apis: Record<string, IntegrationApi>;
+  logger: any;
+}): Promise<(props: { prompt: string }) => Promise<any>> {
+  return async (props: { prompt: string }) => {
+    return { message: "Hello, world!" };
+  };
+}
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "connectionId",
+      type: "string",
+      description: "The connection ID to use for the agent's API calls.",
+    },
+    {
+      name: "agent",
+      type: "Record<string, any>",
+      description: "The agent configuration object.",
+    },
+    {
+      name: "apis",
+      type: "Record<string, IntegrationAPI>",
+      description: "A map of API names to their respective API objects.",
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable content={[]} />