hono-todo

プロジェクト概要

hono-todo は Hono 製 MCP サーバーが Todo ウィジェットを提供するサンプルです。hono/jsx によるサーバーサイドレンダリングと hono/jsx/dom を用いたクライアント側の軽量インタラクションを組み合わせ、ChatGPT Apps SDK (Streamable HTTP) から Todo リストを表示・更新できます。

• MCP サーバー: @hono/mcp, @modelcontextprotocol/sdk
• サーバー側レンダリング: hono/jsx/dom/server
• クライアント: hono/jsx/dom Hooks + window.openai
• バンドラ: Vite (dist/manifest.json を参照)

セットアップ

事前に Bun をインストールしてください。

bun install

開発時は MCP サーバーと Vite を並行起動します。

# MCP サーバー (ホットリロード)
bun run dev:server

# クライアントバンドル (HMR)
bun run dev:client

本番用アセットは次で生成します。

bun run build:client

生成した dist/ を利用してサーバーを起動する場合は、別ターミナルで次を実行します。

NODE_ENV=production bun run start

ディレクトリ構成 (抜粋)

src/
  server.tsx               # Hono アプリと MCP サーバーのエントリ
  server/assets.ts         # Vite manifest / 開発時エントリの解決
  server/store.ts          # Zod スキーマとメモリ内 Todo ストア
  server/widget.tsx        # SSR 用 JSX テンプレート
  client/todo/main.tsx     # hono/jsx/dom でウィジェットをマウント
  client/todo/controller.tsx  # TodoApp コンポーネント (Hooks 実装)
  client/todo/types.ts     # 型定義と type guard
  styles/todo.css          # Todo ウィジェットのスタイル

サーバー実装のポイント

• src/server.tsx
  • /mcp に StreamableHTTPTransport をマウントし、MCP Server と接続。
  • Todo リスト表示・追加・トグルのツールとリソース (ui://widget/todo-list.html) を登録。
  • renderWidgetHtml(loadAssetMap()) で SSR 済み HTML を返却。
  • /assets/* で dist/ 配下のビルド成果物を配信。
• src/server/assets.ts
  • 開発時は VITE_DEV_SERVER_ORIGIN を利用し、HMR クライアントとモジュールを挿入。
  • 本番時は dist/manifest.json からエントリ JS/CSS を解決しキャッシュ。
• src/server/store.ts
  • Zod で入力検証を行い、メモリ内の Todo リストを管理。

クライアント実装のポイント

• src/client/todo/controller.tsx
  • useState, useEffect, useRef で TodoApp コンポーネントを構築。
  • window.openai.callTool を介して Todo 追加・トグルを実行。
  • openai:set_globals イベントでサーバーからの最新状態に追従。
• src/client/todo/main.tsx
  • 初期 structuredContent から Todo 配列を抽出して TodoApp に渡し、render() で #todo-root にマウント。

動作確認手順

1. bun run dev:server を起動。
2. 別ターミナルで bun run dev:client を起動し、Vite の HMR を有効化。
3. bunx @modelcontextprotocol/inspector http://localhost:3000/mcp を実行し、todo-list ツールを呼び出してウィジェット表示と操作を確認。

本番相当の挙動を確かめる場合は bunx vite build でバンドル後、NODE_ENV=production bun run start を実行して同様に検証してください。

補足情報

• SSR された HTML はシリアライズされた JSX 関数ではなくプレーンなマークアップを返すため、ChatGPT 上でもそのまま描画されます。
• Todo データはメモリ上で管理しているため、プロセス再起動で初期状態に戻ります。永続化が必要な場合は InMemoryTodoStore を差し替えてください。
• PORT 環境変数で待ち受けポートを変更できます (初期値 3000)。
• ChatGPT Apps SDK に接続する際は、HTTPS の公開エンドポイント (例: Cloudflare Tunnel / ngrok) を用意し /mcp を指定してください。