@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.11

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

@@ -0,0 +1,242 @@
+---
+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";
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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
+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
+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
+  content={[
+    {
+      name: "app",
+      type: "Hono",
+      description: "Hono 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: "{ 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,
+    },
+    {
+      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,
+    },
+  ]}
+/>
+
+
+## Adding custom routes
+
+Add routes directly to the Hono app:
+
+```typescript title="server.ts" copy
+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
+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 |
+| `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
+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

package/.docs/raw/reference/server/mastra-server.mdx

@@ -0,0 +1,345 @@
+---
+title: "Reference: MastraServer | Server"
+description: "API reference for the MastraServer abstract class used to create server adapters."
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# MastraServer
+
+The `MastraServer` abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.
+
+## Import
+
+```typescript copy
+import { MastraServer } from '@mastra/server/server-adapter';
+```
+
+## Type parameters
+
+```typescript copy
+MastraServer<TApp, TRequest, TResponse>
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `TApp` | Framework app type (e.g., `Hono`, `Application`) |
+| `TRequest` | Framework request type |
+| `TResponse` | Framework response/context type |
+
+## Constructor
+
+```typescript copy
+constructor(options: MastraServerOptions<TApp>)
+```
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "app",
+      type: "TApp",
+      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",
+      isOptional: true,
+      defaultValue: "''",
+    },
+    {
+      name: "bodyLimitOptions",
+      type: "BodyLimitOptions",
+      description: "Request body size limits",
+      isOptional: true,
+    },
+    {
+      name: "streamOptions",
+      type: "StreamOptions",
+      description: "Stream redaction config",
+      isOptional: true,
+      defaultValue: "{ redact: true }",
+    },
+    {
+      name: "customRouteAuthConfig",
+      type: "Map<string, boolean>",
+      description: "Per-route auth overrides",
+      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,
+    },
+    {
+      name: "playground",
+      type: "boolean",
+      description: "Can be read to set context values in adapters implementing the MastraServer",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "isDev",
+      type: "boolean",
+      description: "Development mode flag",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>
+
+## Abstract methods
+
+These methods must be implemented by adapters:
+
+### registerContextMiddleware()
+
+Attach Mastra context to every request.
+
+```typescript copy
+abstract registerContextMiddleware(): void
+```
+
+**Context to attach:**
+- `mastra` - Mastra instance
+- `requestContext` - Request-scoped context
+- `tools` - Available tools
+- `abortSignal` - Request cancellation signal
+
+### registerAuthMiddleware()
+
+Register authentication and authorization middleware.
+
+```typescript copy
+abstract registerAuthMiddleware(): void
+```
+
+### registerRoute()
+
+Register a single route with the framework.
+
+```typescript copy
+abstract registerRoute(
+  app: TApp,
+  route: ServerRoute,
+  options: { prefix?: string }
+): Promise<void>
+```
+
+### getParams()
+
+Extract parameters from the request.
+
+```typescript copy
+abstract getParams(
+  route: ServerRoute,
+  request: TRequest
+): Promise<{
+  urlParams: Record<string, string>;
+  queryParams: Record<string, string>;
+  body: unknown;
+}>
+```
+
+### sendResponse()
+
+Send response based on route type.
+
+```typescript copy
+abstract sendResponse(
+  route: ServerRoute,
+  response: TResponse,
+  result: unknown
+): Promise<unknown>
+```
+
+### stream()
+
+Handle streaming responses.
+
+```typescript copy
+abstract stream(
+  route: ServerRoute,
+  response: TResponse,
+  result: unknown
+): Promise<unknown>
+```
+
+## Instance methods
+
+### init()
+
+Initialize the server by registering all middleware and routes.
+
+```typescript copy
+async init(): Promise<void>
+```
+
+Calls in order:
+1. `registerContextMiddleware()`
+2. `registerAuthMiddleware()`
+3. `registerRoutes()`
+
+### registerRoutes()
+
+Register all Mastra routes.
+
+```typescript copy
+async registerRoutes(): Promise<void>
+```
+
+### getApp()
+
+Get the framework app instance.
+
+```typescript copy
+getApp<T = TApp>(): T
+```
+
+### parsePathParams()
+
+Validate path parameters with the route's Zod schema.
+
+```typescript copy
+async parsePathParams(
+  route: ServerRoute,
+  params: Record<string, string>
+): Promise<Record<string, unknown>>
+```
+
+### parseQueryParams()
+
+Validate query parameters with the route's Zod schema.
+
+```typescript copy
+async parseQueryParams(
+  route: ServerRoute,
+  params: Record<string, string>
+): Promise<Record<string, unknown>>
+```
+
+### parseBody()
+
+Validate request body with the route's Zod schema.
+
+```typescript copy
+async parseBody(
+  route: ServerRoute,
+  body: unknown
+): Promise<unknown>
+```
+
+### registerOpenAPIRoute()
+
+Register an endpoint that serves the OpenAPI specification.
+
+```typescript copy
+async registerOpenAPIRoute(
+  app: TApp,
+  config: OpenAPIConfig,
+  options: { prefix?: string }
+): Promise<void>
+```
+
+## Protected methods
+
+### mergeRequestContext()
+
+Merge request context from multiple sources (query params and body).
+
+```typescript copy
+protected mergeRequestContext(options: {
+  paramsRequestContext?: Record<string, any>;
+  bodyRequestContext?: Record<string, any>;
+}): RequestContext
+```
+
+## Types
+
+### BodyLimitOptions
+
+```typescript copy
+interface BodyLimitOptions {
+  maxSize: number;
+  onError: (error: unknown) => unknown;
+}
+```
+
+### StreamOptions
+
+```typescript copy
+interface StreamOptions {
+  redact?: boolean;
+}
+```
+
+## Example
+
+```typescript copy
+import { MastraServer, ServerRoute } from '@mastra/server/server-adapter';
+import type { Mastra } from '@mastra/core';
+
+export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
+  registerContextMiddleware(): void {
+    this.app.use('*', (req, res, next) => {
+      res.locals.mastra = this.mastra;
+      next();
+    });
+  }
+
+  registerAuthMiddleware(): void {
+    const auth = this.mastra.getServer()?.auth;
+    if (!auth) return;
+    // Implement auth
+  }
+
+  async registerRoute(app, route, { prefix }) {
+    // Implement route registration
+  }
+
+  async getParams(route, request) {
+    return {
+      urlParams: request.params,
+      queryParams: request.query,
+      body: request.body,
+    };
+  }
+
+  async sendResponse(route, response, result) {
+    return response.json(result);
+  }
+
+  async stream(route, response, result) {
+    // Implement streaming
+  }
+}
+```
+
+## Related
+
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters
+- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Creating custom adapters
+- [createRoute()](/reference/v1/server/create-route) - Creating custom routes