React MCP SPA

Una aplicación de página única (SPA) de React minimalista que se empaqueta en un único blob HTML y es servida por un servidor de MCP Apps. La SPA no utiliza enrutamiento de rutas URL; elige qué página renderizar leyendo el nombre de la herramienta actual desde el contexto del host MCP.

Estructura

• packages/ui/ — SPA de React + Vite, compilada en un blob HTML de un solo archivo mediante vite-plugin-singlefile.

• packages/mcp/ — Servidor MCP que utiliza @modelcontextprotocol/ext-apps/server. Registra herramientas (show-home, show-counter, show-profile) que apuntan todas al mismo recurso ui://.

• packages/playground/ — Entorno de desarrollo que renderiza la SPA dentro de una interfaz de chat simulada con entradas JSON para hostContext y toolResult, para que las páginas puedan probarse sin un host MCP.

Instalación

Requiere Node.js ≥ 20 y pnpm ≥ 9.

pnpm install

Desarrollar la interfaz de usuario de forma aislada

pnpm run dev:ui

Abra la URL impresa (por ejemplo, http://localhost:5173). La SPA detecta que no hay un host MCP y muestra un selector de rutas para que pueda previsualizar cada página.

Playground — probar el renderizado sin MCP

pnpm run dev:playground

Se abre en http://localhost:5174. El playground reutiliza el renderizador de rutas real de la SPA (RouteRenderer de packages/ui/src/Router.tsx) y lo envuelve en una interfaz de chat simulada. El encabezado tiene dos áreas de texto JSON: una para el hostContext (que determina qué página se renderiza mediante toolInfo.tool.name) y otra para el toolResult pasado a la página. Los botones preestablecidos cargan pares de contexto+resultado listos para cada herramienta registrada; las ediciones en cualquiera de las áreas de texto vuelven a renderizar en vivo la burbuja de salida de la herramienta del asistente.

Compilar y ejecutar el servidor MCP

pnpm run build       # builds packages/ui → dist/index.html, then packages/mcp
pnpm run serve:mcp   # starts Streamable HTTP server on http://localhost:3001/mcp

Para transporte stdio:

pnpm --filter @react-mcp-spa/mcp run serve:stdio

Exponer el servidor con cloudflared

Algunos clientes MCP (incluidos los alojados) no pueden acceder a localhost. Utilice cloudflared para abrir un túnel rápido que asigne una URL HTTPS pública.

Instale cloudflared a través del gestor de paquetes de su sistema operativo:

# macOS (Homebrew)
brew install cloudflared

# Linux (Debian/Ubuntu)
# See https://pkg.cloudflare.com/ for the apt repo, or grab the .deb from
# https://github.com/cloudflare/cloudflared/releases

# Windows (winget)
winget install --id Cloudflare.cloudflared

Inicie el servidor localmente:

pnpm run serve:mcp

En otra terminal, ejecute:

cloudflared tunnel --url http://localhost:3001
# or: pnpm run tunnel

cloudflared imprime una URL como https://<random>.trycloudflare.com. Añada /mcp y utilícela como la URL de su servidor MCP:

https://<random>.trycloudflare.com/mcp

El túnel permanece activo hasta que cierre cloudflared. Para obtener un nombre de host estable, configure un túnel de Cloudflare con nombre en lugar de un túnel rápido.

Empaquetado como una extensión de Claude Desktop (.mcpb)

El repositorio incluye un empaquetador que produce un MCP Bundle instalable para Claude Desktop. La extensión ejecuta el servidor a través de stdio; no se requiere túnel.

pnpm run pack:mcpb

Esto compila ambos paquetes, prepara el servidor compilado + HTML de la interfaz de usuario + node_modules de producción en build/mcpb-staging/, e invoca mcpb pack para producir:

build/react-mcp-spa.mcpb

Para instalarlo, haga doble clic en el archivo .mcpb en Finder/Explorer (o arrástrelo a Claude Desktop). Claude valida el manifiesto y registra el servidor; después de la instalación, las tres herramientas (show-home, show-counter, show-profile) estarán disponibles y cada una renderizará su página como una interfaz de usuario de React en línea.

El manifiesto del paquete se encuentra en mcpb/manifest.json — actualice la version allí (y en packages/mcp/package.json) al realizar una nueva versión de la extensión.

Cómo funciona el enrutamiento

La SPA nunca lee window.location. En su lugar, packages/ui/src/App.tsx utiliza useApp() de @modelcontextprotocol/ext-apps/react y:

1. Lee app.getHostContext().toolInfo.tool.name para saber qué herramienta invocó el host; esta es la "ruta".

2. Se suscribe a app.ontoolresult para recibir el CallToolResult del servidor y pasarlo a la página como datos.

3. Observa app.onhostcontextchanged para que las actualizaciones de tema / área segura / configuración regional se rendericen correctamente.

Añadir una nueva página es un cambio de dos pasos:

1. Registre una herramienta en packages/mcp/src/server.ts con _meta.ui.resourceUri apuntando al recurso compartido ui://react-mcp-spa/app.html.

2. Añada un caso para el nombre de la herramienta en renderRoute() dentro de packages/ui/src/App.tsx.