MCP Tools 개요

소개

MCP(Model Context Protocol) Tools는 QA Agent의 핵심 기능으로, 자동화된 테스트와 모니터링을 위한 다양한 도구를 제공합니다. 각 도구는 특정 목적에 최적화되어 있으며, 조합하여 사용할 때 더욱 강력한 분석이 가능합니다.

도구 카테고리

1. 데이터 조회 도구

사용자 데이터와 애플리케이션 상태를 조회하는 도구들입니다.

도구명	설명	주요 용도
query-mobile-logs	모바일 앱 로그 조회	앱 크래시 분석, 사용자 문제 추적
questionnaire_data_query	설문 데이터 조회	사용자 진행도 확인, 점수 추이 분석
sleep_log_data_query	수면 로그 조회	수면 패턴 분석, 치료 효과 측정

2. 시스템 분석 도구

시스템 상태와 에러를 분석하는 도구들입니다.

도구명	설명	주요 용도
query-recent-errors	최근 에러 조회	서비스 안정성 모니터링
analyze-error-patterns	에러 패턴 분석	반복 문제 식별, 근본 원인 분석
query-logs	시스템 로그 조회	상세 로그 분석, 성능 진단

3. 시간 관리 도구

시간 조회, 가상 시간 설정, TimeMachine 관리 등을 지원하는 도구들입니다.

도구명	설명	주요 용도
get-current-time	현재 시각 조회	타임존 변환, 시간 동기화, 로그 분석
get-user-virtual-time	사용자 가상 시간 조회	사용자 시간 상태 확인, 치료 진행도 추적
change-user-day-index	사용자 가상 시간 변경	치료 일차 테스트, 시나리오 검증
get-user-timemachine-status	TimeMachine 상태 조회	TimeMachine 활성화 여부 확인
enable-user-timemachine	TimeMachine 활성화	테스트 환경 구성, 시나리오 테스트
disable-user-timemachine	TimeMachine 비활성화	테스트 완료 후 원복

4. 유틸리티 도구

테스트와 개발을 지원하는 유틸리티 도구들입니다.

도구명	설명	주요 용도
create-access-code	액세스 코드 생성	사용자 초대, 온보딩, 코드 관리

도구 선택 가이드

목적별 도구 선택

모바일 앱 품질 검증

1. query-mobile-logs - 에러 로그 수집
2. analyze-error-patterns - 패턴 분석
3. questionnaire_data_query - 영향받은 사용자 확인

사용자 경험 분석

1. questionnaire_data_query - 설문 응답 확인
2. sleep_log_data_query - 수면 데이터 분석
3. query-mobile-logs - 사용자별 로그 추적

시스템 모니터링

1. query-recent-errors - 실시간 에러 감지
2. query-logs - 상세 로그 분석
3. analyze-error-patterns - 트렌드 파악

시간 관련 시나리오 테스트

1. enable-user-timemachine - TimeMachine 활성화
2. change-user-day-index - 특정 치료 일차로 이동
3. get-user-virtual-time - 변경된 시간 확인
4. questionnaire_data_query - 해당 시점 설문 확인
5. sleep_log_data_query - 수면 데이터 검증
6. disable-user-timemachine - 테스트 완료 후 원복

사용 규칙

1. 파라미터 검증

• 모든 필수 파라미터는 반드시 제공해야 합니다
• 시간 파라미터는 ISO 8601 형식을 따라야 합니다
• 배열 파라미터는 올바른 값만 포함해야 합니다

2. 응답 처리

• isError 필드를 확인하여 에러 처리
• 대량의 데이터는 페이지네이션 고려
• 응답 데이터의 구조를 이해하고 파싱

3. 성능 최적화

• 적절한 시간 범위 설정
• 필요한 필드만 요청
• 캐싱 전략 수립

조합 사용 예시

예시 1: 종합적인 사용자 문제 분석

// 1단계: 사용자의 설문 데이터 확인
const questionnaireData = await mcpTool.execute({
  tool: "questionnaire_data_query",
  arguments: {
    userId: "user-12345",
    includeDetails: true
  }
});

// 2단계: 수면 로그 확인
const sleepLogs = await mcpTool.execute({
  tool: "sleep_log_data_query",
  arguments: {
    userId: "user-12345",
    limit: 30
  }
});

// 3단계: 관련 모바일 로그 조회
const mobileLogs = await mcpTool.execute({
  tool: "query-mobile-logs",
  arguments: {
    userId: "user-12345",
    startTime: "2024-01-01T00:00:00.000Z",
    endTime: "2024-01-15T23:59:59.999Z",
    logLevel: ["WARNING", "ERROR"]
  }
});

예시 2: 시스템 안정성 진단

// 1단계: 최근 에러 확인
const recentErrors = await mcpTool.execute({
  tool: "query-recent-errors",
  arguments: {
    hours: 24,
    limit: 100
  }
});

// 2단계: 에러 패턴 분석
const errorPatterns = await mcpTool.execute({
  tool: "analyze-error-patterns",
  arguments: {
    startTime: "2024-01-01T00:00:00.000Z",
    endTime: "2024-01-15T23:59:59.999Z",
    minOccurrences: 5
  }
});

// 3단계: 상세 로그 조회
const detailedLogs = await mcpTool.execute({
  tool: "query-logs",
  arguments: {
    startTime: "2024-01-15T00:00:00.000Z",
    endTime: "2024-01-15T23:59:59.999Z",
    severity: ["ERROR", "CRITICAL"],
    limit: 500
  }
});

에러 처리

공통 에러 코드

코드	설명	대응 방법
INVALID_PARAMETERS	잘못된 파라미터	파라미터 형식 확인
UNAUTHORIZED	권한 없음	인증 토큰 확인
RATE_LIMIT_EXCEEDED	요청 한도 초과	잠시 후 재시도
INTERNAL_ERROR	내부 오류	지원팀 문의

에러 처리 예시

try {
  const result = await mcpTool.execute({
    tool: "query-mobile-logs",
    arguments: { /* ... */ }
  });
  
  if (result.isError) {
    console.error("Tool execution failed:", result.content[0].text);
    // 에러별 처리 로직
  } else {
    // 성공 처리
  }
} catch (error) {
  console.error("Unexpected error:", error);
  // 예외 처리
}

모범 사례

1. 도구 선택

   • 목적에 맞는 적절한 도구 선택
   • 필요시 여러 도구 조합 사용
   • 성능을 고려한 실행 순서 결정

2. 데이터 관리

   • 조회한 데이터의 적절한 보관
   • 민감 정보 보호
   • 캐싱 전략 수립

3. 모니터링

   • 도구 실행 결과 추적
   • 성능 메트릭 수집
   • 이상 패턴 감지

다음 단계

• 각 도구의 상세 문서를 확인하여 구체적인 사용법을 익히세요
• QA 규약을 참고하여 표준을 준수하세요
• 에러 처리 가이드를 확인하세요