서버 레퍼런스

defineServer(options)

MCP 서버 인스턴스를 생성합니다.

import { defineServer } from '@airmcp-dev/core';

const server = defineServer({
  name: 'my-server',
  version: '1.0.0',
  tools: [ /* ... */ ],
});

AirServerOptions

interface AirServerOptions {
  name: string;                           // 필수 — MCP 등록명
  version?: string;                       // 기본: '0.1.0'
  description?: string;

  tools?: AirToolDef[];
  resources?: AirResourceDef[];
  prompts?: AirPromptDef[];

  use?: Array<AirPlugin | AirPluginFactory>;  // 배열 순서 = 실행 순서
  middleware?: AirMiddleware[];            // 플러그인 미들웨어 이후 실행

  transport?: TransportConfig;
  storage?: StoreOptions;
  meter?: MeterConfig;

  maxSseSessions?: number;                // 기본: 200 — 최대 동시 SSE 세션 수
  sseHeartbeatMs?: number;                // 기본: 30000 — 하트비트 ping 간격 (0이면 비활성)
  sseReplayBufferSize?: number;           // 기본: 100 — 재연결용 메시지 보관 수
  sseReplayTtlMs?: number;               // 기본: 300000 — 재전송 버퍼 TTL
  sseIdleTimeoutMs?: number;             // 기본: 600000 — 유휴 세션 자동 종료

  logging?: {
    level?: 'debug' | 'info' | 'warn' | 'error' | 'silent';  // 기본: 'info'
    format?: 'json' | 'pretty';                                // 기본: 'pretty'
  };

  dev?: {
    hotReload?: boolean;                  // 기본: true
    port?: number;                        // 기본: 3100
  };
}

AirServer

interface AirServer {
  readonly name: string;

  start(): Promise<void>;
  stop(): Promise<void>;
  status(): AirServerStatus;

  tools(): AirToolDef[];
  resources(): AirResourceDef[];

  callTool(name: string, params?: Record<string, any>): Promise<any>;

  addTool(tool: AirToolDef): void;
  addMiddleware(mw: AirMiddleware): void;
  addPlugin(plugin: AirPlugin): void;

  state: Record<string, any>;

  /** Workers fetch 핸들러 (transport: 'workers'일 때 사용) */
  fetch?: (request: Request, env?: any) => Promise<Response>;
}

메서드 상세

server.start()

플러그인 onInit → onStart 훅 실행 후 트랜스포트 연결.

await server.start();
// [air] Starting "my-server" (sse transport, 3 tools)
// [air] SSE server listening on port 3510

server.stop()

플러그인 onStop 훅 실행 후 MCP 연결 종료.

await server.stop();
// [air] "my-server" stopped

server.status()

const s = server.status();

반환값:

interface AirServerStatus {
  name: string;
  version: string;
  state: 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
  uptime: number;           // ms
  toolCount: number;
  resourceCount: number;
  transport: string;        // 'stdio' | 'sse' | 'http' | 'workers'
}

server.callTool(name, params?)

미들웨어 체인(검증, 에러 처리, 플러그인)을 전부 거쳐 도구 호출. 프로덕션과 동일한 경로.

const result = await server.callTool('search', { query: 'hello' });
// 없는 도구 → throws AirError (code: -32601)

내부: 도구 검색 → requestContext 생성 → chain.execute → McpContent[]에서 첫 텍스트 추출.

server.addTool(tool)

런타임 도구 추가. onToolRegister 훅을 거침.

server.addTool(defineTool('dynamic', { handler: async () => 'ok' }));

server.addPlugin(plugin)

런타임 플러그인 등록. 미들웨어가 체인에 동적 추가됨.

server.addPlugin(webhookPlugin({ url: 'https://hooks.example.com' }));

server.state

모든 도구 핸들러에서 context.state로 접근 가능한 공유 객체.

server.state.db = myConnection;

// 핸들러에서
handler: async (params, context) => context.state.db.query(params.sql)

server.fetch(request, env?)

Workers 전용. MCP JSON-RPC 요청을 미들웨어 체인을 거쳐 처리합니다. 모든 transport 타입에서 정의되지만, 주로 transport: { type: 'workers' }에서 사용합니다.

const server = defineServer({
  transport: { type: 'workers' },
  tools: [ /* ... */ ],
});

// Workers fetch 핸들러에서
export default {
  async fetch(request: Request, env: Env) {
    if (request.method === 'POST') {
      return server.fetch!(request);
    }
    return Response.json(server.status());
  },
};

처리하는 JSON-RPC 메서드:

• initialize → 서버 정보 + capabilities (tools, resources, prompts)
• tools/list → 등록된 도구 스키마
• tools/call → 미들웨어 체인을 거친 도구 실행
• resources/list → 등록된 리소스
• resources/read → URI로 리소스 내용 읽기 (v0.4.0+)
• prompts/list → 등록된 프롬프트
• prompts/get → 이름으로 프롬프트 메시지 조회 (v0.4.0+)
• notifications/initialized → 204 No Content

TIP

server.fetch는 workers transport뿐 아니라 항상 정의됩니다. 테스트나 커스텀 HTTP 통합에서도 활용 가능합니다.

onShutdown(handler)

SIGTERM/SIGINT 수신 시 실행할 정리 함수. 여러 개 등록 가능, 등록 순서대로 실행. 하나가 실패해도 나머지 계속 실행.

import { onShutdown } from '@airmcp-dev/core';

onShutdown(async () => {
  await db.close();
  console.log('DB closed');
});

onShutdown(async () => {
  await cache.flush();
});

시그널 수신 시:

[air] SIGTERM received — shutting down...
DB closed
[air] "my-server" stopped