Cloudflare Remix Vite MCP

🚀 Remix 3 MCPデモ

このプロジェクトは、Cloudflare Workers上で動作し、ChatGPTのようなAIチャットインターフェイスに埋め込むことができる、対話型のMCP（Model Context Protocol）ウィジェットを構築する方法を実証しています。MCPと最新のWeb技術を組み合わせることで、AI会話の中で豊かで状態を持つ体験を作り出すことができることを示しています。

🎥 デモビデオ

ChatGPTで動作する電卓ウィジェットを見てみましょう。隠されたTRONのイースターエッグも含まれています。

https://github.com/user-attachments/assets/5df110d8-f40b-4c6a-8820-c2dbf3ff79c8

X/Twitterでデモを見る

🔍 デモの仕組み

🔧 アーキテクチャの概要

このデモでは、AIアシスタントによって呼び出すことができるMCPツールとして、電卓ウィジェットを実装しています。アーキテクチャはいくつかの重要なコンポーネントで構成されています。

1. MCPサーバー - Model Context Protocolを実装したCloudflare Durable Object
2. ウィジェットシステム - Remix 3で構築され、AIチャットに埋め込むことができる対話型のUIコンポーネント
3. 双方向通信 - ウィジェットはAIから初期状態を受け取り、メッセージを返すことができます
4. 静的アセット - CloudflareのCDNから提供されるウィジェットバンドル

🧮 電卓ウィジェット

この電卓は、Tronにインスパイアされたレトロフューチャーな美学を持つ、完全に機能する美しくスタイル付けされた電卓です。以下がその特徴です。

🛠️ 初期状態の設定

AIアシスタントが電卓ツールを呼び出すとき、初期状態のパラメータを渡すことができます。

• display - 初期表示値
• previousValue - すでに入力された値（例：「ある数に5を足したい」）
• operation - 保留中の演算（+、-、*、/）
• waitingForNewValue - 電卓が新しい入力を待っているかどうか
• errorState - エラー状態で開始するかどうか

これにより、AIはユーザーの要求に基づいて電卓を事前に設定することができます。たとえば、ユーザーが「何かに5を足したい」と言った場合、AIはpreviousValue: 5、operation: '+'、waitingForNewValue: trueで電卓を呼び出すことができます。

🖥️ 対話型UI

電卓ウィジェットは、完全に対話型のRemixアプリケーションです。

• JSX/TSXとCSS-in-JSスタイリングを使用してレンダリングされます
• キーボードショートカット（Enter、Escape、数字キー、演算子など）をサポートします
• アニメーション付きのローディングメッセージを持つTronスタイルの初期化シーケンスを備えています
• ユーザーが操作するとリアルタイムで更新されます
• Remix 3の実験的なDOMレンダラーを使用して効率的な更新を行います

🎁 イースターエッグ：マスターコントロールプログラム

電卓には隠し機能があります。結果が1982（オリジナルのTron映画が公開された年）に等しくなったとき、電卓はAIアシスタントにMCPプロンプトメッセージを送信し、Tronのマスターコントロールプログラム（MCP）のペルソナを採用するよう指示します。

これは、ウィジェットがAIにメッセージを返すことで、会話を動的に影響を与える能力を示しています。

🛠️ 技術的な実装

🖥️ Durable Objectsを使用したMCPサーバー

MathMCPクラスはMcpAgentを拡張し、CloudflareのDurable Objectsを使用して状態を維持します。

export class MathMCP extends McpAgent<Env, State, Props> {
	server = new McpServer(
		{
			name: 'MathMCP',
			version: '1.0.0',
		},
		{
			instructions: `Use this server to solve math problems reliably and accurately.`,
		},
	)
	async init() {
		await registerTools(this)
		await registerWidgets(this)
	}
}

サーバーは2種類の機能を登録します。

1. ツール - サーバー側で算術演算を実行するdo_mathツール
2. ウィジェット - チャットに埋め込むことができる対話型のUIリソース

📝 ウィジェットの登録

ウィジェットは、MCPリソース（HTML/JSバンドル用）とMCPツール（呼び出し用）の両方として登録されます。登録には以下が含まれます。

• 入力スキーマ - ウィジェットが受け入れるパラメータを定義するZodスキーマ
• 出力スキーマ - ウィジェットが返すことができるものを定義するZodスキーマ
• HTMLバンドル - スクリプト参照付きのレンダリングされたHTML
• OpenAIメタデータ - ChatGPTにウィジェットを表示する方法を教える特別なメタデータ

agent.server.registerResource(name, uri, {}, async () => ({
	contents: [
		createUIResource({
			content: {
				type: 'rawHtml',
				htmlString: await widget.getHtml(),
			},
			metadata: {
				'openai/widgetDescription': widget.description,
				'openai/widgetCSP': {
					connect_domains: [],
					resource_domains: [baseUrl],
				},
			},
		}).resource,
	],
}))

🏗️ 別々のビルドプロセス

このプロジェクトは2つの別々のビルドプロセスを使用しています。

1. ウィジェットビルド (Vite) - 電卓UIをスタンドアロンのJavaScriptバンドルにビルドします

   • 入力: worker/widgets/calculator/index.tsx
   • 出力: dist/public/widgets/calculator.js
   • 形式: すべての依存関係がバンドルされたESモジュール

