README.md•28.2 kB
# 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 등 다른 데이터베이스를 사용할 수 있습니다.
---
## 라이선스
이 프로젝트의 라이선스 정보를 여기에 추가하세요.
---
## 기여하기
이슈나 풀 리퀘스트를 환영합니다!
---
## 문의
문제가 발생하거나 질문이 있으시면 이슈를 생성해주세요.