React MCP SPA

1つのHTMLブロブにバンドルされ、MCP Appsサーバーによって提供される最小限のReactシングルページアプリケーションです。このSPAはURLパスルーティングを使用せず、MCPホストコンテキストから現在のツール名を読み取ることで、どのページをレンダリングするかを決定します。

レイアウト

• packages/ui/ — React + Vite SPA。vite-plugin-singlefileを使用して単一ファイルのHTMLブロブにビルドされます。

• packages/mcp/ — @modelcontextprotocol/ext-apps/serverを使用したMCPサーバー。すべて同じ ui:// リソースを指すツール（show-home、show-counter、show-profile）を登録します。

• packages/playground/ — hostContext と toolResult のJSON入力を備えたモックチャットUI内でSPAをレンダリングする開発専用のハーネス。MCPホストなしでページを試すことができます。

インストール

Node.js ≥ 20 および pnpm ≥ 9 が必要です。

pnpm install

UIを分離して開発する

pnpm run dev:ui

表示されたURL（例: http://localhost:5173）を開きます。SPAはMCPホストが存在しないことを検出し、各ページをプレビューできるようにルートピッカーを表示します。

プレイグラウンド — MCPなしでレンダリングをテストする

pnpm run dev:playground

http://localhost:5174 で開きます。プレイグラウンドはSPAの実際のルートレンダラー（packages/ui/src/Router.tsx の RouteRenderer）を再利用し、モックチャットUIでラップします。ヘッダーには2つのJSONテキストエリアがあります。1つは hostContext（toolInfo.tool.name を介してどのページをレンダリングするかを制御）、もう1つはページに渡される toolResult 用です。プリセットボタンで、登録済みの各ツール用に用意されたコンテキストと結果のペアを読み込むことができます。テキストエリアを編集すると、アシスタントのツール出力バブルがライブで再レンダリングされます。

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

stdioトランスポートの場合:

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

cloudflaredによるサーバーの公開

一部のMCPクライアント（ホスト型を含む）はlocalhostに到達できません。 cloudflared を使用して、パブリックHTTPS URLを割り当てるクイックトンネルを開きます。

OSのパッケージマネージャーを使用してcloudflaredをインストールします:

# 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

ローカルでサーバーを起動します:

pnpm run serve:mcp

別のターミナルで以下を実行します:

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

cloudflared は https://<random>.trycloudflare.com のようなURLを出力します。末尾に /mcp を追加し、それをMCPサーバーのURLとして使用します:

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

トンネルは cloudflared を終了するまで維持されます。安定したホスト名が必要な場合は、クイックトンネルではなく 名前付きCloudflareトンネル を設定してください。

Claude Desktop拡張機能（.mcpb）としてのパッケージ化

このリポジトリには、Claude Desktop用のインストール可能な MCP Bundle を生成するパッカーが同梱されています。この拡張機能はサーバーをstdio経由で実行するため、トンネルは不要です。

pnpm run pack:mcpb

これにより両方のパッケージがビルドされ、コンパイル済みのサーバー + UI HTML + プロダクション用 node_modules が build/mcpb-staging/ 配下にステージングされ、mcpb pack が呼び出されて以下が生成されます:

build/react-mcp-spa.mcpb

インストールするには、Finder/エクスプローラーで .mcpb をダブルクリック（またはClaude Desktopにドラッグ）します。Claudeがマニフェストを検証してサーバーを登録します。インストール後、3つのツール（show-home、show-counter、show-profile）が利用可能になり、それぞれがインラインReact UIとしてページをレンダリングします。

バンドルマニフェストは mcpb/manifest.json にあります。新しい拡張機能をリリースする際は、そこで（および packages/mcp/package.json で）version を更新してください。

ルーティングの仕組み

SPAは window.location を読み取りません。代わりに、packages/ui/src/App.tsx が @modelcontextprotocol/ext-apps/react の useApp() を使用して以下を行います:

1. app.getHostContext().toolInfo.tool.name を読み取り、ホストがどのツールを呼び出したか（これが「ルート」になります）を把握します。

2. app.ontoolresult をサブスクライブしてサーバーから CallToolResult を受け取り、データとしてページに渡します。

3. app.onhostcontextchanged を監視し、テーマ、セーフエリア、ロケールの更新が正しく再レンダリングされるようにします。

新しいページを追加するには、2段階の変更が必要です:

1. packages/mcp/src/server.ts で、_meta.ui.resourceUri が共有リソース ui://react-mcp-spa/app.html を指すようにツールを登録します。

2. packages/ui/src/App.tsx 内の renderRoute() に、そのツール名のケースを追加します。