Persona MCP Server
AI 기반 페르소나 분석 및 FGI (Focus Group Interview) 시스템을 위한 MCP (Model Context Protocol) 서버입니다.
📋 목차
MCP란 무엇인가?
**MCP (Model Context Protocol)**는 AI 모델이 외부 도구와 서비스를 안전하게 연결하고 사용할 수 있도록 하는 표준 프로토콜입니다.
MCP의 핵심 개념
도구(Tools): AI가 호출할 수 있는 함수들
리소스(Resources): AI가 읽을 수 있는 데이터 소스
프롬프트(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. 샘플 데이터 생성
시스템 아키텍처
┌─────────────────┐
│ 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 분석 및 생성) │
└───────────────────────────┘
주요 컴포넌트
FastMCP: MCP 프로토콜 구현 프레임워크
SQLAlchemy: ORM을 통한 데이터베이스 관리
Groq API: LLM 기반 분석 및 생성
Pydantic: 데이터 검증 및 직렬화
캐싱 시스템: 반복적인 분석 결과 캐싱
주요 기능
1. 페르소나 생명주기 관리
⚠️ 중요: 기본 프로필은 필수입니다!
서버를 사용하기 전에 반드시 기본 프로필을 설정해야 합니다. 기본 프로필이 없으면 대부분의 기능을 사용할 수 없습니다.
기본 프로필 질문 조회
페르소나의 기본 정보를 수집하기 전에, 먼저 어떤 질문을 해야 하는지 확인할 수 있습니다.
# 기본 프로필 질문 목록 조회
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개)
사용 흐름:
get_basic_profile_questions_tool()로 질문 목록 조회
사용자에게 각 질문을 제시하고 답변 수집
수집한 답변을 update_basic_profile_tool()로 저장
기본 프로필 완전성 확인
기본 프로필이 완전한지 확인할 수 있습니다.
# 모든 페르소나의 기본 프로필 확인
check_basic_profile_tool()
# 특정 페르소나의 기본 프로필 확인
check_basic_profile_tool(persona_id="persona_123")
반환 정보:
is_complete: 기본 프로필이 완전한지 여부 (bool)
missing_fields: 누락된 필수 필드 목록
message: 상태 메시지
persona_id: 확인한 페르소나 ID (또는 None)
기본 프로필 업데이트
수집한 기본 정보를 페르소나에 저장합니다.
# 페르소나의 기본 정보 설정
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개(
income_range는 선택사항이므로 생략 가능합니다.
기본 프로필을 저장하면 신선도 점수가 증가합니다 (최대 25점).
기본 프로필이 없으면 설문 생성, 응답 제출 등 대부분의 기능을 사용할 수 없습니다.
페르소나 예측 (AI 분석)
# 설문 응답을 기반으로 페르소나 자동 생성
predict_persona_tool(
responses=[
{"question_id": "q1", "answer": "저는 기술에 관심이 많아요..."},
{"question_id": "q2", "answer": "주말에는 코딩을 하거나..."}
],
user_id="user_123"
)
반환 정보:
연령대 예측
관심사 리스트
성격 특성
가치관
라이프스타일 설명
MBTI 유형 및 차원별 분석
MBTI 신뢰도 점수
2. 동적 FGI 설문 시스템
설문 시작
# 카테고리별 설문 시작
create_fgi_survey_tool(
category="technology", # technology, lifestyle, culture, fashion, food, general
persona_id="persona_123" # 선택사항
)
지원 카테고리:
technology: 기술 분야
lifestyle: 라이프스타일
culture: 문화/엔터테인먼트
fashion: 패션
food: 음식
general: 일반
다음 질문 동적 생성
# 이전 답변을 분석하여 다음 질문 생성
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": "답변 내용"}
]
)
3. 신선도 점수 시스템
페르소나 데이터의 가치를 "신선도 점수"로 관리합니다.
신선도 점수 계산 방식
점수 획득:
점수 감소:
시간 경과에 따라 자동 감소: 하루에 -3점
최소 0점까지 감소
신선도 등급
등급 | 점수 범위 | 설명 |
SS급 | 500점 이상 | 완벽한 데이터 - 프리미엄 판매 |
S급 | 300-499점 | 최고 가치 데이터 - 고가 판매 |
A급 | 200-299점 | 고가치 데이터 - 판매 가능 |
B급 | 100-199점 | 보통 데이터 - 업데이트 권장 |
C급 | 50-99점 | 낮은 가치 - 업데이트 필요 |
F급 | 0-49점 | 최소 데이터 - 즉시 업데이트 필요 |
# 신선도 확인
check_freshness_tool(persona_id="persona_123")
반환 정보:
현재 신선도 점수
등급 (SS, S, A, B, C, F)
마지막 업데이트 날짜
업데이트 필요 여부
4. 비즈니스 인사이트
선호도 분석
# 특정 제품/주제에 대한 선호도 분석
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
)
5. 페르소나 조회 및 비교
페르소나 상세 조회
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"
)
비교 내용:
기본 프로필 비교
MBTI 차이점
관심사 유사도
성격 특성 차이점
6. 통계 및 히스토리
전체 통계
통계 정보:
전체 페르소나 수
설문 수 및 응답 수
MBTI 분포
지역 분포
직업 분포
평균 신선도 점수
설문 히스토리
get_persona_survey_history_tool(persona_id="persona_123")
7. 샘플 데이터 생성
페르소나 생성
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
)
설치 및 설정
1. 의존성 설치
pip install -r requirements.txt
또는 pyproject.toml을 사용하는 경우:
2. 환경 변수 설정
.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 키 발급 방법:
Groq Console에 접속
API Keys 메뉴에서 새 키 생성
.env 파일에 추가
3. 데이터베이스 초기화
서버를 처음 실행하면 자동으로 데이터베이스가 생성됩니다:
데이터베이스는 data/fgi.db에 생성됩니다 (기본 설정).
⚠️ 중요: 서버 시작 시 기본 프로필 확인
서버가 시작될 때 자동으로 기본 프로필이 설정되어 있는지 확인합니다:
기본 프로필이 없으면 경고 메시지가 표시됩니다
기본 프로필이 없으면 대부분의 기능을 사용할 수 없습니다
먼저 get_basic_profile_questions_tool()로 질문 목록을 조회하고, update_basic_profile_tool()로 기본 프로필을 저장해야 합니다
4. 서버 실행
직접 실행
MCP 클라이언트에서 사용
MCP 클라이언트(Cursor AI, Claude Desktop 등)에서 설정하여 사용합니다.
사용 방법
Cursor AI에서 사용하기
Cursor 설정 열기
MCP 서버 설정 추가
설정 파일에 다음을 추가:
{
"mcpServers": {
"persona-server": {
"command": "python3",
"args": ["-m", "src.main"],
"cwd": "/Users/seodong-ug/Desktop/persona_mcp"
}
}
}
주의: cwd 경로를 실제 프로젝트 경로로 변경하세요.
Cursor 재시작
사용하기
Claude Desktop에서 사용하기
claude_desktop_config.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 (페르소나)
{
"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 (설문)
{
"id": "survey_123",
"category": "technology",
"questions": [
{
"id": "q1",
"text": "요즘 기술 분야에서 가장 관심있는 주제는?",
"type": "open"
}
],
"created_at": "2024-01-15T10:00:00",
"news_source": null # 선택사항
}
FGIResponse (응답)
{
"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: 새로운 페르소나 생성 및 설문 진행
# 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: 특정 제품에 대한 선호도 분석
# 스티커 디자인에 대한 20대 여성들의 선호도 분석
preference = analyze_preference_tool(
query="스티커 디자인",
category="fashion",
age_range="20대",
gender="여성",
location="서울",
limit=30
)
# 결과에서 인사이트 확인
print(preference["insights"])
# - "미니멀하고 깔끔한 디자인 선호"
# - "캐릭터 스티커 인기"
# - "패스텔 톤 색상 선호"
예제 3: 트렌드 인사이트 조회
# 키링 트렌드 분석
trends = get_trend_insights_tool(
topic="키링",
persona_filters={
"age_range": "20대",
"gender": "여성"
},
min_freshness=150
)
# 트렌드 요약 확인
print(trends["summary"])
예제 4: 샘플 데이터로 빠른 테스트
# 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: 페르소나 비교 및 통계
# 두 페르소나 비교
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 # 이 파일
주의사항
Groq API 키: LLM 기능을 사용하려면 Groq API 키가 필요합니다. 키가 없어도 기본적인 CRUD 작업은 가능하지만, 페르소나 예측이나 동적 질문 생성은 불가능합니다.
신선도 점수: 신선도 점수는 시간이 지남에 따라 자동으로 감소합니다. 정기적으로 설문을 진행하여 데이터를 업데이트하는 것이 좋습니다.
캐싱: 선호도 분석, 트렌드 인사이트 등은 캐싱되어 12시간 동안 재사용됩니다. 실시간 데이터가 필요한 경우 캐시를 무시하도록 수정할 수 있습니다.
데이터베이스: 기본적으로 SQLite를 사용하지만, DATABASE_URL 환경 변수를 변경하여 PostgreSQL, MySQL 등 다른 데이터베이스를 사용할 수 있습니다.
라이선스
이 프로젝트의 라이선스 정보를 여기에 추가하세요.
기여하기
이슈나 풀 리퀘스트를 환영합니다!
문의
문제가 발생하거나 질문이 있으시면 이슈를 생성해주세요.