@mastra/mcp-docs-server 1.0.0-beta.6 → 1.0.0-beta.7

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

@@ -0,0 +1,314 @@
+---
+title: "Reference: createRoute() | Server"
+description: "API reference for createRoute() function used to define type-safe routes with validation and OpenAPI generation."
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# createRoute()
+
+The `createRoute()` function creates type-safe routes with Zod validation. When an `openapiPath` is configured on the server adapter, it generates OpenAPI schema entries from the supplied Zod schemas.
+
+## Import
+
+```typescript copy
+import { createRoute } from '@mastra/server';
+```
+
+## Signature
+
+```typescript copy
+function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
+  config: RouteConfig<TPath, TQuery, TBody, TResponse, TResponseType>
+): ServerRoute
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "method",
+      type: "'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'",
+      description: "HTTP method",
+      isOptional: false,
+    },
+    {
+      name: "path",
+      type: "string",
+      description: "Route path with optional params (e.g., `/api/items/:id`)",
+      isOptional: false,
+    },
+    {
+      name: "responseType",
+      type: "'json' | 'stream'",
+      description: "Response format. Internal routes may use additional types (`datastream-response`, `mcp-http`, `mcp-sse`).",
+      isOptional: false,
+    },
+    {
+      name: "handler",
+      type: "ServerRouteHandler",
+      description: "Route handler function",
+      isOptional: false,
+    },
+    {
+      name: "pathParamSchema",
+      type: "ZodSchema",
+      description: "Validates URL path parameters",
+      isOptional: true,
+    },
+    {
+      name: "queryParamSchema",
+      type: "ZodSchema",
+      description: "Validates query string parameters",
+      isOptional: true,
+    },
+    {
+      name: "bodySchema",
+      type: "ZodSchema",
+      description: "Validates request body",
+      isOptional: true,
+    },
+    {
+      name: "responseSchema",
+      type: "ZodSchema",
+      description: "Documents response shape for OpenAPI",
+      isOptional: true,
+    },
+    {
+      name: "streamFormat",
+      type: "'sse' | 'stream'",
+      description: "Stream format (when responseType is 'stream')",
+      isOptional: true,
+    },
+    {
+      name: "maxBodySize",
+      type: "number",
+      description: "Override default body size limit in bytes",
+      isOptional: true,
+    },
+    {
+      name: "summary",
+      type: "string",
+      description: "OpenAPI summary",
+      isOptional: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "OpenAPI description",
+      isOptional: true,
+    },
+    {
+      name: "tags",
+      type: "string[]",
+      description: "OpenAPI tags",
+      isOptional: true,
+    },
+    {
+      name: "deprecated",
+      type: "boolean",
+      description: "Mark route as deprecated",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Handler parameters
+
+The handler receives validated parameters plus runtime context:
+
+```typescript copy showLineNumbers
+handler: async (params) => {
+  // From schemas (typed from Zod)
+  params.id;              // From pathParamSchema
+  params.filter;          // From queryParamSchema
+  params.name;            // From bodySchema
+
+  // Runtime context (always available)
+  params.mastra;          // Mastra instance
+  params.requestContext;  // Request-scoped context
+  params.tools;           // Available tools
+  params.abortSignal;     // Request cancellation signal
+  params.taskStore;       // A2A task storage
+}
+```
+
+## Return value
+
+Returns a `ServerRoute` object that can be registered with an adapter.
+
+## Examples
+
+### GET route with path params
+
+```typescript copy showLineNumbers
+import { createRoute } from '@mastra/server';
+import { z } from 'zod';
+
+const getAgent = createRoute({
+  method: 'GET',
+  path: '/api/agents/:agentId',
+  responseType: 'json',
+  pathParamSchema: z.object({
+    agentId: z.string(),
+  }),
+  responseSchema: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+  summary: 'Get agent by ID',
+  tags: ['Agents'],
+  handler: async ({ agentId, mastra }) => {
+    return mastra.getAgent(agentId);
+  },
+});
+```
+
+### POST route with body
+
+```typescript copy showLineNumbers
+const createItem = createRoute({
+  method: 'POST',
+  path: '/api/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+    value: z.number(),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    value: z.number(),
+  }),
+  handler: async ({ name, value, mastra }) => {
+    // name and value are typed from bodySchema
+    return { id: 'new-id', name, value };
+  },
+});
+```
+
+### Query params with coercion
+
+```typescript copy showLineNumbers
+const listItems = createRoute({
+  method: 'GET',
+  path: '/api/items',
+  responseType: 'json',
+  queryParamSchema: z.object({
+    page: z.coerce.number().default(0),
+    limit: z.coerce.number().default(50),
+    enabled: z.coerce.boolean().optional(),
+  }),
+  handler: async ({ page, limit, enabled, mastra }) => {
+    // page, limit, enabled are typed and coerced
+    return { items: [], page, limit };
+  },
+});
+```
+
+### Streaming route
+
+```typescript copy showLineNumbers
+const streamAgent = createRoute({
+  method: 'POST',
+  path: '/api/agents/:agentId/stream',
+  responseType: 'stream',
+  streamFormat: 'sse',
+  pathParamSchema: z.object({
+    agentId: z.string(),
+  }),
+  bodySchema: z.object({
+    messages: z.array(z.any()),
+  }),
+  handler: async ({ agentId, messages, mastra, abortSignal }) => {
+    const agent = mastra.getAgent(agentId);
+    return agent.stream({ messages, abortSignal });
+  },
+});
+```
+
+### Custom body size limit
+
+```typescript copy showLineNumbers
+const uploadRoute = createRoute({
+  method: 'POST',
+  path: '/api/upload',
+  responseType: 'json',
+  maxBodySize: 50 * 1024 * 1024, // 50MB
+  bodySchema: z.object({
+    file: z.string(),
+  }),
+  handler: async ({ file }) => {
+    return { uploaded: true };
+  },
+});
+```
+
+## Schema patterns
+
+### Passthrough for extensibility
+
+```typescript copy
+const bodySchema = z.object({
+  required: z.string(),
+}).passthrough(); // Allow unknown fields
+```
+
+### Date coercion
+
+```typescript copy
+const querySchema = z.object({
+  fromDate: z.coerce.date().optional(),
+  toDate: z.coerce.date().optional(),
+});
+```
+
+### Union types
+
+```typescript copy
+const bodySchema = z.object({
+  messages: z.union([
+    z.array(z.any()),
+    z.string(),
+  ]),
+});
+```
+
+## Error handling
+
+Throw `HTTPException` to return specific HTTP status codes from handlers:
+
+```typescript copy showLineNumbers
+import { createRoute, HTTPException } from '@mastra/server';
+
+const getAgent = createRoute({
+  method: 'GET',
+  path: '/api/agents/:agentId',
+  responseType: 'json',
+  pathParamSchema: z.object({ agentId: z.string() }),
+  handler: async ({ agentId, mastra }) => {
+    const agent = mastra.getAgent(agentId);
+    if (!agent) {
+      throw new HTTPException(404, { message: `Agent '${agentId}' not found` });
+    }
+    return agent;
+  },
+});
+```
+
+Common status codes:
+
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 500 | Internal Server Error |
+
+## Related
+
+- [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

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

@@ -0,0 +1,193 @@
+---
+title: "Reference: Express Adapter | Server"
+description: "API reference for the @mastra/express server adapter."
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Express Adapter
+
+The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com).
+
+:::info
+
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+
+:::
+
+## Installation
+
+<Steps>
+
+<StepItem>
+
+Install the Express adapter and Express framework:
+
+```bash copy
+npm install @mastra/express express
+```
+
+</StepItem>
+
+<StepItem>
+
+Create your server file:
+
+```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()); // Required for body parsing
+
+const server = new MastraServer({ app, mastra });
+await server.init();
+
+app.listen(4111, () => {
+  console.log('Server running on port 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);
+```
+
+## Differences from Hono
+
+| Aspect | Express | Hono |
+|--------|---------|------|
+| Body parsing | Requires `express.json()` | Handled by framework |
+| Context storage | `res.locals` | `c.get()` / `c.set()` |
+| Middleware signature | `(req, res, next)` | `(c, next)` |
+| Streaming | `res.write()` / `res.end()` | `stream()` helper |
+| AbortSignal | Created from `req.on('close')` | `c.req.raw.signal` |
+
+## Adding custom routes
+
+Add routes directly to the Express app:
+
+```typescript title="server.ts" copy showLineNumbers
+const app = express();
+app.use(express.json());
+
+const server = new MastraServer({ app, mastra });
+
+// Before init - runs before Mastra middleware
+app.get('/early-health', (req, res) => res.json({ status: 'ok' }));
+
+await server.init();
+
+// After init - has access to Mastra context
+app.get('/custom', (req, res) => {
+  const mastraInstance = res.locals.mastra;
+  res.json({ agents: Object.keys(mastraInstance.listAgents()) });
+});
+
+app.listen(4111);
+```
+
+:::tip
+
+Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
+
+:::
+
+## Accessing context
+
+In Express middleware and routes, access Mastra context via `res.locals`:
+
+```typescript copy showLineNumbers
+app.get('/custom', (req, res) => {
+  const mastra = res.locals.mastra;
+  const requestContext = res.locals.requestContext;
+  const abortSignal = res.locals.abortSignal;
+
+  const agent = mastra.getAgent('myAgent');
+  res.json({ agent: agent.name });
+});
+```
+
+Available properties on `res.locals`:
+
+| Key | Description |
+|-----|-------------|
+| `mastra` | Mastra instance |
+| `requestContext` | Request context map |
+| `abortSignal` | Request cancellation signal |
+| `tools` | Available tools |
+| `user` | Authenticated user (if auth configured) |
+
+## Adding middleware
+
+Add Express middleware before or after `init()`:
+
+```typescript title="server.ts" copy showLineNumbers
+const app = express();
+app.use(express.json());
+
+// Middleware before init
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+const server = new MastraServer({ app, mastra });
+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.
+
+## Examples
+
+- [Express Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-express-adapter) - Basic Express server setup
+
+## Related
+
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Shared adapter concepts
+- [Hono Adapter](/reference/v1/server/hono-adapter) - Alternative adapter
+- [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

@@ -0,0 +1,174 @@
+---
+title: "Reference: Hono Adapter | Server"
+description: "API reference for the @mastra/hono server adapter."
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Hono Adapter
+
+The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev).
+
+:::info
+
+For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+
+:::
+
+## Installation
+
+<Steps>
+
+<StepItem>
+
+Install the Hono adapter and Hono framework:
+
+```bash copy
+npm install @mastra/hono hono
+```
+
+</StepItem>
+
+<StepItem>
+
+Create your server file:
+
+```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 });
+
+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;
+```
+
+## Adding custom routes
+
+Add routes directly to the Hono app:
+
+```typescript title="server.ts" copy showLineNumbers
+import { Hono } from 'hono';
+import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+const server = new MastraServer({ app, mastra });
+
+// Before init - runs before Mastra middleware
+app.get('/early-health', (c) => c.json({ status: 'ok' }));
+
+await server.init();
+
+// After init - has access to Mastra context
+app.get('/custom', (c) => {
+  const mastraInstance = c.get('mastra');
+  return c.json({ agents: Object.keys(mastraInstance.listAgents()) });
+});
+```
+
+:::tip
+
+Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
+
+:::
+
+## Accessing context
+
+In Hono middleware and route handlers, access Mastra context via `c.get()`:
+
+```typescript copy showLineNumbers
+app.get('/custom', async (c) => {
+  const mastra = c.get('mastra');
+  const requestContext = c.get('requestContext');
+  const abortSignal = c.get('abortSignal');
+
+  const agent = mastra.getAgent('myAgent');
+  return c.json({ agent: agent.name });
+});
+```
+
+Available context keys:
+
+| Key | Description |
+|-----|-------------|
+| `mastra` | Mastra instance |
+| `requestContext` | Request context map |
+| `abortSignal` | Request cancellation signal |
+| `tools` | Available tools |
+| `user` | Authenticated user (if auth configured) |
+
+## Adding middleware
+
+Add Hono middleware before or after `init()`:
+
+```typescript title="server.ts" copy showLineNumbers
+import { Hono } from 'hono';
+import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+
+// Middleware before init
+app.use('*', async (c, next) => {
+  console.log(`${c.req.method} ${c.req.url}`);
+  await next();
+});
+
+const server = new MastraServer({ app, mastra });
+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.
+
+## Examples
+
+- [Hono Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-hono-adapter) - Basic Hono server setup
+
+## Related
+
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Shared adapter concepts
+- [Express Adapter](/reference/v1/server/express-adapter) - Alternative adapter
+- [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
+- [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes