@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/server/hono-adapter.md

@@ -0,0 +1,162 @@
+# 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](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Hono adapter and Hono framework:
+
+**npm**:
+
+```bash
+npm install @mastra/hono@latest hono
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/hono@latest hono
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/hono@latest hono
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/hono@latest hono
+```
+
+## Usage example
+
+```typescript
+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
+```
+
+## Constructor parameters
+
+**app:** (`Hono`): Hono app instance
+
+**mastra:** (`Mastra`): Mastra instance
+
+**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
+
+**openapiPath?:** (`string`): Path to serve OpenAPI spec (e.g., \`/openapi.json\`) (Default: `''`)
+
+**bodyLimitOptions?:** (`{ maxSize: number, onError: (err) => unknown }`): Request body size limits
+
+**streamOptions?:** (`{ redact?: boolean }`): Stream redaction config. When true, redacts sensitive data from streams. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\` (e.g., \`GET:/api/health\`). Value \`false\` makes route public, \`true\` requires auth.
+
+**tools?:** (`Record<string, Tool>`): Available tools for the server
+
+**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions?:** (`MCPOptions`): MCP transport options. Set \`serverless: true\` for stateless environments like Cloudflare Workers or Vercel Edge.
+
+## Adding custom routes
+
+Add routes directly to the Hono app:
+
+```typescript
+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
+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
+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 [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.
+
+## Examples
+
+- [Hono Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-hono-adapter) - Basic Hono server setup
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Shared adapter concepts
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
+- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes

package/.docs/reference/server/koa-adapter.md

@@ -0,0 +1,127 @@
+# Koa Adapter
+
+The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com).
+
+> **Info:** For general adapter concepts (constructor options, initialization flow, etc.), see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Koa adapter and Koa framework:
+
+**npm**:
+
+```bash
+npm install @mastra/koa@latest koa koa-bodyparser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/koa@latest koa koa-bodyparser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/koa@latest koa koa-bodyparser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/koa@latest koa koa-bodyparser
+```
+
+## Usage example
+
+```typescript
+import Koa from 'koa'
+import bodyParser from 'koa-bodyparser'
+import { MastraServer } from '@mastra/koa'
+import { mastra } from './mastra'
+
+const app = new Koa()
+app.use(bodyParser())
+
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000')
+})
+```
+
+## Constructor parameters
+
+**app:** (`Koa`): Koa app instance
+
+**mastra:** (`Mastra`): Mastra instance
+
+**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
+
+**openapiPath?:** (`string`): Path to serve OpenAPI spec (e.g., \`/openapi.json\`) (Default: `''`)
+
+**bodyLimitOptions?:** (`BodyLimitOptions`): Request body size limits
+
+**streamOptions?:** (`StreamOptions`): Stream redaction config. When true (default), redacts sensitive data (system prompts, tool definitions, API keys) from stream chunks before sending to clients. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\` (e.g., \`GET:/api/health\`). Value \`false\` makes route public, \`true\` requires auth.
+
+**tools?:** (`ToolsInput`): Available tools for the server
+
+**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions?:** (`MCPOptions`): MCP transport options. Set \`serverless: true\` for stateless environments like Cloudflare Workers or Vercel Edge.
+
+## Error handling
+
+The Koa adapter propagates errors from route handlers up through Koa's middleware chain, following Koa's standard error handling pattern. This means you can use regular Koa error-handling middleware:
+
+```typescript
+const app = new Koa()
+app.use(bodyParser())
+
+// Your error middleware catches errors from Mastra route handlers
+app.use(async (ctx, next) => {
+  try {
+    await next()
+  } catch (err) {
+    ctx.status = err.status || 500
+    ctx.body = { error: err.message }
+    // Log, report to Sentry, etc.
+  }
+})
+
+const server = new MastraServer({ app, mastra })
+await server.init()
+```
+
+The [`server.onError`](https://mastra.ai/reference/configuration) hook is also supported. When configured, it is called before the error propagates to middleware, and its response is used directly:
+
+```typescript
+const mastra = new Mastra({
+  server: {
+    onError: (err, c) => {
+      console.error('Unhandled error:', err)
+      return c.json({ error: err.message }, 500)
+    },
+  },
+})
+```
+
+When `init()` is used, a global error-handling middleware is also registered as a safety net. Errors that reach this middleware are emitted via `ctx.app.emit('error', err, ctx)` following the standard Koa convention.
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.
+
+## Examples
+
+- [Koa Adapter](https://github.com/mastra-ai/mastra/tree/main/examples/server-koa-adapter) - Basic Koa server setup
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Shared adapter concepts
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
+- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes

package/.docs/reference/server/mastra-server.md

@@ -0,0 +1,298 @@
+# 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
+import { MastraServer } from '@mastra/server/server-adapter'
+```
+
+## Type parameters
+
+```typescript
+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
+constructor(options: MastraServerOptions<TApp>)
+```
+
+### Options
+
+**app:** (`TApp`): Framework app instance
+
+**mastra:** (`Mastra`): Mastra instance
+
+**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
+
+**openapiPath?:** (`string`): Path to serve OpenAPI spec (Default: `''`)
+
+**bodyLimitOptions?:** (`BodyLimitOptions`): Request body size limits
+
+**streamOptions?:** (`StreamOptions`): Stream redaction config (Default: `{ redact: true }`)
+
+**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides
+
+**tools?:** (`Record<string, Tool>`): Available tools for the server
+
+**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions?:** (`MCPOptions`): MCP transport options for serverless environments
+
+## Abstract methods
+
+These methods must be implemented by adapters:
+
+### registerContextMiddleware()
+
+Attach Mastra context to every request.
+
+```typescript
+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
+abstract registerAuthMiddleware(): void
+```
+
+### registerRoute()
+
+Register a single route with the framework.
+
+```typescript
+abstract registerRoute(
+  app: TApp,
+  route: ServerRoute,
+  options: { prefix?: string }
+): Promise<void>
+```
+
+### getParams()
+
+Extract parameters from the request.
+
+```typescript
+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
+abstract sendResponse(
+  route: ServerRoute,
+  response: TResponse,
+  result: unknown
+): Promise<unknown>
+```
+
+### stream()
+
+Handle streaming responses.
+
+```typescript
+abstract stream(
+  route: ServerRoute,
+  response: TResponse,
+  result: unknown
+): Promise<unknown>
+```
+
+## Instance methods
+
+### init()
+
+Initialize the server by registering all middleware and routes.
+
+```typescript
+async init(): Promise<void>
+```
+
+Calls in order:
+
+1. `registerContextMiddleware()`
+2. `registerAuthMiddleware()`
+3. `registerRoutes()`
+
+### registerRoutes()
+
+Register all Mastra routes.
+
+```typescript
+async registerRoutes(): Promise<void>
+```
+
+### getApp()
+
+Get the framework app instance.
+
+```typescript
+getApp<T = TApp>(): T
+```
+
+### parsePathParams()
+
+Validate path parameters with the route's Zod schema.
+
+```typescript
+async parsePathParams(
+  route: ServerRoute,
+  params: Record<string, string>
+): Promise<Record<string, unknown>>
+```
+
+### parseQueryParams()
+
+Validate query parameters with the route's Zod schema.
+
+```typescript
+async parseQueryParams(
+  route: ServerRoute,
+  params: Record<string, string>
+): Promise<Record<string, unknown>>
+```
+
+### parseBody()
+
+Validate request body with the route's Zod schema.
+
+```typescript
+async parseBody(
+  route: ServerRoute,
+  body: unknown
+): Promise<unknown>
+```
+
+### registerOpenAPIRoute()
+
+Register an endpoint that serves the OpenAPI specification.
+
+```typescript
+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
+protected mergeRequestContext(options: {
+  paramsRequestContext?: Record<string, any>;
+  bodyRequestContext?: Record<string, any>;
+}): RequestContext
+```
+
+## Types
+
+### BodyLimitOptions
+
+```typescript
+interface BodyLimitOptions {
+  maxSize: number
+  onError: (error: unknown) => unknown
+}
+```
+
+### StreamOptions
+
+```typescript
+interface StreamOptions {
+  redact?: boolean
+}
+```
+
+### MCPOptions
+
+```typescript
+interface MCPOptions {
+  serverless?: boolean
+  sessionIdGenerator?: () => string
+}
+```
+
+| Property             | Description                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverless`         | When `true`, runs MCP in stateless mode without session management. Use for serverless environments like Cloudflare Workers or Vercel Edge. |
+| `sessionIdGenerator` | Custom function to generate session IDs.                                                                                                    |
+
+## Example
+
+```typescript
+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](https://mastra.ai/docs/server/server-adapters) - Using adapters
+- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters) - Creating custom adapters
+- [createRoute()](https://mastra.ai/reference/server/create-route) - Creating custom routes