Fluduro | ChatGPT 앱 프로젝트

Fluduro는 성격 유형을 꽃으로 매칭하는 간단한 퀴즈 애플리케이션입니다. 이 프로젝트는 ChatGPT 내부에서 대화형 위젯을 직접 만들어 OpenAI Apps SDK와 **Model Context Protocol (MCP)**을 탐구하기 위해 구축되었습니다.

🛠️ 프로젝트 개요

이 프로젝트의 목표는 다음을 배우는 것이었습니다:

1. MCP 서버를 구축하여 도구와 UI 리소스를 노출합니다.

2. OpenAI Apps SDK를 사용하여 ChatGPT에서 맞춤 HTML/CSS 위젯을 렌더링합니다.

3. ngrok을 사용하여 로컬 서버를 ChatGPT에 연결합니다.

4. LLM(Groq)을 사용하여 퀴즈 질문을 동적으로 생성합니다.

도구 및 리소스:

• 도구: say_hello, start, submit_answers, show_results, get_quiz_state.

• UI 위젯: 환영, 퀴즈, 결과 화면.

Related MCP server: Hello Widget Example

📸 시각 자료

![Welcome Screen (Light Mode)](./screenshots/welcome-light.png)
<!-- slide -->
![Welcome Screen (Dark Mode)](screenshots/welcome-dark.png)
<!-- slide -->
![Quiz Screen](screenshots/quiz.png)
<!-- slide -->
![Results Screen](screenshots/result.png)

⚡ 로컬 설정

1. 설치

저장소를 클론하고 의존성을 설치합니다:

git clone <repository-url>
cd plantora
npm install

2. 구성

API 키를 위해 .env 파일을 생성합니다:

cp .env.example .env

API_KEY 필드에 Groq API 키를 추가하세요. console.groq.com에서 무료로 받을 수 있습니다.

3. 실행 및 터널링

HTTP 모드로 서버를 시작하고 ngrok을 사용하여 공개 HTTPS 터널을 생성합니다(ChatGPT에서 필요):

# Terminal 1: Start the server
npm run start:http

# Terminal 2: Start ngrok on the same port
ngrok http 3553

ngrok이 제공하는 공개 URL을 기록해 두세요(예: https://xyz.ngrok-free.dev).

🔗 ChatGPT에 연결하는 방법

ChatGPT에서 이 앱을 테스트하려면 다음 단계를 따르세요:

1. ChatGPT에서 개발자 모드를 활성화합니다(설정 → 앱 및 커넥터 → 고급 설정).

2. 설정 → 커넥터에서 만들기를 클릭합니다.

3. Streamable HTTP를 선택하고 /mcp 경로가 포함된 ngrok URL을 붙여넣습니다: https://your-id.ngrok-free.dev/mcp

4. 이름을 "Fluduro"로 지정하고 만들기를 클릭합니다.

5. 새 채팅에 커넥터를 추가하고 *"Start the quiz."*라고 입력합니다.

🤖 기술 스택

• 백엔드: Node.js와 @modelcontextprotocol/sdk.

• LLM: 질문 생성 및 특성 분석을 위한 Groq (Llama 3.3 70B).

• 프론트엔드: Tailwind CSS(CDN)와 Google Fonts를 사용한 바닐라 HTML/CSS.

• 터널링: ngrok.

📖 SDK에서 얻은 주요 학습 내용

• window.openai 브리지: 위젯 iframe과 호스트 간에 통신하는 방법을 배웠습니다.

• 테마 동기화: openai:set_globals를 사용하여 UI가 ChatGPT의 다크/라이트 모드에 적응하도록 했습니다.

• 도구 기반 UI: structuredContent를 사용하여 모델의 도구 출력에서 UI 변경을 트리거하는 방법을 배웠습니다.

결론

이 프로젝트는 ChatGPT 생태계를 위한 네이티브 느낌의 앱을 구축하는 실습형 입문서 역할을 했습니다. OpenAI Apps 프레임워크 내에서 도구 등록, 리소스 처리, 상태 관리의 기본 사항에 중점을 둡니다.

📸 시각 자료 - 참고용 스크린샷

환영 화면 - 라이트 모드

환영 화면 - 다크 모드

퀴즈 화면

결과 화면