> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 마스트라서버

그만큼`MastraServer`추상 클래스는 모든 서버 어댑터의 기본입니다. Hono 또는 Express 이외의 프레임워크용 어댑터를 만들려면 이 클래스를 확장하세요.

## 수입

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

## 유형 매개변수

```typescript
MastraServer<TApp, TRequest, TResponse>
```

| 매개변수        | 설명                                               |
| ----------- | ------------------------------------------------ |
| `TApp`      | Framework app type (e.g., `Hono`, `Application`) |
| `TRequest`  | 프레임워크 요청 유형                                      |
| `TResponse` | 프레임워크 응답/컨텍스트 유형                                 |

## 건설자

```typescript
constructor(options: MastraServerOptions<TApp>)
```

### 옵션

**app** (`TApp`): 프레임워크 앱 인스턴스

**mastra** (`Mastra`): Mastra 인스턴스

**prefix** (`string`): 경로 경로 접두사(예: /api/v2) (Default: `''`)

**openapiPath** (`string`): OpenAPI 명세를 제공할 경로 (Default: `''`)

**bodyLimitOptions** (`BodyLimitOptions`): 요청 본문 크기 제한

**streamOptions** (`StreamOptions`): 스트림 마스킹 구성 (Default: `{ redact: true }`)

**customRouteAuthConfig** (`Map<string, boolean>`): 경로별 인증 재정의

**tools** (`Record<string, Tool>`): 서버에서 사용할 수 있는 Tool

**taskStore** (`InMemoryTaskStore`): A2A(Agent-to-Agent) 작업용 작업 저장소

**mcpOptions** (`MCPOptions`): 서버리스 환경을 위한 MCP 전송 옵션

## 추상 메소드

이러한 메서드는 어댑터로 구현되어야 합니다.

### `registerContextMiddleware()`

모든 요청에 ​​Mastra 컨텍스트를 연결합니다.

```typescript
abstract registerContextMiddleware(): void
```

**첨부할 컨텍스트:**

- `mastra`- 마스트라 인스턴스
- `requestContext`- 요청 범위 컨텍스트
- `tools`- 사용 가능한 Tool
- `abortSignal`- 취소 신호 요청

### `registerAuthMiddleware()`

초기화 중에 어댑터 인증 후크를 실행합니다. 공식 어댑터는 인증이 경로별로 시행될 때 이를 무작동(no-op)으로 구현할 수 있습니다.

```typescript
abstract registerAuthMiddleware(): void
```

### `registerRoute()`

프레임워크에 단일 경로를 등록합니다.

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

### `getParams()`

요청에서 매개변수를 추출합니다.

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

### `sendResponse()`

경로 유형에 따라 응답을 보냅니다.

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

### `stream()`

스트리밍 응답을 처리합니다.

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

## 인스턴스 메소드

### `init()`

모든 미들웨어와 경로를 등록하여 서버를 초기화합니다.

```typescript
async init(): Promise<void>
```

순서대로 호출:

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

### `registerRoutes()`

모든 Mastra 경로를 등록하세요.

```typescript
async registerRoutes(): Promise<void>
```

### `getApp()`

프레임워크 앱 인스턴스를 가져옵니다.

```typescript
getApp<T = TApp>(): T
```

### `parsePathParams()`

경로의 Zod 스키마를 사용하여 경로 매개변수의 유효성을 검사합니다.

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

### `parseQueryParams()`

경로의 Zod 스키마를 사용하여 쿼리 매개변수의 유효성을 검사합니다.

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

### `parseBody()`

경로의 Zod 스키마를 사용하여 요청 본문의 유효성을 검사합니다.

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

### `registerOpenAPIRoute()`

OpenAPI 사양을 제공하는 엔드포인트를 등록합니다.

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

## 보호된 방법

### `mergeRequestContext()`

여러 소스(쿼리 매개변수 및 본문)의 요청 컨텍스트를 병합합니다.

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

## 유형

### `BodyLimitOptions`

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

### `StreamOptions`

```typescript
interface StreamOptions {
  redact?: boolean
}
```

### MCP옵션

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

| 속성                   | 설명                                                                                              |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `serverless`         | `true`이면 세션 관리 없이 MCP를 상태 비저장 모드로 실행합니다. Cloudflare Workers 또는 Vercel Edge와 같은 서버리스 환경에서 사용합니다. |
| `sessionIdGenerator` | 세션 ID를 생성하는 사용자 지정 함수입니다.                                                                       |

## 예

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

## 관련된

- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters): 어댑터 사용
- [맞춤형 어댑터](https://mastra.zisheng.pro/ko/docs/server/custom-adapters): 사용자 정의 어댑터 만들기
- [경로 생성()](https://mastra.zisheng.pro/ko/reference/server/create-route): 커스텀 경로 생성