LearnAI - MCP 기반 개인화 학습 멘토 시스템

프로젝트 개요

LearnAI는 Model Control Protocol(MCP)을 활용하여 사용자의 관심 주제에 맞춤형 학습 커리큘럼을 제공하고, 일별 학습 계획을 관리하며, AI 멘토 역할을 수행하는 개인화 학습 지원 시스템입니다.

서비스 목표

• 사용자별 맞춤형 학습 커리큘럼 생성
• 일별 학습 계획 및 진도 관리
• 실시간 AI 멘토링 및 학습 상담
• 학습 기록 추적 및 분석

현재 개발 현황

완료된 기능

1. MCP Agent 시스템

   • MCP 서버와 LangGraph 에이전트 통합
   • 모듈화된 에이전트 관리 (agent.py)
   • 동적 서버 전환 기능

2. 웹 기반 채팅 인터페이스

   • FastAPI 기반 백엔드 API
   • HTML/CSS/JavaScript 프론트엔드
   • 실시간 채팅 기능

3. 기본 인프라

   • 로컬 및 네트워크 접근 지원
   • 템플릿 기반 UI 구조
   • 모듈화된 코드 아키텍처

기술 스택

Backend

• FastAPI: 웹 프레임워크 및 API 서버
• Python 3.11: 메인 개발 언어
• MCP (Model Control Protocol): AI 에이전트 통신
• LangGraph: AI 워크플로우 관리
• LangChain: AI 애플리케이션 프레임워크

Frontend

• HTML5/CSS3: 기본 웹 구조 및 스타일링
• Vanilla JavaScript: 클라이언트 사이드 로직
• Jinja2: 서버사이드 템플릿 엔진

AI/ML

• Ollama: 로컬 LLM 실행 환경
• midm-2.0-base-q8: 메인 언어 모델
• ChatOpenAI: OpenAI API 호환 인터페이스

LearnAI 학습 플로우

1단계: 사용자 초기 평가 (user_assessment.py)

사용자가 처음 LearnAI에 접속하면 AI 에이전트와의 대화를 통해 다음 정보를 수집합니다:

• 학습 목표: 무엇을 배우고 싶은지, 왜 배우려고 하는지
• 학습 제약조건: 시간, 예산, 환경적 제약
• 최종 목표: 구체적이고 측정 가능한 학습 목표 설정

2단계: 맞춤형 커리큘럼 생성 (generate_curriculum.py)

1단계에서 수집된 정보를 바탕으로 개인화된 학습 로드맵을 생성합니다.

3단계: 일별 학습 관리 및 멘토링 (evaluate_user.py)

학습 진행 상황을 모니터링하고 필요에 따라 계획을 조정합니다.

learnai/
├── main.py              # FastAPI 메인 애플리케이션
├── agent.py             # MCP 에이전트 모듈
├── utils.py             # 개발/디버깅 유틸리티
├── templates/
│   └── index.html       # 메인 채팅 UI
├── servers/             # MCP 서버들
│   ├── user_assessment.py    # 사용자 진단 서버 (현재: 날씨 데모)
│   ├── generate_curriculum.py # 커리큘럼 생성 서버 (개발 예정)
│   └── evaluate_user.py      # 사용자 평가 서버 (개발 예정)
└── agent.ipynb         # 프로토타이핑 노트북

설치 및 실행

1. 의존성 설치

pip install fastapi uvicorn jinja2 python-multipart aiofiles
pip install langchain langchain-openai langgraph mcp langchain-mcp-adapters

2. Ollama 서버 실행

ollama serve
ollama pull midm-2.0-base-q8  # 모델 다운로드 (필요시)

3. 애플리케이션 실행

python main.py

4. 접속

• 로컬: http://127.0.0.1:8000
• 네트워크: http://[표시된_IP]:8000

API 엔드포인트

• GET /: 메인 채팅 UI
• POST /chat: 채팅 메시지 처리
• GET /docs: API 문서 (Swagger UI)

개발 예정 기능

Phase 1: 데이터베이스 및 사용자 관리

• PostgreSQL/SQLite 데이터베이스 연동
• 사용자 인증 및 회원가입 시스템
• 세션 관리 및 대화 기록 저장
• 사용자 프로필 관리

Phase 2: 학습 커리큘럼 시스템

