본문으로 건너뛰기

Questionnaire Data Query MCP Tool

1. 개요​

1.1 목적​

AI Agent가 사용자의 설문 응답 이력과 점수 추이를 조회하여 개인화된 치료 진행 상황을 평가하고 맞춤형 권장사항을 제공할 수 있도록 지원합니다.

1.2 Tool 정보​

  • Tool Name: questionnaire_data_query
  • Description: 사용자의 설문 응답 데이터 및 점수 추이를 조회합니다.
  • Source Domain: Questionnaire → Agent Data
  • Data Source: 사용자별 변환된 설문 응답 데이터
  • Data Processing: 원본 설문 데이터를 AI Agent가 이해하기 쉬운 형태로 변환

2. 기능 요구사항​

2.1 설문 응답 이력 조회​

2.1.1 초기 설문 조회 (roundNumber=1)​

  • 사용자가 처음 진행한(roundNumber=1) 모든 설문 유형의 응답 데이터를 조회할 수 있어야 한다.
  • 각 설문의 점수, 심각도 레벨, 완료일자를 제공해야 한다.
  • 치료 시작일로부터의 경과일을 포함해야 한다.

2.1.2 전체 설문 이력 조회​

  • 사용자가 현재까지 진행한 모든 회차의 모든 설문 응답 데이터를 조회할 수 있어야 한다.
  • 회차별 점수 변화 추이와 개선도를 제공해야 한다.
  • 각 설문의 심각도 레벨 변화를 포함해야 한다.

2.2 점수 분석 및 추이​

2.2.1 점수 변화 추이​

  • 각 설문 유형별 점수의 시계열 변화를 제공해야 한다.
  • 이전 회차 대비 개선도/악화도를 계산하여 제공해야 한다.
  • 통계적 유의미한 변화인지 판단할 수 있는 정보를 포함해야 한다.

2.2.2 증상 심각도 분석​

  • 각 설문의 심각도 레벨 변화를 추적해야 한다.
  • 정상 범위 진입 여부를 판단하여 제공해야 한다.
  • 치료 목표 달성도를 평가할 수 있는 지표를 제공해야 한다.

2.2.3 회차별 비교 분석​

  • 1회차(베이스라인) 대비 현재 상태를 비교해야 한다.
  • 각 회차 간 주요 변화점을 식별하여 제공해야 한다.
  • 개선이 있었던 영역과 지속적인 문제 영역을 구분해야 한다.

2.3 컨텍스트 정보 제공​

2.3.1 치료 단계별 매핑​

  • 현재 치료 단계(초기/중기/후기)에 따른 설문 결과 해석을 제공해야 한다.
  • 각 단계별 기대되는 개선 패턴과 비교해야 한다.
  • 단계별 치료 목표 달성도를 평가해야 한다.

2.3.2 관련 이벤트 연관성​

  • 설문 응답 시점의 중요한 치료 이벤트를 연결해야 한다.
  • 수면 패턴이나 학습 진도와의 상관관계를 제시해야 한다.
  • 외부 요인(스트레스, 생활 변화 등)의 영향을 고려해야 한다.

2.4 데이터 변환 및 품질 관리​

2.4.1 LLM 친화적 데이터 변환​

  • 원본 설문 응답 데이터를 AI Agent가 이해하기 쉬운 형태로 변환해야 한다.
  • 축약된 필드명을 의미 있는 자연어 필드명으로 변환하여 제공해야 한다.
  • 설문 점수와 함께 해석 정보(심각도, 개선도 등)를 포함해야 한다.

2.4.2 시간 정보 일관성​

  • 사용자별 가상 시간을 적용하여 일관된 시간 정보를 제공해야 한다.
  • 치료 시작일로부터의 정확한 경과일 계산을 포함해야 한다.
  • 설문 완료 시점과 현재 시점 간의 시간 차이를 고려해야 한다.

2.4.3 데이터 품질 보장​

  • 변환된 데이터에 대한 품질 검증을 수행해야 한다.
  • 데이터 무결성 및 일관성 검사 결과를 제공해야 한다.
  • 이상치나 데이터 품질 이슈 발견 시 적절한 경고를 제시해야 한다.

3. 입력 파라미터​

3.1 필수 파라미터​

  • user_id: 조회 대상 사용자 식별자
  • query_type: 조회 유형 (전체/특정설문/최신상태/추이분석)

3.2 선택적 파라미터​

  • questionnaire_types: 조회할 설문 유형 배열 (ISI, PHQ-9, GAD-7, PSS, DBAS-16, WIS)
  • round_numbers: 조회할 회차 번호 배열 (1, 2, 3, 4)
  • date_range: 조회 기간 (시작일, 종료일)
  • analysis_type: 분석 유형 (점수추이/심각도변화/개선도)
  • include_context: 컨텍스트 정보 포함 여부
  • comparison_baseline: 비교 기준점 (첫회차/이전회차/특정회차)

3.3 파라미터 검증​

  • user_id는 유효한 사용자여야 하며 데이터 접근 권한이 있어야 한다.
  • questionnaire_types는 지원되는 설문 유형만 허용한다.
  • date_range는 유효한 날짜 형식이어야 한다.
  • round_numbers는 1-4 범위 내의 값만 허용한다.

4. 출력 형식​

4.1 응답 구조 개요​

주요 데이터 섹션​

  • userContext: 사용자 치료 현황 및 기본 정보
  • questionnaireSummary: 설문 진행 상태 요약
  • questionnaireData: 설문별 점수, 응답, 추이 분석
  • insights: AI Agent를 위한 분석 인사이트 및 권장사항
  • metadata: 데이터 품질, 출처, 캐시 정보

핵심 제공 정보​

  1. 치료 진행 현황: 경과일, 치료 단계, 완료된 회차 수
  2. 설문 점수 추이: 회차별 점수 변화, 개선도, 심각도 레벨
  3. 개별 응답 내용: 각 문항별 응답 (자연어 형태로 변환)
  4. 분석 인사이트: 강점, 개선 영역, 개인화된 권장사항
  5. 임상적 의미: 통계적 유의성, 목표 달성도

4.2 데이터 특성​

  • 시계열 데이터: 회차별 변화 추이 분석 가능
  • 다차원 분석: 설문 유형별, 문제 영역별 세분화
  • 컨텍스트 정보: 치료 단계, 시간 정보, 이전 회차와의 연관성
  • 품질 보장: 데이터 변환 과정 및 검증 정보 포함

4.3 상세 스키마​

구체적인 필드 정의 및 데이터 타입은 구현 시점에 TransformedQuestionnaireData 인터페이스를 기준으로 결정

4.4 오류 처리​

표준 오류 응답 형식​

  • success: false
  • error: 오류 코드, 메시지, 상세 설명, 해결 방안

주요 오류 상황​

  • NO_DATA_FOUND: 설문 응답 데이터가 존재하지 않음
  • USER_ACCESS_ERROR: 사용자 데이터 접근 권한 문제
  • DATA_PROCESSING_ERROR: 데이터 변환 또는 처리 과정 오류
  • SYSTEM_ERROR: 시스템 내부 오류 (캐시, 저장소 등)

5. 사용 사례​

5.1 초기 설문 조회​

AI Agent: "사용자가 처음 진행한 모든 설문 결과를 조회하여 초기 상태를 파악하고 싶습니다."

MCP Call: questionnaire_data_query(
  user_id="user123",
  query_type="특정회차",
  round_numbers=[1]
)

활용: 사용자의 베이스라인 상태를 파악하여 치료 계획 수립 및 목표 설정

5.2 모든 설문 조회​

AI Agent: "사용자가 현재까지 진행한 모든 회차의 설문 결과를 조회하여 전체적인 변화를 확인하고 싶습니다."

MCP Call: questionnaire_data_query(
  user_id="user123",
  query_type="전체",
  include_context=true,
  analysis_type="점수추이"
)

활용: 전체 치료 과정에서의 설문 점수 변화를 분석하여 치료 효과 평가 및 향후 방향 수립

6. 기술 요구사항​

6.1 데이터 처리 아키텍처​

  • 이벤트 기반 데이터 변환: 설문 완료 시 자동으로 AI Agent 친화적 형태로 변환
  • 실시간 데이터 동기화: 설문 응답 완료 후 즉시 변환 데이터 갱신
  • 데이터 품질 보장: 변환 과정에서 무결성 검증 및 이상치 탐지

6.2 성능 요구사항​

  • 응답 시간: 평균 500ms, 최대 2초 이내
  • 캐싱 전략: 자주 조회되는 데이터에 대한 지능형 캐싱
  • 확장성: 동시 다중 AI Agent 요청 처리 지원

6.3 데이터 일관성​

  • 사용자별 가상 시간 적용: 일관된 시간 기준으로 데이터 제공
  • 회차별 연관성 유지: 이전 회차와의 비교 분석 지원
  • 버전 관리: 데이터 스키마 변경 시 하위 호환성 보장

7. 보안 및 권한​

7.1 데이터 접근 제어​

  • 사용자 본인의 데이터만 접근 가능
  • AI Agent 세션과 사용자 ID 바인딩 검증
  • 데이터 접근 로그 기록

7.2 민감 정보 보호​

  • 개별 설문 응답은 필요시에만 제공
  • 의료진 전용 해석 정보는 제외
  • GDPR 준수를 위한 데이터 마스킹 옵션

8. 모니터링 및 품질 관리​

8.1 시스템 모니터링​

  • 응답 시간 추적: MCP tool 호출별 성능 측정
  • 오류율 모니터링: 실패 요청 비율 및 오류 유형 분석
  • 사용 패턴 분석: AI Agent의 조회 패턴 및 빈도 추적

8.2 데이터 품질 보장​

  • 변환 품질 검증: 원본 데이터와 변환 데이터 간 일관성 확인
  • 무결성 검사: 필수 필드, 데이터 타입, 범위 유효성 검증
  • 이상치 탐지: 비정상적인 응답 패턴이나 점수 변화 감지

8.3 성능 최적화​

  • 캐시 효율성: 캐시 히트율 및 무효화 패턴 모니터링
  • 데이터 접근 최적화: 자주 조회되는 데이터 패턴 분석
  • 시스템 리소스 사용량: 메모리, CPU, 네트워크 사용량 추적

9. 향후 확장 계획​

9.1 고급 분석 기능​

  • 예측적 분석 (다음 회차 점수 예측)
  • 패턴 인식 (개선/악화 패턴 분류)
  • 개인화된 권장사항 생성

9.2 다차원 분석​

  • 설문-수면-학습 데이터 통합 분석
  • 외부 요인과의 상관관계 분석
  • 동일 질환 사용자군과의 비교 분석

10. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-06-28bok@weltcorp.com최초 작성