학습 목표

이 프로젝트를 통해 다음 내용을 익히게 됩니다:

1. MCP 프로토콜의 핵심 개념 : 모델 컨텍스트 프로토콜 설계 원리 이해
2. 서버 아키텍처 설계 : 확장 가능한 도구 서버 구축 방법
3. 다중 전송 프로토콜 지원 : stdio, SSE, HTTP 등 다양한 통신 방식 활용
4. 타입 안전 개발 기법 : TypeScript와 Zod의 최적화된 사용법
5. 도구 시스템 설계 : 인터페이스 설계 패턴 파악

第一部分: MCP 프로토콜 기초 이해

1.1 MCP란?

MCP(Model Context Protocol)는 AI 모델과 외부 도구/데이터소스 간 상호작용을 표준화한 프로토콜입니다. 주요 기능으로는 다음과 같은 요소를 포함합니다:

• 기능 호출 인터페이스 : AI가 실행 가능한 도구 목록
• 자원 접근 메커니즘 : 데이터 소스 연동 방법
• 템플릿 시스템 : 사전 정의된 대화 형식

1.2 핵심 구성 요소 분석

서버 진입점인 server.ts 파일을 살펴보면 다음과 같은 구조를 가집니다:

// 1. 서버 초기화 - 전체 MCP 시스템의 시작점
export function initializeServer(): MCPService {
  const service = new MCPService(
    {
      identifier: "mcp-server-chart",    // 서비스 식별자
      version: "0.8.x",                 // 버전 정보
    },
    {
      features: {
        extensions: {},                  // 지원 기능 범위
      },
    },
  );

핵심 학습 포인트 :

• MCP 서비스는 기능 범위를 명시적으로 선언해야 함
• 각 서비스는 고유한 식별자와 버전 정보를 갖음
• extensions: {}는 확장 기능을 나타내는 빈 객체

第二部分: 도구 시스템 아키텍처

2.1 도구 등록 메커니즘

function registerToolEndpoints(service: MCPService): void {
  // 도구 목록 요청 처리 - "사용 가능한 도구는 무엇인가요?"에 대한 응답
  service.setRequestHandler(ToolDiscoverySchema, async () => ({
    availableTools: getActiveExtensions().map((extension) => extension.id),
  }));

  // 도구 실행 요청 처리 - "특정 도구를 사용하려 합니다"에 대한 처리
  service.setRequestHandler(ToolExecutionSchema, async (request) => {
    return await executeExtension(request.params.id, request.params.payload);
  });
}

학습 포인트 :

1. ToolDiscoverySchema : 도구 발견 요청 처리 스키마
2. ToolExecutionSchema : 실제 도구 실행 로직
3. 표준적인 요청-응답 패턴 구조

2.2 도구 정의 구조

모든 도구는 일관된 형식으로 정의됩니다. 예를 들어 막대 차트 생성 도구는 다음과 같이 표현됩니다:

const toolDefinition = {
  id: "generate_bar_chart",            // 고유 도구 식별자
  purpose: "막대 차트 생성 기능...",    // AI에게 기능 목적 설명
  parameters: zodToJsonSchema(schema),  // 입력 파라미터 검증 스키마
};

핵심 개념 :

• id : 유일한 도구 식별 코드
• purpose : AI가 해당 도구를 선택할 수 있도록 하는 설명
• parameters : 입력값의 형식과 유효성 검증 규칙

第三部分: 타입 안전 및 데이터 검증

3.1 Zod 기반 검증 시스템