• 사용자 진단 MCP 서버 (user_assessment.py)
• 사용자 학습 수준 평가 MCP 서버 (evaluate_user.py)
• 맞춤형 커리큘럼 생성 MCP 서버 (generate_curriculum.py)
• 일별 학습 계획 생성 및 관리
• 학습 진도 추적 시스템

Phase 3: UI/UX 개선

• 반응형 웹 디자인
• 대시보드 및 학습 현황 시각화
• 모바일 친화적 인터페이스
• 다크모드 지원

Phase 4: 고급 기능

• 실시간 알림 시스템
• 학습 분석 및 리포트
• 소셜 학습 기능 (스터디 그룹)
• 외부 학습 자료 연동

Phase 5: 배포 및 운영

• Docker 컨테이너화
• 클라우드 배포 (AWS/GCP/Heroku)
• CI/CD 파이프라인 구축
• 모니터링 및 로깅 시스템
• 성능 최적화 및 스케일링

아키텍처 특징

모듈화된 설계

• MCP 서버별 독립적인 기능 구현
• 에이전트와 웹 서버의 명확한 분리
• 재사용 가능한 유틸리티 함수

확장 가능한 구조

• 새로운 MCP 서버 추가 용이
• 서버 타입별 동적 전환 지원
• 플러그인 방식의 기능 확장

개발 친화적 환경

• 핫 리로드 지원 (개발 모드)
• API 문서 자동 생성
• 프로토타이핑을 위한 Jupyter 노트북 지원

기여 방법

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

라이선스

MIT License

문의사항

프로젝트 관련 문의사항이나 버그 리포트는 이슈 트래커를 이용해 주세요.

---

현재 시스템 구성 및 흐름 (2025.09 기준)

전체 아키텍처 구조

LearnAI System Architecture
┌─────────────────────────────────────────────────────────────┐
│                    Web Interface (index.html)               │
│  사용자가 채팅 UI를 통해 메시지 입력                            │
└─────────────────────────┬───────────────────────────────────┘
                         │ POST /chat
┌─────────────────────────▼───────────────────────────────────┐
│                FastAPI Server (main.py)                    │
│  • 웹 서버 역할                                              │
│  • 채팅 API 엔드포인트 제공                                    │
│  • 템플릿 렌더링                                             │
└─────────────────────────┬───────────────────────────────────┘
                         │ MultiMCPAgent.chat()
┌─────────────────────────▼───────────────────────────────────┐
│               Multi-Agent System (agent.py)                │
│  • 여러 MCP 서버를 동시 관리                                  │
│  • 학습 의도 감지 및 라우팅                                    │
│  • 세션 상태 관리                                            │
│  • Assessment vs General 대화 분기                          │
└─────────────────┬─────────────────┬─────────────────────────┘
                 │                 │
        Assessment Mode      General Mode
                 │                 │
┌────────────────▼────────────────┐ │
│   User Assessment MCP Server    │ │
│   (user_assessment.py)          │ │
│                                 │ │
│  • Stateful 세션 관리           │ │
│  • LangGraph Multi-Agent        │ │
│  • 파일 기반 영구 저장           │ │
│                                 │ │
│  ┌─────────────────────────────┐ │ │
│  │    LangGraph Workflow       │ │ │
│  │  ┌─────────────────────────┐│ │ │
│  │  │  Extraction Agent       ││ │ │
│  │  │  • 정보 추출 (엄격)     ││ │ │
│  │  │  • UserInfoSchema 활용  ││ │ │
│  │  └─────────────────────────┘│ │ │
│  │            │                 │ │ │
│  │  ┌─────────▼─────────────────┐│ │ │
│  │  │  Response Agent          ││ │ │
│  │  │  • 완료도 체크           ││ │ │
│  │  │  • 질문 생성 or 완료     ││ │ │
│  │  │  • UI 정리 처리          ││ │ │
│  │  └─────────────────────────┘│ │ │
│  └─────────────────────────────┘ │ │
└─────────────────────────────────┘ │
                                   │
        ┌──────────────────────────▼──────────────────────────┐
        │          General Conversation                       │
        │  • LangChain ReAct Agent                           │
        │  • 일반 멘토링 대화                                   │
        │  • 다른 MCP 도구들 활용                              │
        └─────────────────────────────────────────────────────┘

세션 관리 시스템

Session Management Flow
┌──────────────────────────────────────────────────────────────┐
│                     Session Storage                         │
│                    sessions/ 폴더                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ abc123.json │  │ def456.json │  │ xyz789.json │  ...     │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│                                                             │
│  각 파일 구조:                                                │
│  {                                                          │
│    "messages": [...],    # 대화 기록                        │
│    "topic": "파이썬",     # 추출된 학습 주제                  │
│    "constraints": "초보자, 주 2시간",  # 제약 조건           │
│    "goal": "웹 개발",     # 구체적 목표                      │
│    "session_id": "abc123",                                  │
│    "completed": false,   # 평가 완료 여부                    │
│    "current_agent": "response"                              │
│  }                                                          │
└──────────────────────────────────────────────────────────────┘

사용자 평가 흐름 (Assessment Flow)

User Assessment Workflow
┌─────────────────────────────────────────────────────────────────┐
│  사용자 입력: "나 파이썬 배우고 싶어"                              │
└─────────────────────┬───────────────────────────────────────────┘
                     │
┌─────────────────────▼───────────────────────────────────────────┐
│  Step 1: 학습 의도 감지 (_should_use_assessment_tool)            │
│  • 키워드 매칭: "배우고 싶어", "공부하고 싶어", "학습" 등          │
│  • assessment_in_progress 상태 체크                             │
│  → Assessment Flow 진입                                        │
└─────────────────────┬───────────────────────────────────────────┘
                     │
┌─────────────────────▼───────────────────────────────────────────┐
│  Step 2: 세션 관리                                               │
│  • 기존 세션 복원 또는 새 세션 생성                               │
│  • sessions/세션ID.json 파일에서 로드                           │
│  • 대화 기록에 사용자 메시지 추가                                 │
└─────────────────────┬───────────────────────────────────────────┘
                     │
┌─────────────────────▼───────────────────────────────────────────┐
│  Step 3: LangGraph Workflow 실행                               │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Extraction Agent                                          │ │
│  │  • 엄격한 정보 추출 (명시적 언급만)                          │ │
│  │  • "파이썬 배우고 싶어" → topic: "파이썬"                   │ │
│  │  • constraints: "", goal: "" (빈 값 유지)                  │ │
│  │  • UserInfoSchema로 구조화                                 │ │
│  └─────────────────┬───────────────────────────────────────────┘ │
│                   │                                             │
│  ┌─────────────────▼───────────────────────────────────────────┐ │
│  │  Response Agent                                             │ │
│  │  • 완료도 체크: topic ✓, constraints ✗, goal ✗             │ │
│  │  • 미완료 → 다음 질문 생성                                   │ │
│  │  • "파이썬 학습 조건을 알려주세요!" 생성                      │ │
│  │  • 마크다운 제거, 세션 정보 숨김                              │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
                     │
┌─────────────────────▼───────────────────────────────────────────┐
│  Step 4: 응답 처리                                               │
│  • 세션 데이터를 sessions/세션ID.json에 저장                    │
│  • UI용 응답 정리 (_clean_response_for_ui)                      │
│  • 사용자에게 다음 질문 반환                                      │
└─────────────────────────────────────────────────────────────────┘

정보 추출 로직 (엄격한 추출)

Information Extraction Rules
┌─────────────────────────────────────────────────────────────────┐
│  입력: "나 파이썬 공부하고 싶어"                                   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Extraction Prompt (매우 엄격한 기준)                        │ │
│  │  • 사용자가 직접 말한 단어만 추출                             │ │
│  │  • 절대 추론, 유추, 해석 금지                                 │ │
│  │  • 없으면 빈 문자열로 유지                                    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                           │                                     │
│  ┌─────────────────────────▼───────────────────────────────────┐ │
│  │  UserInfoSchema 구조화 출력                                  │ │
│  │  topic: "파이썬"        ← 명시적으로 언급됨                   │ │
│  │  constraints: ""        ← 언급되지 않음                      │ │
│  │  goal: ""               ← 언급되지 않음                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  잘못된 추출 예시 (하지 않음):                                    │
│  topic: "파이썬 학습" ❌                                         │
│  constraints: "시간 정보 필요" ❌                                │
│  goal: "프로그래밍" ❌                                           │
└─────────────────────────────────────────────────────────────────┘

질문 생성 로직

Question Generation Logic
┌─────────────────────────────────────────────────────────────────┐
│  Current Profile State:                                         │
│  topic: "파이썬", constraints: "", goal: ""                     │
└─────────────────────────┬───────────────────────────────────────┘
                         │
            ┌─────────────▼─────────────┐
            │  _generate_next_question  │
            └─────────────┬─────────────┘
                         │
        ┌────────────────▼────────────────┐
        │  Missing Information Check      │
        └─┬─────────────┬─────────────────┘
         │             │
    topic 없음      constraints 없음
         │             │
  ┌──────▼──────┐ ┌────▼─────────────────────┐
  │  "어떤 분야를│ │ "파이썬 학습 조건을        │
  │  학습하고    │ │  알려주세요!"             │
  │  싶으신가요?"│ │ • 현재 수준               │
  │             │ │ • 시간 투자              │
  └─────────────┘ └──────────────────────────┘
                              │
                    ┌─────────▼─────────────────┐
                    │  goal 없음                │
                    │  "파이썬 학습 목표를       │
                    │   알려주세요!"            │
                    │  • 취업/이직              │
                    │  • 업무 활용              │
                    │  • 개인 프로젝트          │
                    │  • 취미/자기계발          │
                    └───────────────────────────┘

UI 응답 정리 과정

UI Response Cleaning Process
┌─────────────────────────────────────────────────────────────────┐
│  Raw Response:                                                  │
│  🚀 **파이썬 학습 목표를 알려주세요!**                           │
│                                                                 │
│  **어떤 목적으로 파이썬을(를) 배우시나요?**                      │
│  - 취업이나 이직을 위해서                                        │
│  - 현재 업무에 활용하려고                                        │
│                                                                 │
│  _Session: abc123 | Status: In Progress_                       │
└─────────────────────────┬───────────────────────────────────────┘
                         │ _clean_response_for_ui()
┌─────────────────────────▼───────────────────────────────────────┐
│  Cleaned Response:                                              │
│  🚀 파이썬 학습 목표를 알려주세요!                               │
│                                                                 │
│  어떤 목적으로 파이썬을(를) 배우시나요?                          │
│  • 취업이나 이직을 위해서                                        │
│  • 현재 업무에 활용하려고                                        │
│                                                                 │
│  구체적인 목표를 알면 더 맞춤형 로드맵을 제시할 수 있어요!        │
└─────────────────────────────────────────────────────────────────┘
│
├─ ** 마크다운 굵은글씨 제거
├─ - 리스트를 • 불릿으로 변경
├─ 세션 정보 완전 제거
└─ 여러 줄바꿈 정리

완료 상태 판단 로직

Completion Status Check
┌─────────────────────────────────────────────────────────────────┐
│  _should_continue() 함수                                        │
│                                                                 │
│  topic_complete = bool(state.get("topic"))      ← True         │
│  constraints_complete = bool(state.get("constraints")) ← False │
│  goal_complete = bool(state.get("goal"))        ← False        │
│                                                                 │
│  if all three are True:                                        │
│    return "complete" → 완료 메시지 생성                         │
│  else:                                                          │
│    return "continue" → 다음 질문 생성                           │
└─────────────────────────────────────────────────────────────────┘

실제 사용 흐름 예시

실제 대화 흐름
┌─────────────────────────────────────────────────────────────────┐
│  User: "나 파이썬 공부하고 싶어"                                 │
│  → Assessment: topic="파이썬", constraints="", goal=""         │
│  → AI: "파이썬 학습 조건을 알려주세요! 현재 수준과 시간..."       │
│                                                                 │
│  User: "완전 초보자고 주 2시간 가능해"                           │
│  → Assessment: topic="파이썬", constraints="완전 초보자, 주 2시간", goal="" │
│  → AI: "파이썬 학습 목표를 알려주세요! 취업, 업무활용..."        │
│                                                                 │
│  User: "취업 준비하려고"                                         │
│  → Assessment: topic="파이썬", constraints="완전 초보자, 주 2시간", goal="취업" │
│  → AI: "🎯 학습 프로필 분석 완료! [완료 메시지]"                 │
│                                                                 │
│  → assessment_in_progress = False 전환                         │
│  → 이후 일반 멘토링 모드로 전환                                  │
└─────────────────────────────────────────────────────────────────┘

이 구조를 통해 Stateful Multi-Agent Assessment System이 사용자의 학습 프로필을 단계적으로 수집하고, 완료 후에는 일반 멘토링 모드로 자연스럽게 전환됩니다.