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

package/.docs/raw/reference/server/create-route.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: createRoute() | Server"
 description: "API reference for createRoute() function used to define type-safe routes with validation and OpenAPI generation."
+packages:
+  - "@mastra/server"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -11,13 +13,13 @@ The `createRoute()` function creates type-safe routes with Zod validation. When
 
 ## Import
 
-```typescript copy
-import { createRoute } from '@mastra/server';
+```typescript
+import { createRoute } from '@mastra/server/server-adapter';
 ```
 
 ## Signature
 
-```typescript copy
+```typescript
 function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
   config: RouteConfig<TPath, TQuery, TBody, TResponse, TResponseType>
 ): ServerRoute
@@ -118,7 +120,7 @@ function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
 
 The handler receives validated parameters plus runtime context:
 
-```typescript copy showLineNumbers
+```typescript
 handler: async (params) => {
   // From schemas (typed from Zod)
   params.id;              // From pathParamSchema
@@ -142,8 +144,8 @@ Returns a `ServerRoute` object that can be registered with an adapter.
 
 ### GET route with path params
 
-```typescript copy showLineNumbers
-import { createRoute } from '@mastra/server';
+```typescript
+import { createRoute } from '@mastra/server/server-adapter';
 import { z } from 'zod';
 
 const getAgent = createRoute({
@@ -167,7 +169,7 @@ const getAgent = createRoute({
 
 ### POST route with body
 
-```typescript copy showLineNumbers
+```typescript
 const createItem = createRoute({
   method: 'POST',
   path: '/api/items',
@@ -190,7 +192,7 @@ const createItem = createRoute({
 
 ### Query params with coercion
 
-```typescript copy showLineNumbers
+```typescript
 const listItems = createRoute({
   method: 'GET',
   path: '/api/items',
@@ -209,7 +211,7 @@ const listItems = createRoute({
 
 ### Streaming route
 
-```typescript copy showLineNumbers
+```typescript
 const streamAgent = createRoute({
   method: 'POST',
   path: '/api/agents/:agentId/stream',
@@ -223,14 +225,14 @@ const streamAgent = createRoute({
   }),
   handler: async ({ agentId, messages, mastra, abortSignal }) => {
     const agent = mastra.getAgent(agentId);
-    return agent.stream({ messages, abortSignal });
+    return agent.stream(messages, { abortSignal });
   },
 });
 ```
 
 ### Custom body size limit
 
