@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/server-db/mastra-client.mdx

@@ -1,274 +0,0 @@
----
-title: "Mastra Client SDK | Mastra Docs"
-description: "Learn how to set up and use the Mastra Client SDK"
----
-
-import { Tabs } from "nextra/components";
-
-# Mastra Client SDK
-
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/deployment/server) from your client environment.
-
-## Prerequisites
-
-To ensure smooth local development, make sure you have:
-
-- Node.js `v18` or higher
-- TypeScript `v4.7` or higher (if using TypeScript)
-- Your local Mastra server running (typically on port `4111`)
-
-## Usage
-
-The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
-
-## Installation
-
-To use the Mastra Client SDK, install the required dependencies:
-
-{/*
-LLM CONTEXT:
-This Tabs component shows installation commands for the Mastra Client SDK using different package managers.
-Each tab displays the installation command for that specific package manager (npm, yarn, pnpm).
-This helps users install the client SDK with their preferred package manager.
-All commands install the same @mastra/client-js package but use different package manager syntax.
-*/}
-
-<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
-  <Tabs.Tab>
-    ```bash copy
-    npm install @mastra/client-js@latest
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    yarn add @mastra/client-js@latest
-    ```
-  </Tabs.Tab>
-  <Tabs.Tab>
-    ```bash copy
-    pnpm add @mastra/client-js@latest
-    ```
-  </Tabs.Tab>
-    <Tabs.Tab>
-    ```bash copy
-    bun add @mastra/client-js@latest
-    ```
-  </Tabs.Tab>
-</Tabs>
-
-### Initialize the `MastraClient`
-
-Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.
-
-```typescript filename="lib/mastra-client.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111"
-});
-```
-
-## Core APIs
-
-The Mastra Client SDK exposes all resources served by the Mastra Server
-
-- **[Agents](/reference/client-js/agents.mdx)**: Generate responses and stream conversations.
-- **[Memory](/reference/client-js/memory.mdx)**: Manage conversation threads and message history.
-- **[Tools](/reference/client-js/tools.mdx)**: Executed and managed tools.
-- **[Workflows](/reference/client-js/workflows.mdx)**: Trigger workflows and track their execution.
-- **[Vectors](/reference/client-js/vectors.mdx)**: Use vector embeddings for semantic search.
-- **[Logs](/reference/client-js/logs.mdx)**: View logs and debug system behavior.
-- **[Telemetry](/reference/client-js/telemetry.mdx)**: Monitor app performance and trace activity.
-
-## Generating responses
-
-Call `.generate()` with an array of message objects that include `role` and `content`:
-
-```typescript showLineNumbers copy
-import { mastraClient } from "lib/mastra-client";
-
-const testAgent = async () => {
-  try {
-    const agent = mastraClient.getAgent("testAgent");
-
-    const response = await agent.generate({
-      messages: [
-        {
-          role: "user",
-          content: "Hello"
-        }
-      ]
-    });
-
-    console.log(response.text);
-  } catch (error) {
-    return "Error occurred while generating response";
-  }
-};
-```
-
-> See [.generate()](../../reference/client-js/agents.mdx#generate-response) for more information.
-
-## Streaming responses
-
-Use `.stream()` for real-time responses with an array of message objects that include `role` and `content`:
-
-```typescript showLineNumbers copy
-import { mastraClient } from "lib/mastra-client";
-
-const testAgent = async () => {
-  try {
-    const agent = mastraClient.getAgent("testAgent");
-
-    const stream = await agent.stream({
-      messages: [
-        {
-          role: "user",
-          content: "Hello"
-        }
-      ]
-    });
-
-    stream.processDataStream({
-      onTextPart: (text) => {
-        console.log(text);
-      }
-    });
-  } catch (error) {
-    return "Error occurred while generating response";
-  }
-};
-```
-
-> See [.stream()](../../reference/client-js/agents.mdx#stream-response) for more information.
-
-## Configuration options
-
-`MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.
-
-```typescript filename="lib/mastra-client.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  // ...
-  retries: 3,
-  backoffMs: 300,
-  maxBackoffMs: 5000,
-  headers: {
-    "X-Development": "true",
-  },
-});
-```
-
-  > See [MastraClient](../../reference/client-js/mastra-client.mdx) for more configuration options.
-
-## Adding request cancelling
-
-`MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.
-
-Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
-
-```typescript {3,7} filename="lib/mastra-client.ts" showLineNumbers copy
-import { MastraClient } from "@mastra/client-js";
-
-export const controller = new AbortController();
-
-export const mastraClient = new MastraClient({
-  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111",
-  abortSignal: controller.signal
-});
-```
-
-### Using the `AbortController`
-
-Calling `.abort()` will cancel any ongoing requests tied to that signal.
-
-```typescript {4} showLineNumbers copy
-import { mastraClient, controller } from "lib/mastra-client";
-
-const handleAbort = () => {
-  controller.abort();
-};
-```
-
-## Client tools
-
-Define tools directly in client-side applications using the `createTool()` function. Pass them to agents via the `clientTools` parameter in `.generate()` or `.stream()` calls.
-
-This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.
-
-```typescript {27} showLineNumbers copy
-import { createTool } from '@mastra/client-js';
-import { z } from 'zod';
-
-const handleClientTool = async () => {
-  try {
-    const agent = mastraClient.getAgent("colorAgent");
-
-    const colorChangeTool = createTool({
-      id: "color-change-tool",
-      description: "Changes the HTML background color",
-      inputSchema: z.object({
-        color: z.string()
-      }),
-      outputSchema: z.object({
-        success: z.boolean()
-      }),
-      execute: async ({ context }) => {
-        const { color } = context
-
-        document.body.style.backgroundColor = color;
-        return { success: true };
-      }
-    });
-
-    const response = await agent.generate({
-      messages: "Change the background to blue",
-      clientTools: { colorChangeTool }
-    });
-
-    console.log(response);
-  } catch (error) {
-    console.error(error);
-  }
-};
-```
-### Client tool's agent
-
-This is a standard Mastra [agent](../agents/overview#creating-an-agent) configured to return hex color codes, intended to work with the browser-based client tool defined above.
-
-```typescript filename="src/mastra/agents/color-agent" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-
-export const colorAgent = new Agent({
-  name: "test-agent",
-  instructions: `You are a helpful CSS assistant.
-  You can change the background color of web pages.
-  Respond with a hex reference for the color requested by the user`,
-  model: openai("gpt-4o-mini")
-});
-```
-
-## Server-side environments
-
-You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:
-
-```typescript {8} showLineNumbers
-export async function action() {
-  const agent = mastraClient.getAgent("testAgent");
-
-  const stream = await agent.stream({
-    messages: [{ role: "user", content: "Hello" }]
-  });
-
-  return new Response(stream.body);
-}
-```
-
-## Best practices
-
-1. **Error Handling**: Implement proper [error handling](/reference/client-js/error-handling) for development scenarios.
-2. **Environment Variables**: Use environment variables for configuration.
-3. **Debugging**: Enable detailed [logging](/reference/client-js/logs) when needed.
-4. **Performance**: Monitor application performance, [telemetry](/reference/client-js/telemetry) and traces.

package/.docs/raw/server-db/middleware.mdx

@@ -1,173 +0,0 @@
----
-title: "Middleware"
-description: "Apply custom middleware functions to intercept requests."
----
-
-# Middleware
-
-Mastra servers can execute custom middleware functions before or after an API
-route handler is invoked. This is useful for things like authentication,
-logging, injecting request-specific context or adding CORS headers.
-
-A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next`
-function. If it returns a `Response` the request is short-circuited. Calling
-`next()` continues processing the next middleware or route handler.
-
-```typescript copy showLineNumbers
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  server: {
-    middleware: [
-      {
-        handler: async (c, next) => {
-          // Example: Add authentication check
-          const authHeader = c.req.header("Authorization");
-          if (!authHeader) {
-            return new Response("Unauthorized", { status: 401 });
-          }
-
-          await next();
-        },
-        path: "/api/*",
-      },
-      // Add a global request logger
-      async (c, next) => {
-        console.log(`${c.req.method} ${c.req.url}`);
-        await next();
-      },
-    ],
-  },
-});
-```
-
-To attach middleware to a single route pass the `middleware` option to
-`registerApiRoute`:
-
-```typescript copy showLineNumbers
-registerApiRoute("/my-custom-route", {
-  method: "GET",
-  middleware: [
-    async (c, next) => {
-      console.log(`${c.req.method} ${c.req.url}`);
-      await next();
-    },
-  ],
-  handler: async (c) => {
-    const mastra = c.get("mastra");
-    return c.json({ message: "Hello, world!" });
-  },
-});
-```
-
----
-
-## Common examples
-
-### Authentication
-
-```typescript copy
-{
-  handler: async (c, next) => {
-    const authHeader = c.req.header('Authorization');
-    if (!authHeader || !authHeader.startsWith('Bearer ')) {
-      return new Response('Unauthorized', { status: 401 });
-    }
-
-    // Validate token here
-    await next();
-  },
-  path: '/api/*',
-}
-```
-
-### CORS support
-
-```typescript copy
-{
-  handler: async (c, next) => {
-    c.header('Access-Control-Allow-Origin', '*');
-    c.header(
-      'Access-Control-Allow-Methods',
-      'GET, POST, PUT, DELETE, OPTIONS',
-    );
-    c.header(
-      'Access-Control-Allow-Headers',
-      'Content-Type, Authorization',
-    );
-
-    if (c.req.method === 'OPTIONS') {
-      return new Response(null, { status: 204 });
-    }
-
-    await next();
-  },
-}
-```
-
-### Request logging
-
-```typescript copy
-{
-  handler: async (c, next) => {
-    const start = Date.now();
-    await next();
-    const duration = Date.now() - start;
-    console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
-  },
-}
-```
-
-### Special Mastra headers
-
-When integrating with Mastra Cloud or custom clients the following headers can
-be inspected by middleware to tailor behaviour:
-
-```typescript copy
-{
-  handler: async (c, next) => {
-    const isFromMastraCloud = c.req.header('x-mastra-cloud') === 'true';
-    const clientType = c.req.header('x-mastra-client-type');
-    const isDevPlayground =
-      c.req.header('x-mastra-dev-playground') === 'true';
-
-    if (isFromMastraCloud) {
-      // Special handling
-    }
-    await next();
-  },
-}
-```
-- `x-mastra-cloud`: request originates from Mastra Cloud
-- `x-mastra-client-type`: identifies the client SDK, e.g. `js` or `python`
-- `x-mastra-dev-playground`: request triggered from a local playground
-
-### Setting `runtimeContext`
-
-You can populate `runtimeContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
-
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-import { RuntimeContext } from "@mastra/core/runtime-context";
-import { testWeatherAgent } from "./agents/test-weather-agent";
-
-export const mastra = new Mastra({
-  agents: { testWeatherAgent },
-  server: {
-    middleware: [
-      async (context, next) => {
-        const country = context.req.header("CF-IPCountry");
-        const runtimeContext = context.get("runtimeContext");
-
-        runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
-
-        await next();
-      }
-    ]
-  }
-});
-```
-
-# Related
-
-- [Runtime Context](./runtime-context.mdx)

package/.docs/raw/server-db/production-server.mdx

@@ -1,91 +0,0 @@
----
-title: "Create A Mastra Production Server"
-description: "Learn how to configure and deploy a production-ready Mastra server with custom settings for APIs, CORS, and more"
----
-
-# Create a Mastra Production Server
-
-When deploying your Mastra application to production, it runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. This page covers how to configure and customize the server for a production environment.
-
-## Server architecture
-
-Mastra uses [Hono](https://hono.dev) as its underlying HTTP server framework. When you build a Mastra application using `mastra build`, it generates a Hono-based HTTP server in the `.mastra` directory.
-
-The server provides:
-
-- API endpoints for all registered agents
-- API endpoints for all registered workflows
-- Custom API route support
-- Custom middleware support
-- Configuration of timeout
-- Configuration of port
-- Configuration of body limit
-
-See the [Middleware](/docs/server-db/middleware) and
-[Custom API Routes](/docs/server-db/custom-api-routes) pages for details on
-adding additional server behaviour.
-
-## Server configuration
-
-You can configure server `port` and `timeout` in the Mastra instance.
-
-```typescript filename="src/mastra/index.ts" copy showLineNumbers
-import { Mastra } from "@mastra/core/mastra";
-
-export const mastra = new Mastra({
-  // ...
-  server: {
-    port: 3000, // Defaults to 4111
-    timeout: 10000, // Defaults to 30000 (30s)
-  },
-});
-```
-
-The `method` option can be one of `"GET"`, `"POST"`, `"PUT"`,
-`"DELETE"` or `"ALL"`. Using `"ALL"` will cause the handler to be
-invoked for any HTTP method that matches the path.
-
-## TypeScript configuration
-
-Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
-
-```json {4-5} filename="tsconfig.json" copy
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "outDir": "dist"
-  },
-  "include": [
-    "src/**/*"
-  ]
-}
-```
-
-> This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
-
-## CORS configuration
-
-Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
-
-```typescript filename="src/mastra/index.ts" copy showLineNumbers
-import { Mastra } from "@mastra/core/mastra";
-
-export const mastra = new Mastra({
-  // ...
-  server: {
-    cors: {
-      origin: ["https://example.com"], // Allow specific origins or '*' for all
-      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-      allowHeaders: ["Content-Type", "Authorization"],
-      credentials: false,
-    },
-  },
-});
-```