Sneaker Carousel MCP App

Demo portable de MCP Apps para mostrar en Claude: carrusel de zapatillas, selección de talle/cantidad y botón de pago simulado.

Qué demuestra

• Un tool visible para el modelo: show-sneaker-carousel.
• Un recurso ui://sneaker-drop/carousel.html renderizado por el host.
• HTML, CSS y JavaScript empaquetados en un único archivo.
• Una llamada UI → host → servidor mediante app.callServerTool().
• Un tool privado para la UI: prepare-demo-checkout.
• Validación autoritativa de producto, talle y total en el servidor.
• Adaptación al tema y tipografías del host.

El pago es una simulación. No solicita tarjeta ni procesa dinero.

Ejecutar localmente

Requisitos: Node.js 20 o superior.

npm install
npm run build
npm start

Endpoint MCP:

http://localhost:3001/mcp

Health check:

http://localhost:3001/

Vista previa del carrusel sin un host MCP:

http://localhost:3001/preview

Probar con el basic-host oficial

En otra carpeta:

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
SERVERS='["http://localhost:3001/mcp"]' npm start

Abrí http://localhost:8080, elegí show-sneaker-carousel y ejecutá el tool.

Deploy con Docker

docker build -t sneaker-mcp-app .
docker run --rm -p 3001:3001 sneaker-mcp-app

Podés desplegar el Dockerfile en Railway, Render, Fly.io, Cloud Run o ECS. El servicio debe quedar públicamente accesible por HTTPS.

Ejemplo final:

https://tu-dominio.example/mcp

Conectarlo a Claude

1. Desplegá el proyecto con HTTPS.
2. En Claude abrí Customize / Connectors.
3. Elegí Add custom connector.
4. Pegá https://tu-dominio.example/mcp.
5. Para esta demo, seleccioná conexión sin autenticación si Claude ofrece esa opción.
6. En un chat, activá el conector y escribí:

Mostrame el carrusel de zapatillas y ayudame a elegir una.

Claude debería llamar show-sneaker-carousel y renderizar la MCP App dentro de la conversación.

Checkout externo opcional

Si definís:

DEMO_CHECKOUT_URL=https://example.com/checkout

el servidor devolverá esa URL y la MCP App pedirá al host abrirla. Para una integración real, generá una URL única de checkout en el backend y confirmá el pago por webhook. No confíes en el monto enviado por la interfaz.

Estructura

.
├── main.ts              # servidor HTTP/stdio
├── server.ts            # tools y recurso MCP App
├── mcp-app.html         # entrada de la UI
├── src/
│   ├── mcp-app.ts       # comportamiento del carrusel y checkout
│   └── styles.css       # estilos responsivos
├── Dockerfile
└── render.yaml

Solución de problemas

outputSchema no acepta z.object(...)

Esta versión usa @modelcontextprotocol/ext-apps 1.7.4 junto con el SDK MCP 1.29.0. Los helpers del servidor terminan delegando en la API Zod del SDK 1.x, por lo que los schemas de salida se pasan como shapes:

outputSchema: StoreOutputSchema.shape

root is possibly null

El elemento raíz se valida una vez y luego se guarda con tipo HTMLElement, de modo que TypeScript conserva el tipo dentro de callbacks.

Cannot find module dist/main.js

dist/main.js se genera recién cuando npm run build termina correctamente. Ejecutá:

rm -rf dist
npm run build
npm start

Avisos de npm audit

Los avisos de auditoría no causan los errores de compilación. Revisalos con:

npm audit
npm audit fix
npm run build

No ejecutes npm audit fix --force sin revisar los cambios, porque puede instalar actualizaciones mayores incompatibles.

Compatibilidad con Claude

La UI primero lee structuredContent. Como fallback de compatibilidad, también puede recuperar el catálogo y la orden desde un payload JSON marcado dentro de content. Esto permite que la demo siga renderizando en hosts que no reenvían structuredContent al iframe.