Fluduro | Проект приложения для ChatGPT

Fluduro — это простое приложение-викторина, определяющее цветок по типу личности. Этот проект был создан для изучения OpenAI Apps SDK и Model Context Protocol (MCP) путём создания интерактивных виджетов прямо внутри ChatGPT.

🛠️ Обзор проекта

Цель этого проекта — научиться:

1. Создавать MCP-сервер, который предоставляет инструменты и UI-ресурсы.

2. Использовать OpenAI Apps SDK для рендеринга пользовательских HTML/CSS-виджетов в ChatGPT.

3. Подключать локальный сервер к ChatGPT с помощью ngrok.

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. Конфигурация

Создайте файл .env для ваших API-ключей:

cp .env.example .env

Добавьте ваш Groq API-ключ в поле API_KEY. Вы можете получить его бесплатно на 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

Запомните публичный URL, предоставленный ngrok (например, https://xyz.ngrok-free.dev).

🔗 Как подключиться к ChatGPT

Чтобы протестировать это приложение в ChatGPT, выполните следующие шаги:

1. Включите режим разработчика в ChatGPT (Настройки → Приложения и коннекторы → Дополнительные настройки).

2. В настройках → Коннекторы нажмите Создать.

3. Выберите Streamable HTTP и вставьте ваш ngrok URL с путём /mcp: https://your-id.ngrok-free.dev/mcp

4. Назовите его «Fluduro» и нажмите Создать.

5. Добавьте коннектор в новый чат и введите «Начните викторину».

🤖 Технологический стек

• Бэкенд: Node.js с @modelcontextprotocol/sdk.

• LLM: Groq (Llama 3.3 70B) для генерации вопросов и анализа черт личности.

• Фронтенд: Ванильные HTML/CSS с Tailwind CSS (CDN) и Google Fonts.

• Туннелирование: ngrok.

📖 Ключевые уроки из SDK

• Мост window.openai: узнал, как организовать связь между iframe виджета и хост-приложением.

• Синхронизация темы: использовал openai:set_globals, чтобы UI адаптировался к тёмному/светлому режиму ChatGPT.

• UI, управляемый инструментами: узнал, как запускать изменения интерфейса на основе выходных данных инструментов модели с помощью structuredContent.

Заключение

Этот проект стал практическим введением в создание приложений, ощущающихся как нативные, для экосистемы ChatGPT. В нём рассматриваются основы регистрации инструментов, обработки ресурсов и управления состоянием в рамках фреймворка OpenAI Apps.

📸 Визуальные материалы — скриншоты для справки

ЭКРАН ПРИВЕТСТВИЯ — СВЕТЛЫЙ РЕЖИМ

ЭКРАН ПРИВЕТСТВИЯ — ТЁМНЫЙ РЕЖИМ

ЭКРАН ВИКТОРИНЫ

ЭКРАН РЕЗУЛЬТАТОВ