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

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

@@ -1,162 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-# 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

@@ -1,298 +0,0 @@
-# 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