TypeScript로 구축하는 MCP 서버, 무너지지 않게

당신의 MCP 서버는 도구 3개 정도에서는 잘 동작합니다. 하지만 도구 12개가 되면 손대기 두려운 스위치 케이스들의 더미가 됩니다. 여기서는 도메인‑주도 설계(DDD)에서 직접 차용한 TypeScript 아키텍처를 소개합니다. 이 아키텍처는 서버가 성장해도 코드를 깔끔하게 유지해 줍니다.

대부분의 MCP 서버 튜토리얼은 다음과 같은 코드로 시작합니다:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    { name: "get_user", description: "\"Get a user by ID\", inputSchema: { ... } },"
    { name: "create_order", description: "\"Create an order\", inputSchema: { ... } },"
    { name: "send_email", description: "\"Send an email\", inputSchema: { ... } },"
    { name: "get_product", description: "\"Get product details\", inputSchema: { ... } },"
    // ...8 more tools
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case "get_user": return handleGetUser(request.params.arguments);
    case "create_order": return handleCreateOrder(request.params.arguments);
    case "send_email": return handleSendEmail(request.params.arguments);
    // ...
  }
});

익숙하시나요? 문제는 코드가 잘못됐다는 것이 아니라, 정확히 한 사람이 3주 동안만 유지보수할 수 있을 정도로만 확장된다는 점입니다.

실제 운영 환경에 들어서면—예를 들어 사용자 로직과 주문 로직을 담당하는 주체가 다르고, 인증 컨텍스트가 서로 다르며, 상태를 갖는 리소스가 필요해지면—구조가 필요합니다. 바로 여기서 도메인‑주도 설계(DDD)의 가치가 발휘됩니다.

600페이지짜리 책을 읽어야 하는 것은 아닙니다. 여기서는 90% 이상의 상황을 커버하는 세 가지 개념만 알면 충분합니다.

이 분야에 대한 번역 규칙: “아키텍처” 글을 쓰지 말고, 코드를 통해 아키텍처를 가르치는 TypeScript 튜토리얼을 작성하라. 이제 실제로 만들어 보겠습니다.

DDD에서 경계된 컨텍스트는 특정 도메인 모델이 적용되는 경계를 의미합니다. MCP 서버에서는 이것을 도구 명명 규칙과 관련 도구들을 묶는 팩터리 함수로 깔끔하게 구현할 수 있습니다.

다음은 createDomainTools 팩터리 예시입니다:

// src/domains/types.ts

import { Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";

export interface DomainTool {
  definition: Tool;
  handler: (input: TInput) => Promise;
}

export interface DomainModule {
  namespace: string;
  tools: DomainTool[];
}

export function createDomainModule(
  namespace: string,
  tools: DomainTool[]
): DomainModule {
  return {
    namespace,
    tools: tools.map((tool) => ({
      ...tool,
      definition: {
        ...tool.definition,
        name: `${namespace}__${tool.definition.name}`,
      },
    })),
  };
}

이제 users 도메인을 정의해 보겠습니다:

// src/domains/users.ts

import { createDomainModule } from "./types.js";

export const usersDomain = createDomainModule("users", [
  {
    definition: {
      name: "get",
      description: "Get a user by ID",
      inputSchema: {
        type: "object",
        properties: {
          id: { type: "string", description: "User UUID" },
        },
        required: ["id"],
      },
    },
    handler: async ({ id }: { id: string }) => {
      const user = await db.users.findById(id);
      return {
        content: [{ type: "text", text: JSON.stringify(user) }],
      };
    },
  },
  {
    definition: {
      name: "list",
      description: "List users with optional filters",
      inputSchema: {
        type: "object",
        properties: {
          limit: { type: "number" },
          role: { type: "string" },
        },
      },
    },
    handler: async ({ limit = 20, role }: { limit?: number; role?: string }) => {
      const users = await db.users.findMany({ limit, role });
      return {
        content: [{ type: "text", text: JSON.stringify(users) }],
      };
    },
  },
]);

생성된 도구 이름은 users__get와 users__list가