npm - @mastra/mcp-docs-server - Versions diffs - 1.0.0-beta.8 → 1.0.0 - Mend

@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (544) hide show

package/.docs/raw/server-db/server-adapters.mdx DELETED Viewed

@@ -1,286 +0,0 @@
----
-title: "Server Adapters | Server & DB"
-description: "Manually configure a Mastra server using Hono or Express adapters."
----
-import PropertiesTable from "@site/src/components/PropertiesTable";
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-# Server Adapters
-Server adapters let you run Mastra with your own HTTP server instead of using `mastra build`. While `mastra build` generates a standalone server for you, adapters give you full control over the server setup, letting you integrate Mastra into any Node.js application.
-Use adapters when you need to:
-- **Integrate Mastra into an existing application** - Add Mastra endpoints to an Express or Hono app you already have running
-- **Control middleware ordering** - Insert your own middleware before or after Mastra's authentication and routing
-- **Deploy to platforms requiring specific server setup** - Some platforms like Cloudflare Workers or custom Docker setups need direct access to the server instance
-- **Use Express instead of Hono** - `mastra build` uses Hono internally, but you may prefer Express for its ecosystem or team familiarity
-:::info
-For simple deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server-db/mastra-server).
-:::
-## Available adapters
-- **[@mastra/hono](/reference/v1/server/hono-adapter)** - Hono framework adapter
-- **[@mastra/express](/reference/v1/server/express-adapter)** - Express framework adapter
-## Basic setup
-Both adapters follow the same pattern. The adapter wraps your framework's app instance and registers Mastra's routes and middleware onto it.
-1. **Create your framework's app instance** - Initialize Hono or Express as you normally would
-2. **Create a `MastraServer`** - Pass your app and Mastra instance to the adapter
-3. **Call `init()`** - This registers context middleware, authentication, and all API routes
-After `init()`, your app has all the Mastra endpoints (`/api/agents`, `/api/workflows`, etc.) and you can add your own routes before or after.
-See the [Hono Adapter](/reference/v1/server/hono-adapter) or [Express Adapter](/reference/v1/server/express-adapter) docs for framework-specific setup and code examples.
-## Constructor options
-Both adapters accept the same options:
-<PropertiesTable
-  content={[
-    {
-      name: "app",
-      type: "Hono | Application",
-      description: "Framework app instance",
-      isOptional: false,
-    },
-    {
-      name: "mastra",
-      type: "Mastra",
-      description: "Mastra instance",
-      isOptional: false,
-    },
-    {
-      name: "prefix",
-      type: "string",
-      description: "Route path prefix (e.g., `/api/v2`)",
-      isOptional: true,
-      defaultValue: "''",
-    },
-    {
-      name: "openapiPath",
-      type: "string",
-      description: "Path to serve OpenAPI spec (e.g., `/openapi.json`)",
-      isOptional: true,
-    },
-    {
-      name: "bodyLimitOptions",
-      type: "{ maxSize: number, onError: (err) => unknown }",
-      description: "Request body size limits",
-      isOptional: true,
-    },
-    {
-      name: "streamOptions",
-      type: "{ redact?: boolean }",
-      description: "Stream redaction config. When true, redacts sensitive data from streams.",
-      isOptional: true,
-      defaultValue: "{ redact: true }",
-    },
-    {
-      name: "customRouteAuthConfig",
-      type: "Map<string, boolean>",
-      description: "Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.",
-      isOptional: true,
-    },
-  ]}
-/>
-## Initialization flow
-Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
-1. **`registerContextMiddleware()`** - Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
-2. **`registerAuthMiddleware()`** - Adds authentication and authorization middleware, but only if `server.auth` is configured in your Mastra instance. Skipped entirely if no auth is configured.
-3. **`registerRoutes()`** - Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
-### Manual initialization
-For custom middleware ordering, call each method separately instead of `init()`. This is useful when you need middleware that runs before Mastra's context is set up, or when you need to insert logic between the initialization steps.
-```typescript title="server.ts" copy showLineNumbers
-const server = new MastraServer({ app, mastra });
-// Your middleware first
-app.use(loggingMiddleware);
-server.registerContextMiddleware();
-// Middleware that needs Mastra context
-app.use(customMiddleware);
-server.registerAuthMiddleware();
-await server.registerRoutes();
-// Routes after Mastra
-app.get('/health', ...);
-```
-:::tip
-Use manual initialization when you need middleware that runs before Mastra's context is available, or when you need to insert middleware between the context and auth steps.
-:::
-## Adding custom routes
-You can add your own routes to the app alongside Mastra's routes. Routes added after `init()` have access to the Mastra context (the Mastra instance, request context, authenticated user, etc.) through framework-specific mechanisms.
-The timing matters: routes added before `init()` won't have Mastra context available, while routes added after `init()` will. See the framework-specific docs for syntax and examples:
-- [Hono: Adding custom routes](/reference/v1/server/hono-adapter#adding-custom-routes)
-- [Express: Adding custom routes](/reference/v1/server/express-adapter#adding-custom-routes)
-## Route prefixes
-By default, Mastra routes are registered at `/api/agents`, `/api/workflows`, etc. Use the `prefix` option to change this, which is useful for API versioning or when integrating with an existing app that has its own `/api` routes.
-```typescript copy showLineNumbers
-const server = new MastraServer({
-  app,
-  mastra,
-  prefix: '/api/v2',
-});
-```
-With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, etc. Custom routes you add directly to the app are not affected by this prefix.
-## OpenAPI spec
-Mastra can generate an OpenAPI specification for all registered routes. This is useful for documentation, client generation, or integration with API tools. Enable it by setting the `openapiPath` option:
-```typescript copy showLineNumbers
-const server = new MastraServer({
-  app,
-  mastra,
-  openapiPath: '/openapi.json',
-});
-```
-The spec is generated from the Zod schemas defined on each route and served at the specified path. It includes all Mastra routes as well as any custom routes created with `createRoute()`.
-## Stream data redaction
-When streaming agent responses over HTTP, the HTTP streaming layer redacts sensitive information from stream chunks before sending them to clients. This prevents accidental exposure of:
-- System prompts and agent instructions
-- Tool definitions and their parameters
-- API keys and other credentials in request bodies
-- Internal configuration data
-This redaction happens at the HTTP boundary, so internal callbacks like `onStepFinish` still have access to the full request data for debugging and observability purposes.
-By default, redaction is enabled. Configure this behavior via `streamOptions`:
-```typescript copy showLineNumbers
-const server = new MastraServer({
-  app,
-  mastra,
-  streamOptions: {
-    redact: true, // Default
-  },
-});
-```
-Set `redact: false` only for internal services or debugging scenarios where you need access to the full request data in stream responses.
-## Per-route auth overrides
-When authentication is configured on your Mastra instance, all routes require authentication by default. Sometimes you need exceptions: public health check endpoints, webhook receivers, or admin routes that need stricter controls.
-Use `customRouteAuthConfig` to override authentication behavior for specific routes:
-```typescript copy showLineNumbers
-const server = new MastraServer({
-  app,
-  mastra,
-  customRouteAuthConfig: new Map([
-    ['GET:/api/health', false],       // Public health check
-    ['GET:/api/openapi.json', false], // Public API spec
-    ['POST:/api/webhooks/*', false],  // Public webhook endpoints
-    ['POST:/api/admin/reset', true],  // Require auth even if globally disabled
-    ['ALL:/api/internal/*', true],    // Protect all methods on internal routes
-  ]),
-});
-```
-Keys follow the format `METHOD:PATH` where method is `GET`, `POST`, `PUT`, `DELETE`, or `ALL`. Paths support wildcards (`*`) for matching multiple routes. Setting a value to `false` makes the route public, while `true` requires authentication.
-## Accessing the app
-After creating the adapter, you may need to access the underlying framework app instance—for example, to pass it to a platform's serve function or to add routes programmatically from another module.
-```typescript copy showLineNumbers
-// Via the MastraServer instance
-const app = server.getApp();
-// Via the Mastra instance (available after adapter construction)
-const app = mastra.getServerApp();
-```
-Both methods return the same app instance. Use whichever is more convenient based on what's in scope.
-## Server config vs adapter options
-When using server adapters, configuration comes from two places: the Mastra `server` config (passed to the `Mastra` constructor) and the adapter constructor options. Understanding which options come from where helps avoid confusion when settings don't seem to take effect.
-### Used by adapters
-The adapter reads these settings from `mastra.getServer()`:
-| Option | Description |
-|--------|-------------|
-| `auth` | Authentication config, used by `registerAuthMiddleware()`. |
-| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`. |
-### Adapter constructor only
-These options are passed directly to the adapter constructor and are not read from the Mastra config:
-| Option | Description |
-|--------|-------------|
-| `prefix` | Route path prefix |
-| `openapiPath` | OpenAPI spec endpoint |
-| `bodyLimitOptions` | Body size limit with custom error handler |
-| `streamOptions` | Stream redaction settings |
-| `customRouteAuthConfig` | Per-route auth overrides |
-### Not used by adapters
-These `server` config options are only used by `mastra build` and have no effect when using adapters directly:
-| Option | Used by |
-|--------|---------|
-| `port`, `host` | `mastra dev`, `mastra build` |
-| `cors` | `mastra build` adds CORS middleware |
-| `timeout` | `mastra build` |
-| `apiRoutes` | `registerApiRoute()` for `mastra build` |
-| `middleware` | Middleware config for `mastra build` |
-When using adapters, configure these features directly with your framework. For example, add CORS middleware using Hono's or Express's built-in CORS packages, and set the port when calling your framework's listen function.
-## MCP support
-Server adapters register MCP (Model Context Protocol) routes during `registerRoutes()` when MCP servers are configured in your Mastra instance. MCP allows external tools and services to connect to your Mastra server and interact with your agents.
-The adapter registers routes for both HTTP and SSE (Server-Sent Events) transports, enabling different client connection patterns.
-See [MCP](/docs/v1/mcp/overview) for configuration details and how to set up MCP servers.
-## Related
-- [Hono Adapter](/reference/v1/server/hono-adapter) - Hono-specific setup
-- [Express Adapter](/reference/v1/server/express-adapter) - Express-specific setup
-- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Building adapters for other frameworks
-- [Server Configuration](/docs/v1/server-db/mastra-server) - Using `mastra build` instead
-- [Authentication](/docs/v1/auth) - Configuring auth for your server
-- [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
-- [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes

package/.docs/raw/workflows/inngest-workflow.mdx DELETED Viewed

@@ -1,363 +0,0 @@
----
-title: "Inngest Workflow | Workflows"
-description: "Inngest workflow allows you to run Mastra workflows with Inngest"
----
-# Inngest Workflow
-[Inngest](https://www.inngest.com/docs) is a developer platform for building and running background workflows, without managing infrastructure.
-## How Inngest Works with Mastra
-Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow` and `createStep` map directly onto this paradigm. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
-The `serve` function bridges the two systems by registering Mastra workflows as Inngest functions and setting up the necessary event handlers for execution and monitoring.
-When an event triggers a workflow, Inngest executes it step by step, memoizing each step’s result. This means if a workflow is retried or resumed, completed steps are skipped, ensuring efficient and reliable execution. Control flow primitives in Mastra, such as loops, conditionals, and nested workflows are seamlessly translated into the same Inngest’s function/step model, preserving advanced workflow features like composition, branching, and suspension.
-Real-time monitoring, suspend/resume, and step-level observability are enabled via Inngest’s publish-subscribe system and dashboard. As each step executes, its state and output are tracked using Mastra storage and can be resumed as needed.
-## Setup
-```sh
-npm install @mastra/inngest@beta @mastra/core@beta @mastra/deployer@beta
-```
-## Building an Inngest Workflow
-This guide walks through creating a workflow with Inngest and Mastra, demonstrating a counter application that increments a value until it reaches 10.
-### Inngest Initialization
-Initialize the Inngest integration to obtain Mastra-compatible workflow helpers. The createWorkflow and createStep functions are used to create workflow and step objects that are compatible with Mastra and inngest.
-In development
-```ts showLineNumbers copy title="src/mastra/inngest/index.ts"
-import { Inngest } from "inngest";
-import { realtimeMiddleware } from "@inngest/realtime/middleware";
-export const inngest = new Inngest({
-  id: "mastra",
-  baseUrl: "http://localhost:8288",
-  isDev: true,
-  middleware: [realtimeMiddleware()],
-});
-```
-In production
-```ts showLineNumbers copy title="src/mastra/inngest/index.ts"
-import { Inngest } from "inngest";
-import { realtimeMiddleware } from "@inngest/realtime/middleware";
-export const inngest = new Inngest({
-  id: "mastra",
-  middleware: [realtimeMiddleware()],
-});
-```
-### Creating Steps
-Define the individual steps that will compose your workflow:
-```ts showLineNumbers copy title="src/mastra/workflows/index.ts"
-import { z } from "zod";
-import { inngest } from "../inngest";
-import { init } from "@mastra/inngest";
-// Initialize Inngest with Mastra, pointing to your local Inngest server
-const { createWorkflow, createStep } = init(inngest);
-// Step: Increment the counter value
-const incrementStep = createStep({
-  id: "increment",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-  execute: async ({ inputData }) => {
-    return { value: inputData.value + 1 };
-  },
-});
-```
-### Creating the Workflow
-Compose the steps into a workflow using the `dountil` loop pattern. The createWorkflow function creates a function on inngest server that is invocable.
-```ts showLineNumbers copy title="src/mastra/workflows/index.ts"
-// workflow that is registered as a function on inngest server
-const workflow = createWorkflow({
-  id: "increment-workflow",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-}).then(incrementStep);
-workflow.commit();
-export { workflow as incrementWorkflow };
-```
-### Configuring the Mastra Instance and Executing the Workflow
-Register the workflow with Mastra and configure the Inngest API endpoint:
-```ts showLineNumbers copy title="src/mastra/index.ts"
-import { Mastra } from "@mastra/core";
-import { serve as inngestServe } from "@mastra/inngest";
-import { incrementWorkflow } from "./workflows";
-import { inngest } from "./inngest";
-import { PinoLogger } from "@mastra/loggers";
-// Configure Mastra with the workflow and Inngest API endpoint
-export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
-  server: {
-    // The server configuration is required to allow local docker container can connect to the mastra server
-    host: "0.0.0.0",
-    apiRoutes: [
-      // This API route is used to register the Mastra workflow (inngest function) on the inngest server
-      {
-        path: "/api/inngest",
-        method: "ALL",
-        createHandler: async ({ mastra }) => inngestServe({ mastra, inngest }),
-        // The inngestServe function integrates Mastra workflows with Inngest by:
-        // 1. Creating Inngest functions for each workflow with unique IDs (workflow.${workflowId})
-        // 2. Setting up event handlers that:
-        //    - Generate unique run IDs for each workflow execution
-        //    - Create an InngestExecutionEngine to manage step execution
-        //    - Handle workflow state persistence and real-time updates
-        // 3. Establishing a publish-subscribe system for real-time monitoring
-        //    through the workflow:${workflowId}:${runId} channel
-        //
-        // Optional: You can also pass additional Inngest functions to serve alongside workflows:
-        // createHandler: async ({ mastra }) => inngestServe({
-        //   mastra,
-        //   inngest,
-        //   functions: [customFunction1, customFunction2] // User-defined Inngest functions
-        // }),
-      },
-    ],
-  },
-  logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
-  }),
-});
-```
-### Running the Workflow locally
-> **Prerequisites:**
->
-> - Docker installed and running
-> - Mastra project set up
-> - Dependencies installed (`npm install`)
-1. Run `npx mastra dev` to start the Mastra server on local to serve the server on port 4111.
-2. Start the Inngest Dev Server (via Docker)
-   In a new terminal, run:
-```sh
-docker run --rm -p 8288:8288 \
-  inngest/inngest \
-  inngest dev -u http://host.docker.internal:4111/api/inngest
-```
-> **Note:** The URL after `-u` tells the Inngest dev server where to find your Mastra `/api/inngest` endpoint.
-3. Open the Inngest Dashboard
-- Visit [http://localhost:8288](http://localhost:8288) in your browser.
-- Go to the **Apps** section in the sidebar.
-- You should see your Mastra workflow registered.
-  ![Inngest Dashboard](/img/inngest-apps-dashboard.png)
-4. Invoke the Workflow
-- Go to the **Functions** section in the sidebar.
-- Select your Mastra workflow.
-- Click **Invoke** and use the following input:
-```json
-{
-  "data": {
-    "inputData": {
-      "value": 5
-    }
-  }
-}
-```
-![Inngest Function](/img/inngest-function-dashboard.png)
-5. **Monitor the Workflow Execution**
-- Go to the **Runs** tab in the sidebar.
-- Click on the latest run to see step-by-step execution progress.
-  ![Inngest Function Run](/img/inngest-runs-dashboard.png)
-### Running the Workflow in Production
-> **Prerequisites:**
->
-> - Vercel account and Vercel CLI installed (`npm i -g vercel`)
-> - Inngest account
-> - Vercel token (recommended: set as environment variable)
-1. Add Vercel Deployer to Mastra instance
-```ts showLineNumbers copy title="src/mastra/index.ts"
-import { VercelDeployer } from "@mastra/deployer-vercel";
-export const mastra = new Mastra({
-  // ...other config
-  deployer: new VercelDeployer({
-    teamSlug: "your_team_slug",
-    projectName: "your_project_name",
-    // you can get your vercel token from the vercel dashboard by clicking on the user icon in the top right corner
-    // and then clicking on "Account Settings" and then clicking on "Tokens" on the left sidebar.
-    token: "your_vercel_token",
-  }),
-});
-```
-> **Note:** Set your Vercel token in your environment:
->
-> ```sh
-> export VERCEL_TOKEN=your_vercel_token
-> ```
-2. Build the mastra instance
-```sh
-npx mastra build
-```
-3. Deploy to Vercel
-```sh
-cd .mastra/output
-vercel --prod
-```
-> **Tip:** If you haven't already, log in to Vercel CLI with `vercel login`.
-4. Sync with Inngest Dashboard
-- Go to the [Inngest dashboard](https://app.inngest.com/env/production/apps).
-- Click **Sync new app with Vercel** and follow the instructions.
-- You should see your Mastra workflow registered as an app.
-  ![Inngest Dashboard](/img/inngest-apps-dashboard-prod.png)
-5. Invoke the Workflow
-- In the **Functions** section, select `workflow.increment-workflow`.
-- Click **All actions** (top right) > **Invoke**.
-- Provide the following input:
-```json
-{
-  "data": {
-    "inputData": {
-      "value": 5
-    }
-  }
-}
-```
-![Inngest Function Run](/img/inngest-function-dashboard-prod.png)
-6.  Monitor Execution
-- Go to the **Runs** tab.
-- Click the latest run to see step-by-step execution progress.
-  ![Inngest Function Run](/img/inngest-runs-dashboard-prod.png)
-## Advanced Usage: Adding Custom Inngest Functions
-You can serve additional Inngest functions alongside your Mastra workflows by using the optional `functions` parameter in `inngestServe`.
-### Creating Custom Functions
-First, create your custom Inngest functions:
-```ts showLineNumbers copy title="src/inngest/custom-functions.ts"
-import { inngest } from "./inngest";
-// Define custom Inngest functions
-export const customEmailFunction = inngest.createFunction(
-  { id: "send-welcome-email" },
-  { event: "user/registered" },
-  async ({ event }) => {
-    // Custom email logic here
-    console.log(`Sending welcome email to ${event.data.email}`);
-    return { status: "email_sent" };
-  },
-);
-export const customWebhookFunction = inngest.createFunction(
-  { id: "process-webhook" },
-  { event: "webhook/received" },
-  async ({ event }) => {
-    // Custom webhook processing
-    console.log(`Processing webhook: ${event.data.type}`);
-    return { processed: true };
-  },
-);
-```
-### Serving Custom Functions with Workflows
-Update your Mastra configuration to include the custom functions:
-```ts showLineNumbers copy title="src/mastra/index.ts"
-import { Mastra } from "@mastra/core";
-import { serve as inngestServe } from "@mastra/inngest";
-import { incrementWorkflow } from "./workflows";
-import { inngest } from "./inngest";
-import {
-  customEmailFunction,
-  customWebhookFunction,
-} from "./inngest/custom-functions";
-export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
-  server: {
-    host: "0.0.0.0",
-    apiRoutes: [
-      {
-        path: "/api/inngest",
-        method: "ALL",
-        createHandler: async ({ mastra }) =>
-          inngestServe({
-            mastra,
-            inngest,
-            functions: [customEmailFunction, customWebhookFunction], // Add your custom functions
-          }),
-      },
-    ],
-  },
-});
-```
-### Function Registration
-When you include custom functions:
-1. **Mastra workflows** are automatically converted to Inngest functions with IDs like `workflow.${workflowId}`
-2. **Custom functions** retain their specified IDs (e.g., `send-welcome-email`, `process-webhook`)
-3. **All functions** are served together on the same `/api/inngest` endpoint
-This allows you to combine Mastra's workflow orchestration with your existing Inngest functions seamlessly.