typescript-mcp

Cloudflare Workers 上の TypeScript MCP サーバー

TypeScript を使用して、本番環境に対応した Model Context Protocol（MCP）サーバーを構築し、Cloudflare Workers にデプロイします。このスキルでは、公式の @modelcontextprotocol/sdk、HTTP トランスポートの設定、認証パターン、Cloudflare サービスとの連携、包括的なエラー防止策について説明します。

---

このスキルを使う場面

次のような場合に、このスキルを使用してください：

• MCP サーバーを構築して、API、ツール、データを LLM に公開する
• Cloudflare Workers にサーバーレス MCP エンドポイントをデプロイする
• 外部 API（REST、GraphQL、データベース）を MCP ツールとして連携する
• エッジデプロイ向けのステートレス MCP サーバーを作成する
• MCP プロトコル経由でCloudflare サービス（D1、KV、R2、Vectorize）を公開する
• API キー、OAuth、Zero Trust を使用して認証付き MCP サーバーを実装する
• リソースとプロンプトを備えた複数ツール対応の MCP サーバーを構築する
• よくある MCP エラーを防止する本番環境対応テンプレートが必要である

次のような場合は、このスキルを使用しないでください：

• Python MCP サーバーを構築する場合（代わりに FastMCP スキルを使用してください）
• WebSockets を使用するステートフルエージェントが必要な場合（Cloudflare Agents SDK を使用してください）
• SQLite ストレージを使用する長時間実行される永続エージェントが必要な場合（Durable Objects を使用してください）
• ローカルの CLI ツールを構築する場合（HTTP ではなく stdio トランスポートを使用してください）

---

安全なインストール

MCP サーバーパッケージは LLM にツールへのアクセスを許可するため、SDK が侵害されるとシステム全体の制御が露出する可能性があります。インストール前にパッケージを検証してください。サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロックする — npm config set ignore-scripts true（Bun はデフォルトで無効）
• クールダウン期間を設ける — 新しいパッケージバージョンがコミュニティによって検証されるまで、7 日間待ちます
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

Socket CLI との連携、クールダウンの設定、ロックファイルの検証、CI での適用を含むセキュリティ設定の全容については、dependency-upgrade スキルを読み込んでください。

基本概念

MCP プロトコルの構成要素：

1. ツール - LLM が呼び出せる関数（Zod スキーマ、非同期ハンドラー、外部 API）
2. リソース - データの公開（URI ベース：config://app、user://{userId}）
3. プロンプト - LLM とのやり取りに使用する事前設定済みテンプレート
4. 補完 - 引数のオートコンプリート（任意）

---

クイックスタート

1. 依存関係をインストールする

bun add @modelcontextprotocol/sdk hono zod
bun add -d @cloudflare/workers-types wrangler typescript

2. 基本的な MCP サーバーを作成する

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { Hono } from 'hono';
import { z } from 'zod';

const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });

// Register a tool
server.registerTool(
  'echo',
  {
    description: 'Echoes back the input text',
    inputSchema: z.object({ text: z.string().describe('Text to echo') })
  },
  async ({ text }) => ({ content: [{ type: 'text', text }] })
);

// HTTP endpoint
const app = new Hono();

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  // CRITICAL: Close transport to prevent memory leaks
  c.res.raw.on('close', () => transport.close());

  await server.connect(transport);
  await transport.handleRequest(c.req.raw, c.res.raw, await c.req.json());
  return c.body(null);
});

export default app;

3. デプロイする

wrangler deploy

4. 本番環境対応テンプレートを使用する

完全な実装については、templates/ ディレクトリからコピーしてください：

• templates/basic-mcp-server.ts - 最小構成の動作するサーバー
• templates/tool-server.ts - 複数のツール（API 連携、計算）
• templates/resource-server.ts - 静的および動的リソース
• templates/full-server.ts - 完全なサーバー（ツール + リソース + プロンプト）
• templates/authenticated-server.ts - API キー認証による本番環境向けセキュリティ
• templates/wrangler.jsonc - Cloudflare Workers の設定

---

認証パターン

簡単な例 - API キー認証（最も一般的）：

