본문으로 건너뛰기

Agent Data 도메인 MCP 인터페이스 요구사항

1. 개요​

1.1 목적​

Agent Data 도메인은 AI Agent가 Model Context Protocol(MCP)을 통해 사용자의 개인화된 치료 컨텍스트 데이터에 접근할 수 있도록 지원합니다. 이를 통해 AI Agent는 사용자의 수면 패턴, 설문 응답 이력, 학습 진도, 약물 정보 등을 종합적으로 분석하여 개인화된 치료 서비스를 제공할 수 있습니다.

1.2 MCP 역할​

  • 데이터 제공자(Data Provider): Firestore에 저장된 가공된 사용자 데이터를 MCP 도구로 노출
  • 컨텍스트 브리지(Context Bridge): 여러 도메인의 데이터를 AI Agent가 이해하기 쉬운 형태로 통합 제공
  • 개인화 지원: 사용자별 맞춤형 인사이트 및 추천을 위한 데이터 기반 제공

1.3 구현 위치​

  • MCP Server: apps/dta-wide-mcp
  • Data Source: Agent Data 도메인의 Firestore 컬렉션
  • API Endpoint: Agent Data 도메인의 기존 조회 API 활용

2. 아키텍처 개요​

2.1 MCP 통신 흐름​

AI Agent ↔ MCP Server (dta-wide-mcp) ↔ Agent Data API ↔ Firestore

2.2 데이터 흐름​

  1. 수집: 각 도메인 이벤트 → Agent Data 도메인
  2. 변환: 원본 데이터 → LLM 친화적 JSON 구조
  3. 저장: 변환된 데이터 → Firestore 컬렉션
  4. 제공: MCP Tool → AI Agent

2.3 보안 및 인증​

  • MCP Server는 Agent Data API 호출 시 적절한 인증 토큰 사용
  • 사용자별 데이터 격리 및 접근 권한 검증
  • 민감한 건강 정보에 대한 GDPR 준수

3. 공통 기능 요구사항​

3.1 인증 및 권한 관리​

3.1.1 사용자 컨텍스트 식별​

  • MCP Tool은 현재 대화 중인 사용자를 식별할 수 있어야 한다.
  • 사용자 식별은 안전한 방식으로 MCP 세션에 바인딩되어야 한다.
  • 잘못된 사용자 데이터 접근을 방지하는 검증 로직이 필요하다.

3.1.2 데이터 접근 권한​

  • MCP Tool은 해당 사용자의 데이터에만 접근할 수 있어야 한다.
  • 데이터 접근 로그를 기록하여 감사 추적이 가능해야 한다.
  • 사용자가 데이터 접근을 거부한 경우 적절히 처리해야 한다.

3.2 성능 요구사항​

3.2.1 응답 시간​

  • MCP Tool 호출 응답 시간은 평균 500ms, 최대 2초를 초과하지 않아야 한다.
  • 대용량 데이터 조회 시 페이징 및 필터링을 지원해야 한다.
  • 자주 요청되는 데이터는 캐싱을 통해 성능을 최적화해야 한다.

3.2.2 동시성​

  • 여러 AI Agent가 동시에 MCP Tool을 호출할 수 있어야 한다.
  • 동시 호출 시에도 데이터 일관성을 보장해야 한다.

3.3 오류 처리​

3.3.1 예외 상황 처리​

  • 사용자 데이터가 없는 경우 적절한 메시지를 반환해야 한다.
  • API 호출 실패 시 재시도 메커니즘을 구현해야 한다.
  • 네트워크 오류, 타임아웃 등에 대한 견고한 처리가 필요하다.

3.3.2 에러 메시지​

  • AI Agent가 이해하기 쉬운 명확한 에러 메시지를 제공해야 한다.
  • 에러 유형별로 적절한 대응 방안을 제시해야 한다.

3.4 데이터 형식​

3.4.1 LLM 친화적 구조​

  • 모든 데이터는 LLM이 이해하기 쉬운 명확한 필드명을 사용해야 한다.
  • 축약된 컬럼명이나 코드는 의미 있는 이름으로 변환되어야 한다.
  • 메타데이터와 컨텍스트 정보를 포함해야 한다.

3.4.2 일관된 스키마​

  • 모든 MCP Tool은 일관된 응답 구조를 가져야 한다.
  • 날짜/시간 형식, 단위, 범위 등이 표준화되어야 한다.
  • 버전 관리가 가능한 스키마 구조를 유지해야 한다.

4. MCP Tool 분류​

4.1 Core Data Tools​

사용자의 핵심 치료 데이터를 제공하는 도구들

4.1.1 Questionnaire Data Query​

  • 목적: 설문 응답 이력 및 점수 추이 조회
  • 주요 기능: 설문 점수 변화, 증상 심각도 분석, 회차별 비교
  • 사용 사례: 개인화된 치료 진행 상황 평가, 증상 개선도 분석

4.1.2 Sleep Data Query​

  • 목적: 수면 패턴 및 품질 데이터 조회
  • 주요 기능: 수면 효율성, 수면 시간 패턴, 수면 품질 추이 분석
  • 사용 사례: 수면 개선 효과 확인, 개인화된 수면 권장사항 제공

4.1.3 Learning Progress Query​

  • 목적: 학습 진도 및 이해도 조회
  • 주요 기능: 학습 완료 레슨 목록, 숙지 개념, 학습 패턴 분석
  • 사용 사례: 개인화된 학습 추천, 복습 필요 항목 식별

