MastraServer

La classe abstraite MastraServer est la base de tous les adaptateurs de serveur. Étendez cette classe pour créer des adaptateurs pour des frameworks autres que Hono ou Express.

Importation

import { MastraServer } from '@mastra/server/server-adapter'

Paramètres de type

MastraServer<TApp, TRequest, TResponse>

Paramètre	Description
TApp	Type d'application du framework (par exemple, Hono, Application)
TRequest	Type de requête du framework
TResponse	Type de réponse/contexte du framework

Constructeur

constructor(options: MastraServerOptions<TApp>)

Options

app:

TApp

Instance d'application du framework

mastra:

Mastra

Instance Mastra

prefix?:

string

= ''

Préfixe du chemin de route (par exemple, /api/v2)

openapiPath?:

string

= ''

Chemin servant la spécification OpenAPI

bodyLimitOptions?:

BodyLimitOptions

Limites de taille du corps de la requête

streamOptions?:

StreamOptions

= { redact: true }

Configuration de masquage du flux

customRouteAuthConfig?:

Map<string, boolean>

Remplacements d'authentification par route

tools?:

Record<string, Tool>

Outils disponibles pour le serveur

taskStore?:

InMemoryTaskStore

Magasin de tâches pour les opérations A2A (Agent-to-Agent)

mcpOptions?:

MCPOptions

Options de transport MCP pour les environnements serverless

Méthodes abstraites

Ces méthodes doivent être implémentées par les adaptateurs :

registerContextMiddleware()

Attache le contexte Mastra à chaque requête.

abstract registerContextMiddleware(): void

Contexte à attacher :

• mastra - instance Mastra
• requestContext - contexte limité à la requête
• tools - outils disponibles
• abortSignal - signal d'annulation de la requête

registerAuthMiddleware()

Exécute le hook d'authentification de l'adaptateur pendant l'initialisation. Les adaptateurs officiels peuvent l'implémenter comme une opération vide lorsque l'authentification est appliquée par route.

abstract registerAuthMiddleware(): void

registerRoute()

Enregistre une seule route auprès du framework.

abstract registerRoute(
  app: TApp,
  route: ServerRoute,
  options: { prefix?: string }
): Promise<void>

getParams()

Extrait les paramètres de la requête.

abstract getParams(
  route: ServerRoute,
  request: TRequest
): Promise<{
  urlParams: Record<string, string>;
  queryParams: Record<string, string>;
  body: unknown;
}>

sendResponse()

Envoie une réponse en fonction du type de route.

abstract sendResponse(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

stream()

Gère les réponses en flux continu.

abstract stream(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

Méthodes d'instance

init()

Initialise le serveur en enregistrant tous les middlewares et toutes les routes.

async init(): Promise<void>

Appelle, dans l'ordre :

1. registerContextMiddleware()
2. registerAuthMiddleware()
3. registerRoutes()

registerRoutes()

Enregistre toutes les routes Mastra.

async registerRoutes(): Promise<void>

getApp()

Obtient l'instance d'application du framework.

getApp<T = TApp>(): T

parsePathParams()

Valide les paramètres de chemin avec le schéma Zod de la route.

async parsePathParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseQueryParams()

Valide les paramètres de requête avec le schéma Zod de la route.

async parseQueryParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseBody()

Valide le corps de la requête avec le schéma Zod de la route.

async parseBody(
  route: ServerRoute,
  body: unknown
): Promise<unknown>

registerOpenAPIRoute()

Enregistre un endpoint qui sert la spécification OpenAPI.

async registerOpenAPIRoute(
  app: TApp,
  config: OpenAPIConfig,
  options: { prefix?: string }
): Promise<void>

Méthodes protégées

mergeRequestContext()

Fusionne le contexte de la requête à partir de plusieurs sources (paramètres de requête et corps).

protected mergeRequestContext(options: {
  paramsRequestContext?: Record<string, any>;
  bodyRequestContext?: Record<string, any>;
}): RequestContext

Types

BodyLimitOptions

interface BodyLimitOptions {
  maxSize: number
  onError: (error: unknown) => unknown
}

StreamOptions

interface StreamOptions {
  redact?: boolean
}

MCPOptions

interface MCPOptions {
  serverless?: boolean
  sessionIdGenerator?: () => string
}

Propriété	Description
serverless	Lorsque la valeur est true, exécute MCP en mode sans état, sans gestion des sessions. À utiliser pour des environnements serverless tels que Cloudflare Workers ou Vercel Edge.
sessionIdGenerator	Fonction personnalisée qui génère des ID de session.

Exemple

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
    // Register global auth middleware, or leave this empty and
    // enforce auth when routes are registered.
  }

  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
  }
}

Ressources associées

• Adaptateurs de serveur : utiliser des adaptateurs
• Adaptateurs personnalisés : créer des adaptateurs personnalisés
• createRoute() : créer des routes personnalisées