app.use('/mcp', async (c, next) => {
  const authHeader = c.req.header('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }

  const apiKey = authHeader.replace('Bearer ', '');
  const isValid = await c.env.MCP_API_KEYS.get(`key:${apiKey}`);
  if (!isValid) return c.json({ error: 'Invalid API key' }, 403);

  await next();
});

認証ガイドの全容については：本番環境向けの認証を実装する際に、references/authentication-guide.md を読み込んでください。5 つの方式を扱っています：API キー（推奨）、Cloudflare Zero Trust Access、OAuth 2.0、カスタム JWT、mTLS。セキュリティのベストプラクティス、テスト戦略、移行ガイドも含まれています。

---

Cloudflare サービスとの連携

簡単な例 - D1 データベースツール：

server.registerTool(
  'query-database',
  {
    description: 'Executes SQL query on D1 database',
    inputSchema: z.object({
      query: z.string(),
      params: z.array(z.union([z.string(), z.number()])).optional()
    })
  },
  async ({ query, params }, env) => {
    const result = await env.DB.prepare(query).bind(...(params || [])).all();
    return { content: [{ type: 'text', text: JSON.stringify(result.results, null, 2) }] };
  }
);

対応サービス：D1（SQL データベース）、KV（キー・バリューストア）、R2（オブジェクトストレージ）、Vectorize（ベクトルデータベース）、Workers AI、Queues、Analytics Engine。

連携ガイドの全容については：Cloudflare サービスを連携する際に、references/cloudflare-integration.md を読み込んでください。設定、MCP ツールの例、ベストプラクティス、高度なパターン（RAG システム、複数サービスの組み合わせ）を含みます。

---

テスト戦略

クイックテストワークフロー：

1. ユニットテスト（Vitest）：ツールのロジックを個別にテストします
2. 統合テスト（MCP Inspector）：bunx @modelcontextprotocol/inspector を使ってテストします
3. E2E テスト：実際の MCP クライアントを使ってテストします

# Local dev
npm run dev

# Test with Inspector
bunx @modelcontextprotocol/inspector

テストガイド全体：テストを作成する際は、references/testing-guide.md を読み込んでください。Vitest を使ったユニットテスト、MCP Inspector を使った統合テスト、E2E テスト、認証テスト、Artillery を使った負荷テスト、外部 API のモック、CI/CD のテストパターンについて説明しています。

---

既知の問題の防止

このスキルは、文書化された 13 件のエラーを防ぎます。特に重大な上位 5 件を以下に示します。

問題 #1：エクスポート構文の問題（重大）

エラー："Cannot read properties of undefined (reading 'map')" 発生元：honojs/hono#3955 防止策：

// ❌ WRONG                      // ✅ CORRECT
export default { fetch: app.fetch };    export default app;

問題 #2：トランスポート接続が閉じられない

エラー：メモリーリーク、接続がハングする 防止策：

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport({...});
  c.res.raw.on('close', () => transport.close()); // CRITICAL
  // ... handle request
});

問題 #3：ツールスキーマの検証失敗

エラー：ListTools request handler fails to generate inputSchema 発生元：modelcontextprotocol/typescript-sdk#1028 防止策：Zod スキーマを直接渡します。SDK が自動的に変換します

server.registerTool('tool', { inputSchema: z.object({...}) }, handler);

問題 #4：ツールの引数がハンドラーに渡されない

エラー：ハンドラーが undefined の引数を受け取る 発生元：modelcontextprotocol/typescript-sdk#1026 防止策：型安全なハンドラーパラメーターには z.infer<typeof schema> を使います

問題 #5：CORS の設定ミス

エラー：ブラウザーのクライアントが接続できない 防止策：

import { cors } from 'hono/cors';
app.use('/mcp', cors({ origin: ['http://localhost:3000'], allowMethods: ['POST', 'OPTIONS'] }));

エラー一覧全体：デバッグ時は references/common-errors.md を読み込んでください。13 件すべてのエラーについて、詳細な解決策、GitHub の Issue に基づく根本原因、デバッグ用チェックリストを説明しています。

---

デプロイワークフロー

クイックデプロイ：

# Local development
npm run dev  # Server at http://localhost:8787/mcp

# Production
npm run build
wrangler deploy

# Specific environment
wrangler deploy --env production

デプロイガイド全体：本番環境を設定する際は、references/deployment-guide.md を読み込んでください。環境の設定（dev／staging／prod）、複数環境、カスタムドメイン、GitHub Actions を使った CI/CD、データベースのマイグレーション、監視とログ、ロールバック戦略、パフォーマンスの最適化、ヘルスチェック、コストの最適化、セキュリティチェックリスト、トラブルシューティングについて説明しています。

---

パッケージのバージョン（2025-10-28 検証済み）

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.2",
    "@cloudflare/workers-types": "^4.20251011.0",
    "hono": "^4.10.1",
    "zod": "^4.1.12"
  },
  "devDependencies": {
    "@cloudflare/vitest-pool-workers": "^0.5.29",
    "vitest": "^3.0.0",
    "wrangler": "^4.43.0",
    "typescript": "^5.7.0"
  }
}

