create-hono の `cloudflare-workers+vite` テンプレートで MCP サーバー開発時のエクスポートエラー

create-hono で cloudflare-workers+vite テンプレートを選択し、agents SDK を利用した MCP サーバーを開発する際、デプロイ時に特定のエラーが発生することがあります。

create-hono version 0.18.0
✔ Target directory mcp-hono
? Which template do you want to use?
  aws-lambda
  bun
  cloudflare-workers
❯ cloudflare-workers+vite

✘ [ERROR] Your Worker depends on the following Durable Objects, which are not exported in your entrypoint file: MyMCP.

この問題は cloudflare-workers+vite テンプレートに含まれるデフォルトの Vite 設定が、agents SDK を使用した MCP サーバークラスのエクスポートを適切に処理できないことが原因です。今回は、この問題の原因と効果的な解決策について解説します。

問題が発生する背景

テンプレート選択による影響

create-hono では複数のテンプレートが提供されており、それぞれ異なるビルド設定を持っています。

• cloudflare-workers：シンプルな構成で、基本的なビルド設定
• cloudflare-workers+vite：Vite を使用した高度な構成だが、複雑なビルド設定

cloudflare-workers+vite テンプレートは開発体験を向上させるために Vite の機能を活用していますが、agents SDK を使用した MCP サーバークラスのような特殊な Named Export を扱う際に問題が発生することがあります。

MCP サーバークラスの特殊性

agents SDK を使用した MCP サーバークラスは、通常の Web API とは異なる構造を持っています。MCP プロトコルの要求により、特定のメソッドやプロパティを持つ必要があり、これらが Durable Objects として適切にエクスポートされる必要があります。

興味深いのは、agents SDK を使用した MCP サーバークラスが TypeScript ソースコードでは正しく定義・エクスポートされているにも関わらず、cloudflare-workers+vite テンプレートのビルドプロセスでエクスポートが失われてしまうという現象が起こることです。

原因を探る

cloudflare-workers+vite テンプレートのデフォルト設定

cloudflare-workers+vite テンプレートには、以下のような複雑な Vite 設定が含まれています。

// vite.config.ts (テンプレートのデフォルト設定)
import build from '@hono/vite-build/cloudflare-workers'

export default defineConfig(({ command, isSsrBuild }) => {
  if (command === 'serve') {
    return { plugins: [ssrHotReload(), cloudflare()] }
  }
  if (!isSsrBuild) {
    return { /* client build config */ }
  }
  return {
    plugins: [build({ 
      outputDir: 'dist-server',
      entry: './src/index.tsx'
    })],
    // ...
  }
})

@hono/vite-build と agents SDK の相性問題

@hono/vite-build/cloudflare-workers プラグインは、agents SDK を使用した MCP サーバークラスのような特殊な Named Export を適切に処理できない場合があります。

これは MCP サーバー開発に特有の問題で、通常の Hono アプリケーション開発では発生しません。

解決策

選択肢1：テンプレートの変更を検討

MCP サーバー開発の場合、cloudflare-workers テンプレートを選択することで、この問題を回避できる可能性があります。

# 新しいプロジェクトの場合
npx create-hono mcp-server
# cloudflare-workers テンプレートを選択

選択肢2：Vite 設定の修正

既存のプロジェクトでは、@cloudflare/vite-plugin を使用するように設定を変更することで解決できます。

// vite.config.ts (修正後)
import { cloudflare } from '@cloudflare/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    cloudflare({
      viteEnvironment: {
        name: 'mcp_hono'
      }
    })
  ],
  build: {
    rollupOptions: {
      external: ['cloudflare:workers']
    }
  }
})

必要な依存関係

npm install @cloudflare/vite-plugin

動作確認の方法

ビルド後のファイルを確認して、MCP サーバークラスが正しくエクスポートされているかチェックしましょう。

# ビルド実行
npm run build

# MCP サーバークラスのエクスポート確認
grep -n "MyMCP" dist/mcp_hono/index.js

正しく設定されていれば、以下のような出力が表示されるはずです。

32688:class MyMCP extends McpAgent {
32750:app.mount("/sse", MyMCP.serve("/sse").fetch, { replaceRequest: false });
32751:app.mount("/mcp", MyMCP.serve("/mcp").fetch, { replaceRequest: false });
32761:  MyMCP,

まとめ

この問題は、create-hono の cloudflare-workers+vite テンプレートで agents SDK を使用した MCP サーバーを開発する際に発生する特有の問題です。テンプレートの選択時に cloudflare-workers を選ぶか、または @cloudflare/vite-plugin を使用した設定変更により解決できるでしょう。

この解決方法により、agents SDK を使用した MCP サーバーを Cloudflare Workers 上で正常にデプロイできるようになります。適切なテンプレート選択により、MCP サーバー開発の効率も向上し、より安定したデプロイプロセスを実現できるのではないでしょうか。