OpenAI Apps - ASCII Widget

Aplicación de demostración de un widget interactivo con OpenAI usando el protocolo MCP (Model Context Protocol). Este proyecto ahora muestra un generador de ASCII art en React (usando la librería figlet) que se puede visualizar dentro de ChatGPT con soporte de pantalla completa.

📋 Descripción

Este es un monorepo que implementa un servidor MCP con un widget de React integrado. El servidor sirve el widget, que permite escribir un texto y visualizarlo como ASCII art con distintas fuentes. También soporta cambiar a pantalla completa desde ChatGPT.

Características principales

• 🎨 Generador de ASCII art con selección de fuentes (Standard, Ghost, Slant, Big Chief, Doom, Star Wars)
• 🔌 Servidor MCP usando Express y el SDK oficial
• 🖥️ Botón de Pantalla Completa para una mejor visualización dentro de ChatGPT
• 🌓 Soporte para temas (claro/oscuro)
• 🚀 Monorepo con Turborepo para gestión eficiente

🏗️ Estructura del Proyecto

opeai-apps-hello/
├── apps/
│   ├── server/          # Servidor MCP con Express
│   │   ├── server.ts    # Lógica del servidor y definición del tool
│   │   └── package.json
│   └── web/             # Widget React
│       ├── src/
│       │   └── widget.tsx
│       ├── dist/        # Bundle compilado
│       └── package.json
├── packages/
│   └── config/          # Configuración compartida de TypeScript
│       └── tsconfig.base.json
├── turbo.json           # Configuración de Turborepo
└── package.json

Apps y Paquetes

• server: Servidor Express que implementa el protocolo MCP y sirve el widget
• web: Aplicación React que contiene el widget interactivo
• @repo/config: Configuración compartida de TypeScript para todo el monorepo

Todos los paquetes están escritos en TypeScript.

🚀 Inicio Rápido

Prerrequisitos

• Node.js >= 18
• pnpm 9.0.0 o superior

Instalación

1. Instalar dependencias:

pnpm install

2. Compilar el proyecto:

pnpm build

3. Iniciar en modo desarrollo:

pnpm dev

El servidor estará disponible en http://localhost:3030/mcp

🌐 Conectar con OpenAI usando ngrok

Para que ChatGPT pueda acceder a tu servidor local, necesitas exponerlo públicamente usando ngrok.

1. Instalar ngrok

Si no tienes ngrok instalado:

# Windows (usando Chocolatey)
choco install ngrok

# O descárgalo desde https://ngrok.com/download

2. Configurar ngrok

1. Crea una cuenta en ngrok.com
2. Obtén tu token de autenticación
3. Configura el token:

ngrok config add-authtoken TU_TOKEN_AQUI

3. Exponer el servidor

Con el servidor ejecutándose (pnpm dev), en otra terminal ejecuta:

ngrok http 3030

Ngrok te dará una URL pública como: https://abc123.ngrok-free.app

4. Agregar a OpenAI

1. Ve a ChatGPT
2. Abre la configuración de ChatGPT (ícono de tu perfil → Settings)
3. Ve a Apps & Connectors → Advanced settings activa el modo developer
4. Vuelve a Apps & Connectors y haz click en el nuevo boton Create
5. Agrega tu servidor MCP:
   • Name: ASCII Widget
   • Description: Generador de ASCII art con selector de fuentes
   • URL: https://abc123.ngrok-free.app/mcp
   • Authentication: No authentication

5. Probar el widget

Una vez configurado y abierto en ChatGPT, escribe tu texto en el input del widget y selecciona una fuente para ver el resultado en ASCII art. Puedes pulsar el botón "Ver en pantalla completa" para una experiencia mejorada.

⚠️ Nota: La URL de ngrok cambia cada vez que reinicias el túnel (en la versión gratuita). Para mantener una URL fija, considera usar el plan de pago de ngrok o usar un servicio alternativo.

📦 Comandos Disponibles

Desarrollo

# Ejecutar todos los proyectos en modo desarrollo
pnpm dev

# Desarrollar solo el servidor
pnpm --filter server dev

# Desarrollar solo el widget
pnpm --filter web dev

Construcción

# Compilar todo el monorepo
pnpm build

# Compilar solo el servidor
pnpm --filter server build

# Compilar solo el widget
pnpm --filter web build

Verificación de tipos

# Verificar tipos en todo el proyecto
pnpm typecheck

Limpieza

# Limpiar archivos generados
pnpm clean

🔧 Tecnologías Utilizadas

Backend

• Express: Servidor HTTP
• @modelcontextprotocol/sdk: SDK oficial de MCP
• Zod: Validación de esquemas
• TypeScript: Tipado estático

Frontend

• React 18: Librería de UI
• esbuild: Bundler ultrarrápido
• TypeScript: Tipado estático

Herramientas

• Turborepo: Orquestación del monorepo
• pnpm: Gestor de paquetes eficiente
• Prettier: Formateo de código

🎯 Cómo Funciona

1. El servidor MCP registra y sirve un recurso de tipo widget.
2. El widget React se compila con esbuild y se embebe en el HTML servido por el servidor.
3. El widget usa figlet para convertir el texto a ASCII art y permite:
   • Seleccionar distintas fuentes pre-cargadas
   • Cambiar el modo de visualización a pantalla completa

🌟 Funcionalidades del Widget

El widget incluye:

• Input de texto: Escribe el contenido a convertir en ASCII art
• Selector de fuente: Cambia entre varias fuentes disponibles (Standard, Ghost, Slant, Big Chief, Doom, Star Wars)
• Botón "Ver en pantalla completa": Cambia el modo de visualización a fullscreen
• Detección de tema: Se adapta a claro/oscuro

Nota: Para generar el ASCII art se utiliza la librería figlet y sus fuentes importables.

📝 Configuración

Variables de Entorno

Crea un archivo .env en apps/server/ si necesitas configurar variables:

PORT=3030

📄 Licencia

Este proyecto está licenciado bajo MIT. Consulta el archivo LICENSE para más detalles.

Atribución

Si usas este proyecto, por favor mantén los avisos de copyright y permiso e incluye una referencia al archivo NOTICE. Atribución sugerida:

“Este software incluye componentes de ‘OpenAI Apps - ASCII Widget’ por ivanlhz, con licencia MIT. Ver LICENSE y NOTICE para más detalles.”

🔗 Enlaces Útiles

• Documentación de MCP
• Documentación de Turborepo
• Documentación de React
• Documentación de Express