---

Cloudflare Agents SDK を使うべきケース

次の要件がある場合は、Cloudflare Agents MCP を使います。

• 永続ストレージ（最大 1GB の SQLite）を備えたステートフルなエージェント
• リアルタイムの双方向通信のための WebSocket サポート
• 会話履歴を保持する長時間実行セッション
• Durable Objects のアラームを使ったスケジュール済みエージェントタスク
• 自動的な状態レプリケーションを伴うグローバルな分散

次の要件がある場合は、**このスキル（スタンドアロンの TypeScript MCP）**を使います。

• ステートレスなツールと API 統合
• コールドスタートのレイテンシーを最小限に抑えたエッジデプロイ
• シンプルな認証（API キー、OAuth）
• リクエストごとの従量課金（Durable Objects のオーバーヘッドなし）
• 最大限の移植性（Cloudflare だけでなく、あらゆるプラットフォームで動作）

詳細な比較については、references/cloudflare-agents-vs-standalone.md を参照してください。

---

リファレンスを読み込むタイミング

TypeScript MCP サーバーの特定の側面に取り組む際は、リファレンスファイルを読み込みます。

authentication-guide.md

次の場合に読み込みます。

• セットアップに基づく作業：本番 MCP サーバーの認証を実装する
• 方式に基づく作業：API Key、OAuth 2.0、Zero Trust、JWT、mTLS のいずれかを選ぶ
• セキュリティに基づく作業：レート制限、API キーのローテーション、監査ログを実装する
• テストに基づく作業：認証テスト（ユニット、統合、E2E）を作成する
• 移行に基づく作業：認証方式を別の方式にアップグレードする

cloudflare-agents-vs-standalone.md

次の場合に読み込みます。

• 選択に基づく作業：スタンドアロン MCP と Cloudflare Agents SDK のどちらかを選ぶ
• アーキテクチャに基づく作業：ステートフルなエージェントとステートレスなツールのどちらが必要かを判断する
• コストに基づく作業：低トラフィック／高トラフィックのシナリオで料金を比較する
• 機能に基づく作業：WebSocket、永続ストレージ、スケジュール済みタスクが必要かを判断する
• 移行に基づく作業：スタンドアロンから Agents SDK へ、またはその逆へ移行する

cloudflare-integration.md

次の場合に読み込みます：

• サービスベース：D1、KV、R2、Vectorize、Workers AI、Queues、Analytics Engine を統合する場合
• パターンベース：RAG システムまたは複数サービスを使用するアプリケーションを構築する場合
• セットアップベース：Cloudflare サービスの wrangler.jsonc バインディングを設定する場合
• 例ベース：特定のサービス統合に使用できるコードが必要な場合

common-errors.md

次の場合に読み込みます：

• エラーベース：ドキュメントに記載された 13 個のエラーのいずれかが発生した場合
• デバッグベース：サーバーが動作しない場合、または体系的なデバッグチェックリストが必要な場合
• 予防ベース：デプロイ前に既知の問題をすべて防ぎたい場合
• ソースベース：特定のエラーに関する GitHub issue の参照が必要な場合

deployment-guide.md

次の場合に読み込みます：

• CI/CD ベース：自動デプロイ用に GitHub Actions を設定する場合
• 環境ベース：ステージング環境と本番環境を設定する場合
• 移行ベース：CI/CD で D1 データベースのマイグレーションを実行する場合
• モニタリングベース：ログ、分析、ヘルスチェックを設定する場合
• 最適化ベース：キャッシュ、パフォーマンスの最適化、コスト削減を実装する場合

testing-guide.md

次の場合に読み込みます：

• テストベース：単体テスト、統合テスト、E2E テストを作成する場合
• ツールベース：テストに Vitest、MCP Inspector、Artillery を使用する場合
• CI/CD ベース：GitHub Actions で自動テストを設定する場合
• 認証ベース：認証ミドルウェアをテストする場合
• 負荷ベース：MCP サーバーのエンドポイントで負荷テストが必要な場合

tool-patterns.md

次の場合に読み込みます：

• パターンベース：外部 API ラッパー、データベースクエリ、ファイル操作を実装する場合
• 例ベース：本番環境でテスト済みのツール実装例が必要な場合
• アーキテクチャベース：複数ステップの処理、ストリーミングレスポンス、キャッシュを使用するツールを構築する場合
• エラーベース：ツールのエラー処理に関するベストプラクティスが必要な場合
• レスポンスベース：ツールのレスポンス形式を理解する場合

