get-user-state MCP Tool

개요

get-user-state MCP Tool은 사용자의 현재 상태를 조회하는 도구입니다. 사용자의 사이클 정보, 날짜 매핑, 정지 이력 등 세부적인 상태 정보를 제공하여 사용자 관리 및 문제 해결에 활용할 수 있습니다.

이 문서에서는 다음 사용 방법을 다룹니다:

• JSON 형식: 구조화된 데이터로 정확한 제어가 필요한 경우
• LLM AI Chat: 자연어로 간편하게 사용하고 싶은 경우

두 방법 모두 같은 결과를 제공하며, 사용자의 선호도와 상황에 따라 선택할 수 있습니다.

도구 정보

• 이름: get_user_state
• 설명: 사용자의 현재 상태, 사이클 정보, 날짜 매핑 등 종합적인 상태 정보 조회
• 카테고리: 사용자 관리 도구

파라미터

필수 파라미터

파라미터	타입	설명	제약사항
userId	string	조회할 사용자의 ID	UUID 형식 (예: a1b2c3d4-e5f6-7890-abcd-ef1234567890)

UUID 형식 검증

userId는 다음 형식을 따라야 합니다:

• 8-4-4-4-12 자리 16진수
• 소문자 사용 (a-f, 0-9)
• 예시: a1b2c3d4-e5f6-7890-abcd-ef1234567890

LLM AI Chat에서의 사용법

LLM AI Chat에서는 자연어로 사용자 상태를 조회할 수 있습니다.

기본 사용자 상태 조회

사용자 ID a1b2c3d4-e5f6-7890-abcd-ef1234567890의 상태를 조회해주세요.

또는

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 현재 상태 정보를 알려주세요.

특정 정보 중심 조회

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 사이클 정보를 확인해주세요.

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 현재 날짜 매핑을 보여주세요.

문제 해결 목적 조회

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890에게 문제가 있는지 상태를 확인해주세요.

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 정지 이력을 조회해주세요.

타임머신 상태 확인

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 타임머신 활성화 상태를 확인해주세요.

자연어 응답 예시

요청: "사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 상태를 조회해주세요."

응답: "사용자 상태 정보를 조회했습니다.

📋 기본 정보:

• 사용자 ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
• 사이클 ID: cycle-789
• 플랜 ID: plan-123
• 언어: ko
• 타임존: Asia/Seoul

📅 사이클 정보:

• 시작 날짜: 2024-01-15
• 현재 날짜 인덱스: 25
• 현재 사용자 시간: 2024-02-08 09:30:00
• 정지 상태: 아니오
• 타임머신 활성화: 예

📊 최근 날짜 매핑 (최근 10일):

• 16일차: 2024-01-30
• 17일차: 2024-01-31
• 18일차: 2024-02-01
• 19일차: 2024-02-02
• 20일차: 2024-02-03
• 21일차: 2024-02-04
• 22일차: 2024-02-05
• 23일차: 2024-02-06
• 24일차: 2024-02-07
• 25일차: 2024-02-08

사용자는 현재 정상적으로 사이클을 진행하고 있으며, 타임머신 기능이 활성화되어 있습니다."

사용 예시 (JSON 형식)

기본 사용자 상태 조회

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

응답 형식

성공 응답 예시

{
  "content": [
    {
      "type": "text",
      "text": "User State Information:\n\n📋 Basic Information:\n  User ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n  Cycle ID: cycle-789\n  Plan ID: plan-123\n  Language: ko\n  Timezone: Asia/Seoul\n\n📅 Cycle Information:\n  Started Date: 2024-01-15\n  Current Day Index: 25\n  Current User Time: 2024-02-08 09:30:00\n  Is Suspended: No\n  Time Machine Activated: Yes\n\n📊 Day Mappings (Recent 10 days):\n  Day 16: 2024-01-30\n  Day 17: 2024-01-31\n  Day 18: 2024-02-01\n  Day 19: 2024-02-02\n  Day 20: 2024-02-03\n  Day 21: 2024-02-04\n  Day 22: 2024-02-05\n  Day 23: 2024-02-06\n  Day 24: 2024-02-07\n  Day 25: 2024-02-08\n\n"
    }
  ]
}

응답 데이터 구조

필드	설명
userId	사용자 ID
userCycleId	사용자 사이클 ID
planId	플랜 ID
language	사용자 언어 설정
timezoneId	타임존 ID
startedDate	사이클 시작 날짜
currentDayIndex	현재 날짜 인덱스
currentUserTime	현재 사용자 시간
isSuspended	정지 상태 여부
isTimeMachineActivated	타임머신 활성화 여부
dayMappings	날짜 매핑 정보 (최근 10일)
suspensions	정지 이력
suspensionPeriods	정지 기간 정보

