Manages environment variables for API keys, database URLs, and configuration settings through .env files.
Supports MySQL as an alternative database backend through configurable DATABASE_URL environment variable.
Supports PostgreSQL as an alternative database backend through configurable DATABASE_URL environment variable.
Uses Pydantic for data validation and serialization of persona profiles, survey responses, and API request/response models.
Implements the MCP server using Python with asyncio for asynchronous processing of persona analysis and FGI survey operations.
Provides ORM-based database management for persona profiles, FGI surveys, and response data with support for multiple database backends.
Serves as the default database backend for storing persona data, survey questions, responses, and freshness scores.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Persona MCP Servercreate a persona from my survey responses about tech preferences"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. 샘플 데이터 생성
데모 및 테스트를 위한 샘플 페르소나 자동 생성
다양한 카테고리의 설문 및 응답 생성
LLM 기반 자연스러운 데이터 생성 (또는 템플릿 기반 빠른 생성)
시스템 아키텍처
주요 컴포넌트
FastMCP: MCP 프로토콜 구현 프레임워크
SQLAlchemy: ORM을 통한 데이터베이스 관리
Groq API: LLM 기반 분석 및 생성
Pydantic: 데이터 검증 및 직렬화
캐싱 시스템: 반복적인 분석 결과 캐싱
주요 기능
1. 페르소나 생명주기 관리
⚠️ 중요: 기본 프로필은 필수입니다!
서버를 사용하기 전에 반드시 기본 프로필을 설정해야 합니다. 기본 프로필이 없으면 대부분의 기능을 사용할 수 없습니다.
기본 프로필 질문 조회
페르소나의 기본 정보를 수집하기 전에, 먼저 어떤 질문을 해야 하는지 확인할 수 있습니다.
반환되는 질문 목록:
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()로 저장
기본 프로필 완전성 확인
기본 프로필이 완전한지 확인할 수 있습니다.
반환 정보:
is_complete: 기본 프로필이 완전한지 여부 (bool)missing_fields: 누락된 필수 필드 목록message: 상태 메시지persona_id: 확인한 페르소나 ID (또는 None)
기본 프로필 업데이트
수집한 기본 정보를 페르소나에 저장합니다.
주의사항:
profile_data의 각 필드 값은get_basic_profile_questions_tool()에서 반환된 옵션 리스트 중 하나여야 합니다.필수 필드 4개(
income_range는 선택사항이므로 생략 가능합니다.기본 프로필을 저장하면 신선도 점수가 증가합니다 (최대 25점).
기본 프로필이 없으면 설문 생성, 응답 제출 등 대부분의 기능을 사용할 수 없습니다.
페르소나 예측 (AI 분석)
반환 정보:
연령대 예측
관심사 리스트
성격 특성
가치관
라이프스타일 설명
MBTI 유형 및 차원별 분석
MBTI 신뢰도 점수
2. 동적 FGI 설문 시스템
설문 시작
지원 카테고리:
technology: 기술 분야lifestyle: 라이프스타일culture: 문화/엔터테인먼트fashion: 패션food: 음식general: 일반
다음 질문 동적 생성
특징:
AI가 이전 답변을 분석하여 맥락에 맞는 다음 질문 생성
정보 수집 완료도(
info_completeness) 추적최종 질문 여부(
is_final) 판단최대 질문 수 제한 가능
응답 제출
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점 | 최소 데이터 - 즉시 업데이트 필요 |
반환 정보:
현재 신선도 점수
등급 (SS, S, A, B, C, F)
마지막 업데이트 날짜
업데이트 필요 여부
4. 비즈니스 인사이트
선호도 분석
분석 내용:
선호하는 스타일/특성
공통된 선호도 패턴
차별화된 선호도
구체적인 예시 응답
트렌드 인사이트
응답 검색
5. 페르소나 조회 및 비교
페르소나 상세 조회
반환 정보:
기본 프로필
페르소나 프로필 (관심사, 성격, 가치관 등)
MBTI 분석
통계 정보 (설문 수, 응답 수 등)
페르소나 목록 조회
페르소나 비교
비교 내용:
기본 프로필 비교
MBTI 차이점
관심사 유사도
성격 특성 차이점
6. 통계 및 히스토리
전체 통계
통계 정보:
전체 페르소나 수
설문 수 및 응답 수
MBTI 분포
지역 분포
직업 분포
평균 신선도 점수
설문 히스토리
7. 샘플 데이터 생성
페르소나 생성
설문 및 응답 생성
전체 샘플 데이터 생성
설치 및 설정
1. 의존성 설치
또는 pyproject.toml을 사용하는 경우:
2. 환경 변수 설정
.env 파일을 프로젝트 루트에 생성하고 다음을 설정하세요:
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 설정 열기
Cmd + ,(Mac) 또는Ctrl + ,(Windows/Linux)"MCP" 검색
MCP 서버 설정 추가
설정 파일에 다음을 추가:
{ "mcpServers": { "persona-server": { "command": "python3", "args": ["-m", "src.main"], "cwd": "/Users/seodong-ug/Desktop/persona_mcp" } } }주의:
cwd경로를 실제 프로젝트 경로로 변경하세요.Cursor 재시작
Cursor를 완전히 종료 후 다시 시작
사용하기
채팅에서 "페르소나 목록 조회해줘" 같은 자연어 명령 사용
또는 직접 도구 호출
Claude Desktop에서 사용하기
claude_desktop_config.json 파일에 다음을 추가:
API 도구 목록
기본 관리
도구명 | 설명 | 필수 파라미터 |
| 서비스 상태 확인 | 없음 |
| 사용 가능한 도구 목록 조회 | 없음 |
페르소나 관리
도구명 | 설명 | 필수 파라미터 |
| 기본 프로필 질문 목록 조회 | 없음 |
| 기본 프로필 완전성 확인 | 없음 (persona_id 선택) |
| 기본 프로필 업데이트 |
|
| 설문 응답 기반 페르소나 예측 |
|
| 페르소나 상세 조회 |
|
| 페르소나 목록 조회 | 없음 (필터 옵션) |
| 두 페르소나 비교 |
|
| 신선도 점수 확인 |
|
FGI 설문
도구명 | 설명 | 필수 파라미터 |
| 설문 시작 |
|
| 다음 질문 동적 생성 |
|
| 응답 제출 |
|
| 설문 히스토리 조회 |
|
인사이트 및 분석
도구명 | 설명 | 필수 파라미터 |
| 선호도 분석 |
|
| 트렌드 인사이트 |
|
| 응답 검색 |
|
| 전체 통계 조회 | 없음 |
샘플 데이터
도구명 | 설명 | 필수 파라미터 |
| 샘플 페르소나 생성 | 없음 (옵션) |
| 샘플 설문 생성 | 없음 (옵션) |
| 전체 샘플 데이터 생성 | 없음 (옵션) |
데이터 모델
Persona (페르소나)
FGISurvey (설문)
FGIResponse (응답)
사용 예제
예제 1: 새로운 페르소나 생성 및 설문 진행
예제 2: 특정 제품에 대한 선호도 분석
예제 3: 트렌드 인사이트 조회
예제 4: 샘플 데이터로 빠른 테스트
예제 5: 페르소나 비교 및 통계
기술 스택
FastMCP: MCP 프로토콜 구현 프레임워크
SQLAlchemy: ORM 및 데이터베이스 관리
Groq API: LLM 기반 분석 및 생성
Pydantic: 데이터 검증 및 직렬화
Python-dotenv: 환경 변수 관리
SQLite: 기본 데이터베이스 (PostgreSQL 등으로 변경 가능)
프로젝트 구조
주의사항
Groq API 키: LLM 기능을 사용하려면 Groq API 키가 필요합니다. 키가 없어도 기본적인 CRUD 작업은 가능하지만, 페르소나 예측이나 동적 질문 생성은 불가능합니다.
신선도 점수: 신선도 점수는 시간이 지남에 따라 자동으로 감소합니다. 정기적으로 설문을 진행하여 데이터를 업데이트하는 것이 좋습니다.
캐싱: 선호도 분석, 트렌드 인사이트 등은 캐싱되어 12시간 동안 재사용됩니다. 실시간 데이터가 필요한 경우 캐시를 무시하도록 수정할 수 있습니다.
데이터베이스: 기본적으로 SQLite를 사용하지만,
DATABASE_URL환경 변수를 변경하여 PostgreSQL, MySQL 등 다른 데이터베이스를 사용할 수 있습니다.
라이선스
이 프로젝트의 라이선스 정보를 여기에 추가하세요.
기여하기
이슈나 풀 리퀘스트를 환영합니다!
문의
문제가 발생하거나 질문이 있으시면 이슈를 생성해주세요.