---

バンドルされたリソースの使用

テンプレート（templates/）：本番環境に対応した実装

• basic-mcp-server.ts - 最小限の実用サーバー
• tool-server.ts - 複数のツール（API 統合）
• resource-server.ts - 静的および動的リソース
• full-server.ts - 完全なサーバー（ツール＋リソース＋プロンプト）
• authenticated-server.ts - 本番環境向けセキュリティ
• wrangler.jsonc - Cloudflare Workers の設定

リファレンスガイド（references/）：包括的なドキュメント（上記の「リファレンスを読み込むタイミング」セクションを参照）

• tool-patterns.md - 実装パターン
• authentication-guide.md - 5 種類すべての認証方法
• testing-guide.md - 単体テスト、統合テスト、E2E テスト
• deployment-guide.md - CI/CD、環境、モニタリング
• cloudflare-integration.md - D1、KV、R2、Vectorize、Workers AI
• common-errors.md - 13 個すべてのエラーとデバッグ
• cloudflare-agents-vs-standalone.md - 判断マトリクス

スクリプト（scripts/）：自動化ツール

• init-mcp-server.sh - 新しいプロジェクトを初期化
• test-mcp-connection.sh - サーバーの接続性をテスト

---

公式ドキュメント

• MCP 仕様：https://spec.modelcontextprotocol.io/
• TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hono フレームワーク：https://hono.dev/
• Context7 ライブラリ ID：/websites/modelcontextprotocol（利用可能な場合）

サーバーの例：

• 公式の例：https://github.com/modelcontextprotocol/servers
• Cloudflare MCP サーバー：https://github.com/cloudflare/mcp-server-cloudflare

---

重要なルール

必ず行うこと： ✅ レスポンス終了時にトランスポートを閉じる | ✅ export default app 構文を使用する | ✅ 認証を実装する | ✅ レート制限を追加する | ✅ Zod スキーマを使用する | ✅ MCP Inspector でテストする | ✅ SDK v1.20.2+ に更新する | ✅ すべてのツールをドキュメント化する | ✅ エラーを適切に処理する | ✅ 環境変数を使用する

決して行わないこと： ❌ オブジェクトラッパーでエクスポートする | ❌ トランスポートを閉じ忘れる | ❌ 認証なしでデプロイする | ❌ 環境変数をログに記録する | ❌ CommonJS を使用する | ❌ CORS 設定を省略する | ❌ 認証情報をハードコードする | ❌ 生のエラーを返す | ❌ テストせずにデプロイする | ❌ 古い SDK を使用する

---

セットアップの完全チェックリスト

このチェックリストを使って、MCP サーバーのセットアップを確認してください。

• SDK のバージョンが 1.20.2 以降である
• エクスポート構文が正しい（オブジェクトラッパーではなく、直接エクスポートしている）
• レスポンス終了時にトランスポートが閉じられる
• 認証が実装されている（本番環境の場合）
• レート制限が設定されている（外部公開する場合）
• CORS ヘッダーが設定されている（ブラウザのクライアントを使用する場合）
• すべてのツールに明確な説明と Zod スキーマがある
• シークレットに環境変数が使用されている
• wrangler.jsonc に必要なバインディングがすべて含まれている
• wrangler dev によるローカルテストが成功する
• MCP Inspector が接続し、ツール一覧を取得できる
• 本番環境へのデプロイが成功する
• すべてのツール／リソースが期待どおりのレスポンスを返す

---

本番環境の例

このスキルは、以下のパターンに基づいています。

• 公式 MCP TypeScript SDK の例：https://github.com/modelcontextprotocol/servers
• Cloudflare MCP サーバー：https://github.com/cloudflare/mcp-server-cloudflare
• エラー：0 件（既知の問題 10 件以上をすべて防止）
• トークン削減量：手動で実装する場合と比べて約 70%
• 検証：✅ すべてのテンプレートを Cloudflare Workers 上でテスト済み

---

質問や問題がありますか？

1. トラブルシューティングについては、references/common-errors.md を確認してください
2. クイックスタートのセクションにあるすべての手順を確認してください
3. MCP Inspector でテストしてください：bunx @modelcontextprotocol/inspector
4. 公式ドキュメントを確認してください：https://spec.modelcontextprotocol.io/
5. SDK のバージョンが 1.20.2 以降であることを確認してください

---

最終更新日：2025-10-28 SDK バージョン：@modelcontextprotocol/[email protected] メンテナー：Claude Skills Repository