4.1.4 Medication Data Query​

  • 목적: 약물 프로필 및 상호작용 정보 조회
  • 주요 기능: 약물 목록, 상호작용 경고, 감량 계획, 추천 이력
  • 사용 사례: 약물 관리 지원, 안전성 확인, 감량 계획 모니터링

4.1.5 Condition Data Query​

  • 목적: 증상 리포트 및 건강 상태 추적 데이터 조회
  • 주요 기능: 증상 이력, 경보 상태, 추세 분석, 수면 인식 신념 조회
  • 사용 사례: 증상 패턴 분석, 건강 상태 평가, 인지 행동 치료 지원
  • 특이사항: 신체적/정신적 상태 통합 조회, 수면/약물과의 상관관계 분석 제공

4.2 Insight & Analytics Tools​

통합 분석 및 인사이트를 제공하는 도구들

4.2.1 User Profile Summary​

  • 목적: 사용자 전반적인 치료 상태 요약
  • 주요 기능: 치료 진행도, 주요 개선 영역, 현재 단계 분석
  • 사용 사례: 초기 컨텍스트 파악, 치료 방향성 설정

4.2.2 Integrated Insights Query​

  • 목적: 모든 도메인 데이터 통합 분석
  • 주요 기능: 상관관계 분석, 패턴 인식, 예측적 인사이트
  • 사용 사례: 종합적 치료 효과 평가, 개인화된 권장사항 생성

4.3 Temporal Analytics Tools​

시계열 분석 및 트렌드를 제공하는 도구들

4.3.1 Daily Progress Query​

  • 목적: 일별 진행 상황 및 패턴 조회
  • 주요 기능: 일일 활동 요약, 단기 트렌드, 이상 패턴 감지
  • 사용 사례: 일일 체크인, 즉각적인 피드백 제공

4.3.2 Weekly Trend Analysis​

  • 목적: 주간 단위 개선 추이 분석
  • 주요 기능: 주간 평균 변화, 목표 달성도, 패턴 변화
  • 사용 사례: 주간 리뷰, 중기 계획 조정

5. 기술 요구사항​

5.1 MCP 프로토콜 준수​

  • MCP 1.0 표준 스펙을 완전히 준수해야 한다.
  • Tool discovery, tool calling, result handling을 지원해야 한다.
  • MCP 세션 관리 및 상태 유지를 구현해야 한다.

5.2 API 통합​

  • Agent Data 도메인의 기존 조회 API를 활용해야 한다.
  • API 버전 관리 및 하위 호환성을 고려해야 한다.
  • API 호출 실패 시 graceful degradation을 구현해야 한다.

5.3 캐싱 전략​

  • 자주 조회되는 데이터는 Redis 캐시를 활용해야 한다.
  • 캐시 무효화 정책을 명확히 정의해야 한다.
  • 실시간성이 중요한 데이터와 배치성 데이터를 구분해야 한다.

5.4 로깅 및 모니터링​

  • 모든 MCP Tool 호출을 로깅해야 한다.
  • 성능 메트릭 및 오류율을 모니터링해야 한다.
  • 사용 패턴 분석을 위한 데이터를 수집해야 한다.

6. 보안 요구사항​

6.1 데이터 보호​

  • 전송 중 데이터 암호화 (TLS 1.3)
  • 민감한 건강 정보에 대한 추가 보안 조치
  • 데이터 마스킹 및 익명화 옵션

6.2 접근 제어​

  • 역할 기반 접근 제어 (RBAC)
  • API 호출 제한 (Rate Limiting)
  • 감사 로그 기록 및 보관

6.3 GDPR 준수​

  • 사용자 동의 관리
  • 데이터 삭제 요청 처리
  • 데이터 이동성 지원

7. 운영 요구사항​

7.1 배포 및 업데이트​

  • 무중단 배포 지원
  • A/B 테스트 가능한 구조
  • 롤백 메커니즘 구현

7.2 확장성​

  • 수평적 확장 지원
  • 로드 밸런싱 구성
  • 서비스 메시 통합

7.3 장애 대응​

  • Circuit Breaker 패턴 적용
  • Health Check 엔드포인트 제공
  • Graceful Shutdown 구현

8. 개발 로드맵​

8.1 Phase 1: Core Tools (MVP)​

  • Questionnaire Data Query
  • Sleep Data Query
  • User Profile Summary

8.2 Phase 2: Advanced Analytics​

  • Learning Progress Query
  • Medication Data Query
  • Integrated Insights Query
  • Daily Progress Query

8.3 Phase 3: Temporal Analytics​

  • Weekly Trend Analysis
  • 예측적 분석 도구
  • 개인화 추천 엔진

9. 성공 지표​

9.1 기술적 지표​

  • MCP Tool 응답 시간 < 500ms (평균)
  • API 가용성 > 99.9%
  • 오류율 < 0.1%

9.2 비즈니스 지표​

  • AI Agent 개인화 정확도 향상
  • 사용자 치료 효과 개선
  • 데이터 활용도 증가

10. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-06-28bok@weltcorp.com최초 작성
0.2.02025-11-10bok@weltcorp.comMedication Data Query MCP 도구 추가 (약물 프로필, 상호작용 경고, 감량 계획 조회)