# Persona MCP Server

AI 기반 페르소나 분석 및 FGI (Focus Group Interview) 시스템을 위한 MCP (Model Context Protocol) 서버입니다.

## 📋 목차

- [MCP란 무엇인가?](#mcp란-무엇인가)
- [이 서비스는 무엇을 하나요?](#이-서비스는-무엇을-하나요)
- [시스템 아키텍처](#시스템-아키텍처)
- [주요 기능](#주요-기능)
- [설치 및 설정](#설치-및-설정)
- [사용 방법](#사용-방법)
- [API 도구 목록](#api-도구-목록)
- [데이터 모델](#데이터-모델)
- [사용 예제](#사용-예제)

---

## MCP란 무엇인가?

**MCP (Model Context Protocol)**는 AI 모델이 외부 도구와 서비스를 안전하게 연결하고 사용할 수 있도록 하는 표준 프로토콜입니다.

### MCP의 핵심 개념

1. **도구(Tools)**: AI가 호출할 수 있는 함수들
2. **리소스(Resources)**: AI가 읽을 수 있는 데이터 소스
3. **프롬프트(Prompts)**: 재사용 가능한 프롬프트 템플릿

### 이 프로젝트에서의 MCP

이 Persona MCP Server는 **FastMCP** 프레임워크를 사용하여 구현되었으며, 다음과 같은 방식으로 작동합니다:

- **표준 입출력(stdio) 통신**: MCP 클라이언트와 JSON-RPC 프로토콜로 통신
- **비동기 처리**: `asyncio`를 활용한 비동기 도구 실행
- **타입 안전성**: Pydantic을 사용한 요청/응답 검증

---

## 이 서비스는 무엇을 하나요?

이 MCP 서버는 **페르소나 기반 FGI 시스템**을 제공합니다. 주요 목적은 다음과 같습니다:

### 1. 페르소나 생성 및 관리
- 사용자의 설문 응답을 분석하여 AI 기반 페르소나 프로필 생성
- MBTI 유형, 관심사, 성격 특성, 가치관 등을 자동 분석
- 기본 프로필(연령대, 성별, 지역, 직업 등) 관리

### 2. 동적 FGI 설문 생성
- 카테고리별(기술, 라이프스타일, 문화, 패션, 음식, 일반) 설문 시작
- AI가 이전 답변을 분석하여 다음 질문을 동적으로 생성
- **최소한의 질문으로 최대한의 정보 수집**이 목표

### 3. 데이터 신선도 관리
- 페르소나 데이터의 가치를 "신선도 점수"로 관리
- 시간이 지남에 따라 자동으로 감소 (하루에 -3점)
- 설문 응답 제출 시 신선도 점수 증가
- SS급, S급, A급, B급, C급 등으로 데이터 가치 등급화

### 4. 비즈니스 인사이트 제공
- 특정 제품/주제에 대한 페르소나들의 선호도 분석
- 트렌드 인사이트 제공
- 키워드 기반 응답 검색
- 페르소나 비교 및 통계 분석

### 5. 샘플 데이터 생성
- 데모 및 테스트를 위한 샘플 페르소나 자동 생성
- 다양한 카테고리의 설문 및 응답 생성
- LLM 기반 자연스러운 데이터 생성 (또는 템플릿 기반 빠른 생성)

---

## 시스템 아키텍처

```
┌─────────────────┐
│  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 분석 및 생성)        │
└───────────────────────────┘
```

### 주요 컴포넌트

1. **FastMCP**: MCP 프로토콜 구현 프레임워크
2. **SQLAlchemy**: ORM을 통한 데이터베이스 관리
3. **Groq API**: LLM 기반 분석 및 생성
4. **Pydantic**: 데이터 검증 및 직렬화
5. **캐싱 시스템**: 반복적인 분석 결과 캐싱

---

## 주요 기능

### 1. 페르소나 생명주기 관리

**⚠️ 중요: 기본 프로필은 필수입니다!**

서버를 사용하기 전에 반드시 기본 프로필을 설정해야 합니다. 기본 프로필이 없으면 대부분의 기능을 사용할 수 없습니다.

#### 기본 프로필 질문 조회

페르소나의 기본 정보를 수집하기 전에, 먼저 어떤 질문을 해야 하는지 확인할 수 있습니다.

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

**반환되는 질문 목록:**
- `age_range`: 나이대 선택 (필수) - 10대, 20대 초반, 20대 후반, 30대 초반, 30대 후반, 40대 이상
- `gender`: 성별 선택 (필수) - 남성, 여성, 기타, 답변 안 함
- `location`: 거주 지역 선택 (필수) - 서울, 경기, 인천, 부산, 대구, 광주, 대전, 기타
- `occupation_category`: 직업 분야 선택 (필수) - IT/개발, 디자인, 마케팅, 교육, 서비스, 학생, 기타
- `income_range`: 월 소득 범위 (선택사항) - 200만원 미만, 200-300만원, 300-500만원, 500만원 이상, 답변 안 함

**필수 필드:** `age_range`, `gender`, `location`, `occupation_category` (4개)
**선택 필드:** `income_range` (1개)

**사용 흐름:**
1. `get_basic_profile_questions_tool()`로 질문 목록 조회
2. 사용자에게 각 질문을 제시하고 답변 수집
3. 수집한 답변을 `update_basic_profile_tool()`로 저장

#### 기본 프로필 완전성 확인

기본 프로필이 완전한지 확인할 수 있습니다.

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

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

**반환 정보:**
- `is_complete`: 기본 프로필이 완전한지 여부 (bool)
- `missing_fields`: 누락된 필수 필드 목록
- `message`: 상태 메시지
- `persona_id`: 확인한 페르소나 ID (또는 None)

#### 기본 프로필 업데이트

수집한 기본 정보를 페르소나에 저장합니다.

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

**주의사항:**
- `profile_data`의 각 필드 값은 `get_basic_profile_questions_tool()`에서 반환된 옵션 리스트 중 하나여야 합니다.
- **필수 필드 4개(`age_range`, `gender`, `location`, `occupation_category`)는 반드시 설정해야 합니다.**
- `income_range`는 선택사항이므로 생략 가능합니다.
- 기본 프로필을 저장하면 신선도 점수가 증가합니다 (최대 25점).
- **기본 프로필이 없으면 설문 생성, 응답 제출 등 대부분의 기능을 사용할 수 없습니다.**

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

**반환 정보:**
- 연령대 예측
- 관심사 리스트
- 성격 특성
- 가치관
- 라이프스타일 설명
- MBTI 유형 및 차원별 분석
- MBTI 신뢰도 점수

### 2. 동적 FGI 설문 시스템

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

**지원 카테고리:**
- `technology`: 기술 분야
- `lifestyle`: 라이프스타일
- `culture`: 문화/엔터테인먼트
- `fashion`: 패션
- `food`: 음식
- `general`: 일반

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

**특징:**
- AI가 이전 답변을 분석하여 맥락에 맞는 다음 질문 생성
- 정보 수집 완료도(`info_completeness`) 추적
- 최종 질문 여부(`is_final`) 판단
- 최대 질문 수 제한 가능

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

### 3. 신선도 점수 시스템

페르소나 데이터의 가치를 "신선도 점수"로 관리합니다.

#### 신선도 점수 계산 방식

**점수 획득:**
- 기본 프로필 업데이트: 최대 25점
- 설문 응답 제출: 응답당 10-50점 (응답 품질에 따라)
- 페르소나 예측 완료: 50-100점

**점수 감소:**
- 시간 경과에 따라 자동 감소: 하루에 -3점
- 최소 0점까지 감소

#### 신선도 등급

| 등급 | 점수 범위 | 설명 |
|------|----------|------|
| SS급 | 500점 이상 | 완벽한 데이터 - 프리미엄 판매 |
| S급 | 300-499점 | 최고 가치 데이터 - 고가 판매 |
| A급 | 200-299점 | 고가치 데이터 - 판매 가능 |
| B급 | 100-199점 | 보통 데이터 - 업데이트 권장 |
| C급 | 50-99점 | 낮은 가치 - 업데이트 필요 |
| F급 | 0-49점 | 최소 데이터 - 즉시 업데이트 필요 |

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

**반환 정보:**
- 현재 신선도 점수
- 등급 (SS, S, A, B, C, F)
- 마지막 업데이트 날짜
- 업데이트 필요 여부

### 4. 비즈니스 인사이트

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

**분석 내용:**
- 선호하는 스타일/특성
- 공통된 선호도 패턴
- 차별화된 선호도
- 구체적인 예시 응답

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

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

### 5. 페르소나 조회 및 비교

#### 페르소나 상세 조회
```python
get_persona_tool(persona_id="persona_123")
```

**반환 정보:**
- 기본 프로필
- 페르소나 프로필 (관심사, 성격, 가치관 등)
- MBTI 분석
- 통계 정보 (설문 수, 응답 수 등)

#### 페르소나 목록 조회
```python
list_personas_tool(
    age_range="20대 후반",
    gender="남성",
    location="서울",
    occupation_category="IT/개발",
    mbti_type="INTJ",
    min_freshness=200,
    limit=50
)
```

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

**비교 내용:**
- 기본 프로필 비교
- MBTI 차이점
- 관심사 유사도
- 성격 특성 차이점

### 6. 통계 및 히스토리

#### 전체 통계
```python
get_statistics_tool()
```

**통계 정보:**
- 전체 페르소나 수
- 설문 수 및 응답 수
- MBTI 분포
- 지역 분포
- 직업 분포
- 평균 신선도 점수

#### 설문 히스토리
```python
get_persona_survey_history_tool(persona_id="persona_123")
```

### 7. 샘플 데이터 생성

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

#### 설문 및 응답 생성
```python
generate_sample_surveys_tool(
    persona_count=20,
    responses_per_persona=2,
    use_llm=True
)
```

#### 전체 샘플 데이터 생성
```python
generate_all_sample_data_tool(
    persona_count=50,
    responses_per_persona=2,
    use_llm=True
)
```

---

## 설치 및 설정

### 1. 의존성 설치

```bash
pip install -r requirements.txt
```

또는 `pyproject.toml`을 사용하는 경우:

```bash
pip install -e .
```

### 2. 환경 변수 설정

`.env` 파일을 프로젝트 루트에 생성하고 다음을 설정하세요:

```env
# 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
```

**Groq API 키 발급 방법:**
1. [Groq Console](https://console.groq.com/)에 접속
2. API Keys 메뉴에서 새 키 생성
3. `.env` 파일에 추가

### 3. 데이터베이스 초기화

서버를 처음 실행하면 자동으로 데이터베이스가 생성됩니다:

```bash
python -m src.main
```

데이터베이스는 `data/fgi.db`에 생성됩니다 (기본 설정).

**⚠️ 중요: 서버 시작 시 기본 프로필 확인**

서버가 시작될 때 자동으로 기본 프로필이 설정되어 있는지 확인합니다:
- 기본 프로필이 없으면 경고 메시지가 표시됩니다
- 기본 프로필이 없으면 대부분의 기능을 사용할 수 없습니다
- 먼저 `get_basic_profile_questions_tool()`로 질문 목록을 조회하고, `update_basic_profile_tool()`로 기본 프로필을 저장해야 합니다

### 4. 서버 실행

#### 직접 실행
```bash
python -m src.main
```

#### MCP 클라이언트에서 사용
MCP 클라이언트(Cursor AI, Claude Desktop 등)에서 설정하여 사용합니다.

---

## 사용 방법

### Cursor AI에서 사용하기

1. **Cursor 설정 열기**
   - `Cmd + ,` (Mac) 또는 `Ctrl + ,` (Windows/Linux)
   - "MCP" 검색

2. **MCP 서버 설정 추가**
   
   설정 파일에 다음을 추가:

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

   **주의:** `cwd` 경로를 실제 프로젝트 경로로 변경하세요.

3. **Cursor 재시작**
   - Cursor를 완전히 종료 후 다시 시작

4. **사용하기**
   - 채팅에서 "페르소나 목록 조회해줘" 같은 자연어 명령 사용
   - 또는 직접 도구 호출

### Claude Desktop에서 사용하기

`claude_desktop_config.json` 파일에 다음을 추가:

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

---

## API 도구 목록

### 기본 관리

| 도구명 | 설명 | 필수 파라미터 |
|--------|------|--------------|
| `health` | 서비스 상태 확인 | 없음 |
| `get_tool_definitions` | 사용 가능한 도구 목록 조회 | 없음 |

### 페르소나 관리

| 도구명 | 설명 | 필수 파라미터 |
|--------|------|--------------|
| `get_basic_profile_questions_tool` | 기본 프로필 질문 목록 조회 | 없음 |
| `check_basic_profile_tool` | 기본 프로필 완전성 확인 | 없음 (persona_id 선택) |
| `update_basic_profile_tool` | 기본 프로필 업데이트 | `persona_id`, `profile_data` |
| `predict_persona_tool` | 설문 응답 기반 페르소나 예측 | `responses` |
| `get_persona_tool` | 페르소나 상세 조회 | `persona_id` |
| `list_personas_tool` | 페르소나 목록 조회 | 없음 (필터 옵션) |
| `compare_personas_tool` | 두 페르소나 비교 | `persona_id1`, `persona_id2` |
| `check_freshness_tool` | 신선도 점수 확인 | `persona_id` |

### FGI 설문

| 도구명 | 설명 | 필수 파라미터 |
|--------|------|--------------|
| `create_fgi_survey_tool` | 설문 시작 | `category` |
| `generate_next_question_tool` | 다음 질문 동적 생성 | `survey_id`, `previous_qa` |
| `submit_fgi_response_tool` | 응답 제출 | `persona_id`, `survey_id`, `responses` |
| `get_persona_survey_history_tool` | 설문 히스토리 조회 | `persona_id` |

### 인사이트 및 분석

| 도구명 | 설명 | 필수 파라미터 |
|--------|------|--------------|
| `analyze_preference_tool` | 선호도 분석 | `query` |
| `get_trend_insights_tool` | 트렌드 인사이트 | `topic` |
| `search_responses_tool` | 응답 검색 | `keyword` |
| `get_statistics_tool` | 전체 통계 조회 | 없음 |

### 샘플 데이터

| 도구명 | 설명 | 필수 파라미터 |
|--------|------|--------------|
| `generate_sample_personas_tool` | 샘플 페르소나 생성 | 없음 (옵션) |
| `generate_sample_surveys_tool` | 샘플 설문 생성 | 없음 (옵션) |
| `generate_all_sample_data_tool` | 전체 샘플 데이터 생성 | 없음 (옵션) |

---

## 데이터 모델

### Persona (페르소나)

```python
{
    "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
}
```

### FGISurvey (설문)

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

### FGIResponse (응답)

```python
{
    "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: 새로운 페르소나 생성 및 설문 진행

```python
# 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": "..."}
    ]
)
```

### 예제 2: 특정 제품에 대한 선호도 분석

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

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

### 예제 3: 트렌드 인사이트 조회

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

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

### 예제 4: 샘플 데이터로 빠른 테스트

```python
# 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  # 빠른 템플릿 기반 생성 (비용 없음)
)
```

### 예제 5: 페르소나 비교 및 통계

```python
# 두 페르소나 비교
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']}")
```

---

## 기술 스택

- **FastMCP**: MCP 프로토콜 구현 프레임워크
- **SQLAlchemy**: ORM 및 데이터베이스 관리
- **Groq API**: LLM 기반 분석 및 생성
- **Pydantic**: 데이터 검증 및 직렬화
- **Python-dotenv**: 환경 변수 관리
- **SQLite**: 기본 데이터베이스 (PostgreSQL 등으로 변경 가능)

---

## 프로젝트 구조

```
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                 # 이 파일
```

---

## 주의사항

1. **Groq API 키**: LLM 기능을 사용하려면 Groq API 키가 필요합니다. 키가 없어도 기본적인 CRUD 작업은 가능하지만, 페르소나 예측이나 동적 질문 생성은 불가능합니다.

2. **신선도 점수**: 신선도 점수는 시간이 지남에 따라 자동으로 감소합니다. 정기적으로 설문을 진행하여 데이터를 업데이트하는 것이 좋습니다.

3. **캐싱**: 선호도 분석, 트렌드 인사이트 등은 캐싱되어 12시간 동안 재사용됩니다. 실시간 데이터가 필요한 경우 캐시를 무시하도록 수정할 수 있습니다.

4. **데이터베이스**: 기본적으로 SQLite를 사용하지만, `DATABASE_URL` 환경 변수를 변경하여 PostgreSQL, MySQL 등 다른 데이터베이스를 사용할 수 있습니다.

---

## 라이선스

이 프로젝트의 라이선스 정보를 여기에 추가하세요.

---

## 기여하기

이슈나 풀 리퀘스트를 환영합니다!

---

## 문의

문제가 발생하거나 질문이 있으시면 이슈를 생성해주세요.