React MCP SPA

Eine minimale React Single-Page-Anwendung, die in einen einzelnen HTML-Blob gebündelt und von einem MCP Apps-Server bereitgestellt wird. Die SPA verwendet kein URL-Pfad-Routing – sie wählt die zu rendernde Seite aus, indem sie den aktuellen Tool-Namen aus dem MCP-Host-Kontext liest.

Layout

• packages/ui/ — React + Vite SPA, erstellt als ein einzelner HTML-Blob mittels vite-plugin-singlefile.

• packages/mcp/ — MCP-Server unter Verwendung von @modelcontextprotocol/ext-apps/server. Registriert Tools (show-home, show-counter, show-profile), die alle auf dieselbe ui://-Ressource verweisen.

• packages/playground/ — Entwicklungs-Tool, das die SPA innerhalb einer Mock-Chat-UI mit JSON-Eingaben für hostContext und toolResult rendert, sodass Seiten ohne einen MCP-Host getestet werden können.

Installation

Erfordert Node.js ≥ 20 und pnpm ≥ 9.

pnpm install

Entwicklung der UI in Isolation

pnpm run dev:ui

Öffnen Sie die ausgegebene URL (z. B. http://localhost:5173). Die SPA erkennt, dass kein MCP-Host vorhanden ist, und zeigt eine Routenauswahl an, damit Sie jede Seite in der Vorschau ansehen können.

Playground — Rendering ohne MCP testen

pnpm run dev:playground

Öffnet sich unter http://localhost:5174. Der Playground verwendet den echten Routen-Renderer der SPA (RouteRenderer aus packages/ui/src/Router.tsx) und bettet ihn in eine Mock-Chat-UI ein. Der Header verfügt über zwei JSON-Textbereiche – einen für den hostContext (steuert über toolInfo.tool.name, welche Seite gerendert wird) und einen für das toolResult, das an die Seite übergeben wird. Preset-Schaltflächen laden fertige Kontext-Ergebnis-Paare für jedes registrierte Tool; Änderungen an einem der Textbereiche rendern die Tool-Ausgabe-Sprechblase des Assistenten live neu.

MCP-Server erstellen und ausführen

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

Für stdio-Transport:

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

Bereitstellung des Servers mit cloudflared

Einige MCP-Clients (einschließlich gehosteter) können localhost nicht erreichen. Verwenden Sie cloudflared, um einen schnellen Tunnel zu öffnen, der eine öffentliche HTTPS-URL zuweist.

Installieren Sie cloudflared über Ihren Betriebssystem-Paketmanager:

# 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

Starten Sie den Server lokal:

pnpm run serve:mcp

Führen Sie in einem anderen Terminal Folgendes aus:

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

cloudflared gibt eine URL wie https://<random>.trycloudflare.com aus. Hängen Sie /mcp an und verwenden Sie diese als Ihre MCP-Server-URL:

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

Der Tunnel bleibt bestehen, bis Sie cloudflared beenden. Für einen stabilen Hostnamen konfigurieren Sie einen benannten Cloudflare-Tunnel anstelle eines schnellen Tunnels.

Verpacken als Claude Desktop-Erweiterung (.mcpb)

Das Repo enthält einen Packer, der ein installierbares MCP Bundle für Claude Desktop erstellt. Die Erweiterung führt den Server über stdio aus – es ist kein Tunnel erforderlich.

pnpm run pack:mcpb

Dies erstellt beide Pakete, stellt den kompilierten Server + UI-HTML + Prod-node_modules unter build/mcpb-staging/ bereit und ruft mcpb pack auf, um Folgendes zu erzeugen:

build/react-mcp-spa.mcpb

Um es zu installieren, doppelklicken Sie auf die .mcpb im Finder/Explorer (oder ziehen Sie sie auf Claude Desktop). Claude validiert das Manifest und registriert den Server; nach der Installation sind die drei Tools (show-home, show-counter, show-profile) verfügbar und jedes rendert seine Seite als Inline-React-UI.

Das Bundle-Manifest befindet sich unter mcpb/manifest.json — erhöhen Sie dort (und in packages/mcp/package.json) die version, wenn Sie ein neues Erweiterungs-Release erstellen.

Funktionsweise des Routings

Die SPA liest niemals window.location. Stattdessen verwendet packages/ui/src/App.tsx useApp() aus @modelcontextprotocol/ext-apps/react und:

1. Liest app.getHostContext().toolInfo.tool.name, um zu wissen, welches Tool der Host aufgerufen hat – dies ist die "Route".

2. Abonniert app.ontoolresult, um das CallToolResult vom Server zu empfangen und es als Daten an die Seite zu übergeben.

3. Überwacht app.onhostcontextchanged, damit Aktualisierungen von Design / Safe-Area / Gebietsschema korrekt neu gerendert werden.

Das Hinzufügen einer neuen Seite ist eine Änderung in zwei Schritten:

1. Registrieren Sie ein Tool in packages/mcp/src/server.ts, wobei _meta.ui.resourceUri auf die gemeinsame ui://react-mcp-spa/app.html-Ressource verweist.

2. Fügen Sie einen Fall für den Tool-Namen in renderRoute() innerhalb von packages/ui/src/App.tsx hinzu.