Fluduro | Un proyecto de aplicación para ChatGPT

Fluduro es una aplicación sencilla de test de personalidad basado en flores. Este proyecto se creó para explorar el OpenAI Apps SDK y el Model Context Protocol (MCP) mediante la creación de widgets interactivos directamente dentro de ChatGPT.

🛠️ Descripción general del proyecto

El objetivo de este proyecto era aprender a:

1. Construir un servidor MCP que exponga herramientas y recursos de UI.

2. Usar el OpenAI Apps SDK para renderizar widgets HTML/CSS personalizados en ChatGPT.

3. Conectar un servidor local a ChatGPT usando ngrok.

4. Usar un LLM (Groq) para generar dinámicamente las preguntas del test.

Herramientas y recursos:

• Herramientas: say_hello, start, submit_answers, show_results, get_quiz_state.

• Widgets de UI: pantallas de bienvenida, del test y de resultados.

Related MCP server: Hello Widget Example

📸 Imágenes

![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)

⚡ Configuración local

1. Instalación

Clona el repositorio e instala las dependencias:

git clone <repository-url>
cd plantora
npm install

2. Configuración

Crea un archivo .env con tus claves de API:

cp .env.example .env

Añade tu clave de API de Groq al campo API_KEY. Puedes obtener una gratis en console.groq.com.

3. Ejecución y túnel

Inicia el servidor en modo HTTP y usa ngrok para crear un túnel HTTPS público (requerido por ChatGPT):

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

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

Anota la URL pública proporcionada por ngrok (p. ej., https://xyz.ngrok-free.dev).

🔗 Cómo conectarse a ChatGPT

Para probar esta aplicación en ChatGPT, sigue estos pasos:

1. Habilita el modo desarrollador en ChatGPT (Configuración → Aplicaciones y conectores → Ajustes avanzados).

2. En Configuración → Conectores, haz clic en Crear.

3. Selecciona Streamable HTTP y pega tu URL de ngrok con la ruta /mcp: https://your-id.ngrok-free.dev/mcp

4. Nómbralo "Fluduro" y haz clic en Crear.

5. Añade el conector a un nuevo chat y escribe "Inicia el test."

🤖 Stack tecnológico

• Backend: Node.js con @modelcontextprotocol/sdk.

• LLM: Groq (Llama 3.3 70B) para generar preguntas y analizar rasgos.

• Frontend: HTML/CSS puro con Tailwind CSS (CDN) y Google Fonts.

• Tunelización: ngrok.

📖 Aprendizajes clave del SDK

• Puente window.openai: Aprendí a comunicar el iframe del widget con el host.

• Sincronización de tema: Usé openai:set_globals para hacer que la interfaz se adapte al modo oscuro/claro de ChatGPT.

• UI impulsada por herramientas: Aprendí a activar cambios en la interfaz a partir de las salidas de herramientas del modelo usando structuredContent.

Conclusión

Este proyecto sirvió como una introducción práctica a la creación de aplicaciones con aspecto nativo para el ecosistema de ChatGPT. Se centra en los conceptos básicos del registro de herramientas, la gestión de recursos y la administración del estado dentro del marco de trabajo de OpenAI Apps.

📸 Imágenes - Capturas de pantalla de referencia

PANTALLA DE BIENVENIDA - MODO CLARO

PANTALLA DE BIENVENIDA - MODO OSCURO

PANTALLA DEL TEST

PANTALLA DE RESULTADOS