사용 시나리오

시나리오 1: 사용자 문제 해결

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890가 앱이 이상하게 동작한다고 신고했습니다. 
사용자 상태를 확인해주세요.

JSON 형식:

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

시나리오 2: 사이클 진행 상태 확인

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 치료 사이클이 정상적으로 진행되고 있는지 확인해주세요.

JSON 형식:

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

시나리오 3: 타임머신 상태 확인

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 타임머신 기능이 활성화되어 있는지 확인해주세요.

JSON 형식:

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

시나리오 4: 정지 이력 조회

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 정지 이력을 조회해서 
과거에 문제가 있었는지 확인해주세요.

JSON 형식:

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

시나리오 5: 날짜 매핑 확인

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 날짜 진행이 올바른지 
날짜 매핑을 확인해주세요.

JSON 형식:

{
  "tool": "get_user_state",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

문제 해결

일반적인 문제

1. UUID 형식 오류: 잘못된 userId 형식 입력
2. 사용자 미존재: 존재하지 않는 사용자 ID
3. 권한 부족: 사용자 상태 조회 권한 없음
4. 사이클 없음: 활성 사이클이 없는 사용자

에러 응답 예시

UUID 형식 오류:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid userId format. Must be a valid UUID\nUser ID: invalid-user-id"
    }
  ],
  "isError": true
}

사용자 미존재:

{
  "content": [
    {
      "type": "text",
      "text": "Error getting user state:\n\nStatus Code: 404\nError Code: USER_NOT_FOUND\nMessage: User not found or no active cycle\nUser ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "isError": true
}

권한 부족:

{
  "content": [
    {
      "type": "text",
      "text": "Error getting user state:\n\nStatus Code: 403\nError Code: ACCESS_DENIED\nMessage: Access denied: Insufficient permissions\nUser ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "isError": true
}

문제 해결 가이드

1. UUID 형식 확인: 올바른 UUID 형식인지 확인
2. 사용자 존재 확인: 사용자가 시스템에 등록되어 있는지 확인
3. 권한 확인: 사용자 상태 조회 권한이 있는지 확인
4. 사이클 상태 확인: 사용자에게 활성 사이클이 있는지 확인

상태 정보 해석

사이클 상태

• currentDayIndex: 사용자가 현재 진행 중인 날짜 인덱스
• isSuspended: 사용자 사이클이 정지된 상태인지 여부
• suspensions: 과거 정지 이력 (시작일, 종료일, 기간)

타임머신 상태

• isTimeMachineActivated: 타임머신 기능 활성화 여부
• 활성화된 경우 테스트 목적으로 시간 조작 가능

날짜 매핑

• dayMappings: 날짜 인덱스와 실제 날짜의 매핑 정보
• 최근 10일의 매핑 정보를 제공
• 날짜 진행이 올바른지 확인 가능

모니터링 및 추적

1. 사용자 상태 변경 추적

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890의 상태 변경 이력을 조회해주세요.

JSON 형식:

{
  "tool": "query_logs",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "startTime": "2024-01-01T00:00:00.000Z",
    "endTime": "2024-01-31T23:59:59.999Z",
    "severity": ["INFO", "WARNING", "ERROR"]
  }
}

2. 오류 발생 확인

LLM AI Chat:

사용자 a1b2c3d4-e5f6-7890-abcd-ef1234567890와 관련된 최근 오류를 확인해주세요.

JSON 형식:

{
  "tool": "query_recent_errors",
  "arguments": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hours": 24
  }
}

성능 고려사항

1. 인증: Service Account 토큰 사용으로 보안 강화
2. 권한 확인: 적절한 권한 검증 수행
3. 데이터 최적화: 필요한 데이터만 반환하여 성능 최적화
4. 에러 처리: 명확한 에러 메시지 제공

보안 및 프라이버시

• Service Account 토큰 인증 필요
• 사용자 개인정보 보호 준수
• 권한이 있는 사용자만 조회 가능
• 민감한 정보는 적절히 마스킹 처리
• 로그 기록을 통한 접근 추적

관련 도구

• get-user-virtual-time: 사용자 가상 시간 조회
• change-user-day-index: 사용자 날짜 인덱스 변경
• get-user-timemachine-status: 타임머신 상태 확인
• enable-user-timemachine: 타임머신 활성화
• disable-user-timemachine: 타임머신 비활성화
• query-logs: 사용자 관련 로그 조회
• query-recent-errors: 최근 오류 조회

관련 문서

• MCP Tools 개요
• MCP Tools 가이드
• get-user-virtual-time
• change-user-day-index
• get-user-timemachine-status
• enable-user-timemachine
• disable-user-timemachine
• 에러 처리 가이드
• MCP Server 설정