2. ワーカービルド (Wrangler) - MCPサーバー付きのCloudflare Workerをビルドします

   • 入力: worker/index.tsx
   • 出力: Cloudflareにデプロイされるワーカーバンドル
   • 含まれるもの: MCPプロトコルハンドラー、ツール登録、ウィジェット提供

📡 通信プロトコル

ウィジェットはpostMessageを使用して、親フレーム（AIチャットインターフェイス）と通信します。

• 初期化 - ウィジェットがマウントされるとui-lifecycle-iframe-readyを送信します
• レンダリングデータ - ウィジェットは初期状態を含むui-lifecycle-iframe-render-dataを受け取ります
• ツール呼び出し - ウィジェットはtoolメッセージを送信することで、他のMCPツールを呼び出すことができます
• プロンプト - ウィジェットはpromptメッセージを使用して、AIに新しいプロンプトを送信することができます
• リンク - ウィジェットはlinkメッセージを使用してリンクを開くことができます

// ウィジェットがAIにプロンプトを送信する
sendMcpMessage('prompt', { prompt: MCP_PROMPT })

// ウィジェットが初期レンダリングデータを待つ
const renderData = await waitForRenderData(renderDataSchema)

👤 ユーザー体験

ユーザーがChatGPTでこのMCPサーバーと対話するとき、以下のようなことが起こります。

1. ユーザーが質問する: "計算機を使えますか？"
2. ChatGPTがMCPを介してcalculatorツールを呼び出す
3. サーバーが応答する:
   • テキストコンテンツ: "計算機がレンダリングされました"
   • UIリソース: 初期状態付きの計算機HTML
   • 構造化コンテンツ: 現在の計算機状態
4. ChatGPTがiframeで計算機ウィジェットをレンダリングする
5. ウィジェットがロードされ、Tronスタイルの初期化シーケンスを表示した後、計算機が表示される
6. ユーザーが計算機と対話する（ボタンをクリックするかキーボードを使用する）
7. 結果が1982になった場合、ウィジェットがChatGPTにプロンプトを送信する
8. ChatGPTがMCPのペルソナを採用し、それに応じて応答する

🏃‍♂️ 自分で実行する方法

📋 前提条件

• Node.js (v18以上)
• npmまたはyarn
• Cloudflareアカウント（デプロイ用）

💻 ローカル開発

1. クローンとインストール

   npm install
   

2. 開発サーバーを起動する

   npm run dev
   

   これにより、2つのプロセスが同時に実行されます。

   • ウィジェットビルドをウォッチモードで実行する（Vite）
   • ローカルのDurable Objects付きのワーカーを実行する（Wrangler）

3. 計算機ウィジェットをテストする

   http://localhost:8787/__dev/widgetsにアクセスして、計算機ウィジェットを単独で確認します。

4. MCPインスペクターに接続する

   MCPインスペクターを使用してMCPサーバーをテストします。

   npm run inspect
   

   その後、インスペクターでhttp://localhost:8787/mcpに接続します。

🚀 デプロイ

1. 本番用にビルドする

   npm run build
   

2. Cloudflareにデプロイする

   npm run deploy
   

3. ChatGPTで使用する

   デプロイが完了したら、デプロイURL + /mcpエンドポイントを指定することで、このMCPサーバーをChatGPTに追加することができます。

📁 プロジェクト構造

├── worker/
│   ├── index.tsx              # メインワーカーのエントリポイント
│   ├── tools.ts               # MCPツールの定義 (do_math)
│   ├── widgets.tsx            # ウィジェット登録システム
│   ├── utils.ts               # CORSとユーティリティ関数
│   └── widgets/
│       ├── utils.ts           # ウィジェット通信ユーティリティ
│       └── calculator/
│           ├── index.tsx      # 計算機UIコンポーネント
│           ├── calculator.ts  # 計算機のビジネスロジック
│           └── mcp-prompt.ts  # MCPイースターエッグのプロンプト
├── dist/
│   └── public/
│       └── widgets/
│           └── calculator.js  # ビルドされた計算機バンドル
├── vite.config.widgets.ts     # ウィジェットビルド用のVite設定
└── wrangler.jsonc             # Cloudflare Workersの設定

⚙️ 主要な技術

• Cloudflare Workers - エッジコンピューティングプラットフォーム
• Durable Objects - ステートフルなコーディネーションプリミティブ
• Model Context Protocol - AIとサービス間の通信プロトコル
• Remix 3 - Reactフレームワーク（実験的なDOMレンダラー）
• Vite - ウィジェットバンドル用の高速ビルドツール
• Zod - TypeScriptファーストのスキーマバリデーション

🌐 環境と設定

wrangler.jsoncでは以下を設定します。

• Durable Objectのバインディング (MATH_MCP_OBJECT)
• ウィジェットバンドルを提供するためのアセットバインディング
• MCP SDKのNode.js互換性
• 本番環境でのモニタリング用のオブザーバビリティ

💡 開発のヒント

• ウィジェット開発: ウィジェットコードの変更は自動的にホットリロードされます
• ワーカーの変更: ファイルが変更されると、Wranglerがワーカーを再起動します
• 型安全性: npm run typecheckを実行してTypeScriptを検証します
• リンティング: npm run lintを実行してコードスタイルをチェックします

🙌 クレジット

このデモは、最新のWeb技術を展示しています。実験的なRemix 3の機能、MCPウィジェット、Cloudflareのエッジコンピューティングプラットフォームが含まれています。計算機のデザインは、独特のオレンジ色の光とレトロフューチャーなスタイルで、Tronの美学に敬意を表しています。