-```typescript copy showLineNumbers
+```typescript
 const uploadRoute = createRoute({
   method: 'POST',
   path: '/api/upload',
@@ -249,7 +251,7 @@ const uploadRoute = createRoute({
 
 ### Passthrough for extensibility
 
-```typescript copy
+```typescript
 const bodySchema = z.object({
   required: z.string(),
 }).passthrough(); // Allow unknown fields
@@ -257,7 +259,7 @@ const bodySchema = z.object({
 
 ### Date coercion
 
-```typescript copy
+```typescript
 const querySchema = z.object({
   fromDate: z.coerce.date().optional(),
   toDate: z.coerce.date().optional(),
@@ -266,7 +268,7 @@ const querySchema = z.object({
 
 ### Union types
 
-```typescript copy
+```typescript
 const bodySchema = z.object({
   messages: z.union([
     z.array(z.any()),
@@ -277,10 +279,11 @@ const bodySchema = z.object({
 
 ## Error handling
 
-Throw `HTTPException` to return specific HTTP status codes from handlers:
+Throw an error with a `status` property to return specific HTTP status codes from handlers. If using Hono, you can use `HTTPException` from `hono/http-exception`:
 
-```typescript copy showLineNumbers
-import { createRoute, HTTPException } from '@mastra/server';
+```typescript
+import { createRoute } from '@mastra/server/server-adapter';
+import { HTTPException } from 'hono/http-exception';
 
 const getAgent = createRoute({
   method: 'GET',
@@ -297,6 +300,19 @@ const getAgent = createRoute({
 });
 ```
 
+For Express or framework-agnostic code, throw an error with a `status` property:
+
+```typescript
+class HttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}
+
+// In handler:
+throw new HttpError(404, `Agent '${agentId}' not found`);
+```
+
 Common status codes:
 
 | Code | Meaning |
@@ -311,4 +327,4 @@ Common status codes:
 
 - [Server Routes](/reference/v1/server/routes) - Default Mastra routes
 - [MastraServer](/reference/v1/server/mastra-server) - Server adapter class
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters
+- [Server Adapters](/docs/v1/server/server-adapters) - Using adapters

package/.docs/raw/reference/server/express-adapter.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Express Adapter | Server"
 description: "API reference for the @mastra/express server adapter."
+packages:
+  - "@mastra/express"
 ---
 
 import Steps from "@site/src/components/Steps";
@@ -13,29 +15,21 @@ The `@mastra/express` package provides a server adapter for running Mastra with
 
 :::info
 
-For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
 
 :::
 
 ## Installation
 
-<Steps>
-
-<StepItem>
-
 Install the Express adapter and Express framework:
 
-```bash copy
-npm install @mastra/express express
+```bash
+npm install @mastra/express@beta express
 ```
 
-</StepItem>
-
-<StepItem>
-
-Create your server file:
+## Usage example
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 import express from 'express';
 import { MastraServer } from '@mastra/express';
 import { mastra } from './mastra';
@@ -51,43 +45,12 @@ app.listen(4111, () => {
 });
 ```
 
-</StepItem>
-
-</Steps>
-
 :::note
 
 Express requires `express.json()` middleware for JSON body parsing. Add it before creating the `MastraServer`.
 
 :::
 
-## Full example
-
-```typescript title="server.ts" copy showLineNumbers
-import express from 'express';
-import { MastraServer } from '@mastra/express';
-import { mastra } from './mastra';
-
-const app = express();
-app.use(express.json());
-
-const server = new MastraServer({
-  app,
-  mastra,
-  prefix: '/api/v2',
-  openapiPath: '/openapi.json',
-  bodyLimitOptions: {
-    maxSize: 10 * 1024 * 1024, // 10MB
-    onError: (err) => ({ error: 'Payload too large', maxSize: '10MB' }),
-  },
-  streamOptions: { redact: true },
-});
-
-await server.init();
-
-app.listen(4111);
-```
-
 ## Constructor parameters
 
 <PropertiesTable
@@ -116,6 +79,7 @@ app.listen(4111);
       type: "string",
       description: "Path to serve OpenAPI spec (e.g., `/openapi.json`)",
       isOptional: true,
+      defaultValue: "''",
     },
     {
       name: "bodyLimitOptions",
@@ -136,6 +100,18 @@ app.listen(4111);
       description: "Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.",
       isOptional: true,
     },
+    {
+      name: "tools",
+      type: "Record<string, Tool>",
+      description: "Available tools for the server",
+      isOptional: true,
+    },
+    {
+      name: "taskStore",
+      type: "InMemoryTaskStore",
+      description: "Task store for A2A (Agent-to-Agent) operations",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -153,7 +129,7 @@ app.listen(4111);
 
 Add routes directly to the Express app:
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 const app = express();
 app.use(express.json());
 
@@ -183,7 +159,7 @@ Routes added before `init()` run without Mastra context. Add routes after `init(
 
 In Express middleware and routes, access Mastra context via `res.locals`:
 
-```typescript copy showLineNumbers
+```typescript
 app.get('/custom', (req, res) => {
   const mastra = res.locals.mastra;
   const requestContext = res.locals.requestContext;
@@ -202,13 +178,15 @@ Available properties on `res.locals`:
 | `requestContext` | Request context map |
 | `abortSignal` | Request cancellation signal |
 | `tools` | Available tools |
+| `taskStore` | Task store for A2A operations |
+| `customRouteAuthConfig` | Per-route auth overrides |
 | `user` | Authenticated user (if auth configured) |
 
 ## Adding middleware
 
 Add Express middleware before or after `init()`:
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 const app = express();
 app.use(express.json());
 
@@ -224,14 +202,13 @@ await server.init();
 // Middleware after init has access to Mastra context
 app.use((req, res, next) => {
   const mastra = res.locals.mastra;
-  // ...
   next();
 });
 ```
 
 ## Manual initialization
 
-For custom middleware ordering, call each method separately instead of `init()`. See [Server Adapters: Manual initialization](/docs/v1/server-db/server-adapters#manual-initialization) for details.
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](/docs/v1/server/server-adapters#manual-initialization) for details.
 
 ## Examples
 
@@ -239,7 +216,6 @@ For custom middleware ordering, call each method separately instead of `init()`.
 
 ## Related
 
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Shared adapter concepts
-- [Hono Adapter](/reference/v1/server/hono-adapter) - Alternative adapter
+- [Server Adapters](/docs/v1/server/server-adapters) - Shared adapter concepts
 - [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/reference/server/fastify-adapter.mdx

@@ -0,0 +1,130 @@
+---
+title: "Reference: Fastify Adapter | Server"
+description: "API reference for the @mastra/fastify server adapter."
+packages:
+  - "@mastra/fastify"
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# Fastify Adapter
+
+The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev).
+
+:::info
+
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
+
+:::
+
+## Installation
+
+Install the Fastify adapter and Fastify framework:
+
+```bash
+npm install @mastra/fastify@beta fastify
+```
+
+## Usage example
+
+```typescript title="server.ts"
+import Fastify from 'fastify';
+import { MastraServer } from '@mastra/fastify';
+import { mastra } from './mastra';
+
+const app = Fastify({ logger: true });
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+app.listen({ port: 3000 }, (err, address) => {
+  if (err) {
+    console.error(err);
+    process.exit(1);
+  }
+  console.log(`Server running on ${address}`);
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "app",
+      type: "FastifyInstance",
+      description: "Fastify 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,
+      defaultValue: "''",
+    },
+    {
+      name: "bodyLimitOptions",
+      type: "BodyLimitOptions",
+      typeDescription: "{ maxSize: number, onError: (error: unknown) => unknown }",
+      description: "Request body size limits",
+      isOptional: true,
+    },
+    {
+      name: "streamOptions",
+      type: "StreamOptions",
+      typeDescription: "{ redact?: boolean }",
+      description: "Stream redaction config. When true (default), redacts sensitive data (system prompts, tool definitions, API keys) from stream chunks before sending to clients.",
+      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,
+    },
+    {
+      name: "tools",
+      type: "ToolsInput",
+      typeDescription: "Record<string, ToolAction | VercelTool>",
+      description: "Available tools for the server",
+      isOptional: true,
+    },
+    {
+      name: "taskStore",
+      type: "InMemoryTaskStore",
+      description: "Task store for A2A (Agent-to-Agent) operations",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](/docs/v1/server/server-adapters#manual-initialization) for details.
+
+## Examples
+
+- [Fastify Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-fastify-adapter) - Basic Fastify server setup
+
+## Related
+
+- [Server Adapters](/docs/v1/server/server-adapters) - Shared adapter concepts
+- [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/reference/server/hono-adapter.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Hono Adapter | Server"
 description: "API reference for the @mastra/hono server adapter."
+packages:
+  - "@mastra/hono"
 ---
 
 import Steps from "@site/src/components/Steps";
@@ -13,29 +15,21 @@ The `@mastra/hono` package provides a server adapter for running Mastra with [Ho
 
 :::info
 
-For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
 
 :::
 
 ## Installation
 
-<Steps>
-
-<StepItem>
-
 Install the Hono adapter and Hono framework:
 
-```bash copy
-npm install @mastra/hono hono
+```bash
+npm install @mastra/hono@beta hono
 ```
 
-</StepItem>
-
-<StepItem>
-
-Create your server file:
+## Usage example
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 import { Hono } from 'hono';
 import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
 import { mastra } from './mastra';
@@ -48,37 +42,6 @@ await server.init();
 export default app;
 ```
 
-</StepItem>
-
-</Steps>
-
-## Full example
-
-```typescript title="server.ts" copy showLineNumbers
-import { Hono } from 'hono';
-import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
-import { mastra } from './mastra';
-
-const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
-
-const server = new MastraServer({
-  app,
-  mastra,
-  prefix: '/api/v2',
-  openapiPath: '/openapi.json',
-  bodyLimitOptions: {
-    maxSize: 10 * 1024 * 1024, // 10MB
-    onError: (err) => ({ error: 'Payload too large', maxSize: '10MB' }),
-  },
-  streamOptions: { redact: true },
-});
-
-await server.init();
-
-export default app;
-```
-
-
 ## Constructor parameters
 
 <PropertiesTable
@@ -107,6 +70,7 @@ export default app;
       type: "string",
       description: "Path to serve OpenAPI spec (e.g., `/openapi.json`)",
       isOptional: true,
+      defaultValue: "''",
     },
     {
       name: "bodyLimitOptions",
@@ -127,6 +91,18 @@ export default app;
       description: "Per-route auth overrides. Keys are `METHOD:PATH` (e.g., `GET:/api/health`). Value `false` makes route public, `true` requires auth.",
       isOptional: true,
     },
+    {
+      name: "tools",
+      type: "Record<string, Tool>",
+      description: "Available tools for the server",
+      isOptional: true,
+    },
+    {
+      name: "taskStore",
+      type: "InMemoryTaskStore",
+      description: "Task store for A2A (Agent-to-Agent) operations",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -135,7 +111,7 @@ export default app;
 
 Add routes directly to the Hono app:
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 import { Hono } from 'hono';
 import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
 
@@ -164,7 +140,7 @@ Routes added before `init()` run without Mastra context. Add routes after `init(
 
 In Hono middleware and route handlers, access Mastra context via `c.get()`:
 
-```typescript copy showLineNumbers
+```typescript
 app.get('/custom', async (c) => {
   const mastra = c.get('mastra');
   const requestContext = c.get('requestContext');
@@ -183,13 +159,15 @@ Available context keys:
 | `requestContext` | Request context map |
 | `abortSignal` | Request cancellation signal |
 | `tools` | Available tools |
+| `taskStore` | Task store for A2A operations |
+| `customRouteAuthConfig` | Per-route auth overrides |
 | `user` | Authenticated user (if auth configured) |
 
 ## Adding middleware
 
 Add Hono middleware before or after `init()`:
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 import { Hono } from 'hono';
 import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
 
@@ -207,14 +185,13 @@ await server.init();
 // Middleware after init has access to Mastra context
 app.use('*', async (c, next) => {
   const mastra = c.get('mastra');
-  // ...
   await next();
 });
 ```
 
 ## Manual initialization
 
-For custom middleware ordering, call each method separately instead of `init()`. See [Server Adapters: Manual initialization](/docs/v1/server-db/server-adapters#manual-initialization) for details.
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](/docs/v1/server/server-adapters#manual-initialization) for details.
 
 ## Examples
 
@@ -222,7 +199,6 @@ For custom middleware ordering, call each method separately instead of `init()`.
 
 ## Related
 
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Shared adapter concepts
-- [Express Adapter](/reference/v1/server/express-adapter) - Alternative adapter
+- [Server Adapters](/docs/v1/server/server-adapters) - Shared adapter concepts
 - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
 - [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes