┌─────────────────┐
│  MCP Client     │  (Cursor AI, Claude Desktop 등)
│  (Cursor AI)    │
└────────┬────────┘
         │ JSON-RPC (stdio)
         │
┌────────▼─────────────────────────────────────┐
│         Persona MCP Server                   │
│  ┌──────────────────────────────────────┐   │
│  │  FastMCP Framework                   │   │
│  │  - Tool Registration                 │   │
│  │  - Request/Response Handling         │   │
│  └──────────┬───────────────────────────┘   │
│             │                                │
│  ┌──────────▼───────────────────────────┐   │
│  │  Tool Implementations                │   │
│  │  - FGI Tools (fgi_tools.py)         │   │
│  │  - Predict (predict.py)             │   │
│  │  - Insights (insights.py)           │   │
│  │  - Freshness (freshness.py)         │   │
│  │  - Query (query.py)                 │   │
│  │  - Sample Data (sample_data.py)     │   │
│  └──────────┬───────────────────────────┘   │
│             │                                │
│  ┌──────────▼───────────────────────────┐   │
│  │  Database Layer (SQLAlchemy)         │   │
│  │  - Persona Model                     │   │
│  │  - FGISurvey Model                   │   │
│  │  - FGIResponse Model                 │   │
│  └──────────┬───────────────────────────┘   │
└─────────────┼────────────────────────────────┘
              │
┌─────────────▼─────────────┐
│   SQLite Database         │
│   (data/fgi.db)           │
└───────────────────────────┘
              │
┌─────────────▼─────────────┐
│   Groq LLM API            │
│   (AI 분석 및 생성)        │
└───────────────────────────┘

# 기본 프로필 질문 목록 조회
questions = get_basic_profile_questions_tool()

# 모든 페르소나의 기본 프로필 확인
check_basic_profile_tool()

# 특정 페르소나의 기본 프로필 확인
check_basic_profile_tool(persona_id="persona_123")

# 페르소나의 기본 정보 설정
update_basic_profile_tool(
    persona_id="persona_123",
    profile_data={
        "age_range": "20대 후반",        # 질문 목록의 옵션 중 하나
        "gender": "남성",                 # 질문 목록의 옵션 중 하나
        "location": "서울",               # 질문 목록의 옵션 중 하나
        "occupation_category": "IT/개발", # 질문 목록의 옵션 중 하나
        "income_range": "300-500만원"     # 선택사항, 질문 목록의 옵션 중 하나
    }
)

# 설문 응답을 기반으로 페르소나 자동 생성
predict_persona_tool(
    responses=[
        {"question_id": "q1", "answer": "저는 기술에 관심이 많아요..."},
        {"question_id": "q2", "answer": "주말에는 코딩을 하거나..."}
    ],
    user_id="user_123"
)

# 카테고리별 설문 시작
create_fgi_survey_tool(
    category="technology",  # technology, lifestyle, culture, fashion, food, general
    persona_id="persona_123"  # 선택사항
)

# 이전 답변을 분석하여 다음 질문 생성
generate_next_question_tool(
    survey_id="survey_123",
    previous_qa=[
        {"question": "요즘 기술 분야에서 가장 관심있는 주제는?", "answer": "AI와 머신러닝에 관심이 많아요"},
        {"question": "어떤 방식으로 학습하시나요?", "answer": "온라인 강의와 프로젝트를 병행해요"}
    ],
    category="technology",
    max_questions=10  # 선택사항: 최대 질문 수 제한
)

# 설문 응답 제출 및 신선도 업데이트
submit_fgi_response_tool(
    persona_id="persona_123",
    survey_id="survey_123",
    responses=[
        {"question_id": "q1", "answer": "답변 내용"},
        {"question_id": "q2", "answer": "답변 내용"}
    ]
)

# 신선도 확인
check_freshness_tool(persona_id="persona_123")

# 특정 제품/주제에 대한 선호도 분석
analyze_preference_tool(
    query="스티커 디자인",
    category="fashion",  # 선택사항
    age_range="20대 후반",  # 선택사항
    gender="남성",  # 선택사항
    location="서울",  # 선택사항
    limit=20
)

# 특정 주제의 트렌드 분석
get_trend_insights_tool(
    topic="키링",
    persona_filters={
        "age_range": "20대",
        "gender": "여성"
    },
    min_freshness=100  # 최소 신선도 점수
)

# 키워드로 관련 응답 검색
search_responses_tool(
    keyword="디자인",
    category="fashion",
    limit=20
)

get_persona_tool(persona_id="persona_123")

list_personas_tool(
    age_range="20대 후반",
    gender="남성",
    location="서울",
    occupation_category="IT/개발",
    mbti_type="INTJ",
    min_freshness=200,
    limit=50
)

compare_personas_tool(
    persona_id1="persona_123",
    persona_id2="persona_456"
)

get_statistics_tool()

get_persona_survey_history_tool(persona_id="persona_123")

generate_sample_personas_tool(
    count=50,
    use_llm=True  # False면 템플릿 기반 빠른 생성 (비용 없음)
)

generate_sample_surveys_tool(
    persona_count=20,
    responses_per_persona=2,
    use_llm=True
)

generate_all_sample_data_tool(
    persona_count=50,
    responses_per_persona=2,
    use_llm=True
)

pip install -r requirements.txt

pip install -e .

# Groq API 키 (LLM 기능 사용 시 필수)
GROQ_API_KEY=your_groq_api_key_here

# 데이터베이스 URL (선택사항, 기본값: sqlite:///data/fgi.db)
DATABASE_URL=sqlite:///data/fgi.db

# 로그 레벨 (선택사항, 기본값: INFO)
LOG_LEVEL=INFO

python -m src.main

python -m src.main

{
  "mcpServers": {
    "persona-server": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/Users/seodong-ug/Desktop/persona_mcp"
    }
  }
}

{
    "id": "persona_123",                    # 고유 ID
    "user_id": "user_123",                  # 사용자 ID (선택사항)
    "freshness_score": 250.0,               # 신선도 점수
    "last_updated": "2024-01-15T10:30:00",  # 마지막 업데이트
    "created_at": "2024-01-10T09:00:00",    # 생성일시
    
    # 기본 프로필
    "age_range": "20대 후반",
    "gender": "남성",
    "location": "서울",
    "occupation_category": "IT/개발",
    "income_range": "300-500만원",
    
    # 심층 페르소나 프로필
    "interests": ["프로그래밍", "AI", "게임"],
    "personality_traits": ["논리적", "호기심 많음"],
    "values": ["성장", "자유"],
    "lifestyle": "주말에는 코딩과 게임을 즐기는 개발자",
    
    # MBTI 분석
    "mbti_type": "INTJ",
    "mbti_dimensions": {
        "E_I": "내향(I) - 혼자 있을 때 에너지를 얻음",
        "S_N": "직관(N) - 미래와 가능성에 집중",
        "T_F": "사고(T) - 논리와 객관성 중시",
        "J_P": "판단(J) - 계획과 체계 선호"
    },
    "mbti_confidence": 85  # 0-100
}

{
    "id": "survey_123",
    "category": "technology",
    "questions": [
        {
            "id": "q1",
            "text": "요즘 기술 분야에서 가장 관심있는 주제는?",
            "type": "open"
        }
    ],
    "created_at": "2024-01-15T10:00:00",
    "news_source": null  # 선택사항
}

{
    "id": "response_123",
    "persona_id": "persona_123",
    "survey_id": "survey_123",
    "responses": [
        {
            "question_id": "q1",
            "answer": "AI와 머신러닝에 관심이 많아요"
        }
    ],
    "submitted_at": "2024-01-15T10:30:00"
}

# 1. 기본 프로필 질문 목록 조회
questions = get_basic_profile_questions_tool()
# 반환 예시:
# {
#   "questions": {
#     "age_range": {"text": "나이대를 선택해주세요", "type": "choice", "options": [...]},
#     "gender": {"text": "성별을 선택해주세요", "type": "choice", "options": [...]},
#     ...
#   }
# }

# 2. 사용자에게 질문하고 답변 수집 (예시)
# 실제로는 UI나 채팅 인터페이스에서 사용자에게 질문을 제시하고 답변을 받습니다.

# 3. 수집한 답변으로 기본 프로필 설정
update_basic_profile_tool(
    persona_id="persona_new_001",
    profile_data={
        "age_range": "20대 후반",        # questions["questions"]["age_range"]["options"] 중 하나
        "gender": "남성",                 # questions["questions"]["gender"]["options"] 중 하나
        "location": "서울",               # questions["questions"]["location"]["options"] 중 하나
        "occupation_category": "IT/개발"  # questions["questions"]["occupation_category"]["options"] 중 하나
        # income_range는 선택사항이므로 생략 가능
    }
)

# 4. 기술 카테고리 설문 시작
survey = create_fgi_survey_tool(
    category="technology",
    persona_id="persona_new_001"
)

# 5. 첫 번째 질문에 답변
submit_fgi_response_tool(
    persona_id="persona_new_001",
    survey_id=survey["survey_id"],
    responses=[
        {
            "question_id": survey["questions"][0]["id"],
            "answer": "AI와 머신러닝에 관심이 많아요. 최근 ChatGPT 같은 생성형 AI가 정말 흥미롭습니다."
        }
    ]
)

# 6. 다음 질문 생성
next_q = generate_next_question_tool(
    survey_id=survey["survey_id"],
    previous_qa=[
        {
            "question": survey["questions"][0]["text"],
            "answer": "AI와 머신러닝에 관심이 많아요..."
        }
    ],
    category="technology"
)

# 7. 계속 질문-답변 반복...
# 8. 최종적으로 페르소나 예측
persona = predict_persona_tool(
    responses=[
        {"question_id": "q1", "answer": "..."},
        {"question_id": "q2", "answer": "..."}
    ]
)

# 스티커 디자인에 대한 20대 여성들의 선호도 분석
preference = analyze_preference_tool(
    query="스티커 디자인",
    category="fashion",
    age_range="20대",
    gender="여성",
    location="서울",
    limit=30
)

# 결과에서 인사이트 확인
print(preference["insights"])
# - "미니멀하고 깔끔한 디자인 선호"
# - "캐릭터 스티커 인기"
# - "패스텔 톤 색상 선호"

# 키링 트렌드 분석
trends = get_trend_insights_tool(
    topic="키링",
    persona_filters={
        "age_range": "20대",
        "gender": "여성"
    },
    min_freshness=150
)

# 트렌드 요약 확인
print(trends["summary"])

# 50개의 샘플 페르소나 생성 (LLM 사용)
generate_sample_personas_tool(count=50, use_llm=True)

# 20명의 페르소나에 대해 각각 2개의 설문 응답 생성
generate_sample_surveys_tool(
    persona_count=20,
    responses_per_persona=2,
    use_llm=True
)

# 또는 한 번에 모든 샘플 데이터 생성
generate_all_sample_data_tool(
    persona_count=50,
    responses_per_persona=2,
    use_llm=False  # 빠른 템플릿 기반 생성 (비용 없음)
)

# 두 페르소나 비교
comparison = compare_personas_tool(
    persona_id1="persona_123",
    persona_id2="persona_456"
)

# 유사점과 차이점 확인
print(comparison["similarities"])
print(comparison["differences"])

# 전체 통계 조회
stats = get_statistics_tool()
print(f"전체 페르소나 수: {stats['total_personas']}")
print(f"평균 신선도: {stats['avg_freshness']}")
print(f"MBTI 분포: {stats['mbti_distribution']}")

persona_mcp/
├── src/
│   ├── main.py                 # MCP 서버 메인 파일
│   ├── db/
│   │   ├── database.py        # 데이터베이스 연결 및 세션 관리
│   │   └── models.py          # SQLAlchemy 모델 정의
│   ├── tools/
│   │   └── persona/
│   │       ├── fgi_tools.py   # FGI 설문 관련 도구
│   │       ├── predict.py     # 페르소나 예측
│   │       ├── freshness.py   # 신선도 관리
│   │       ├── insights.py    # 인사이트 분석
│   │       ├── query.py       # 페르소나 조회
│   │       └── sample_data.py # 샘플 데이터 생성
│   └── utils/
│       ├── cache.py           # 캐싱 시스템
│       └── credentials.py     # API 키 관리
├── data/
│   └── fgi.db                 # SQLite 데이터베이스
├── cache/                     # 캐시 파일 저장소
├── requirements.txt           # Python 의존성
├── pyproject.toml            # 프로젝트 설정
└── README.md                 # 이 파일