typescript-mcp

Cloudflare Workers 上的 TypeScript MCP サーバー

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

---

このスキルを使用する場面

次の場合にこのスキルを使用します：

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

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

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

---

基本概念

MCP プロトコルのコンポーネント

1. ツール - LLM が呼び出せる関数

• 入力／出力スキーマは Zod で定義します
• 非同期ハンドラーは構造化コンテンツを返します
• 外部 API、データベース、または計算処理を呼び出せます

2. リソース - 静的または動的なデータの公開

• URI ベースのアドレス指定（例：config://app/settings）
• テンプレートはパラメーターをサポートします（例：user://{userId}）
• テキスト、JSON、またはバイナリデータを返します

3. プロンプト - 事前設定済みのプロンプトテンプレート

• 再利用可能な会話のきっかけを提供します
• プレースホルダーや動的コンテンツを含められます
• LLM とのやり取りの標準化に役立ちます

4. 補完（任意）- 引数の自動補完

• ツール引数に有効な値を提案します
• 開発者エクスペリエンスを向上させます

---

クイックスタート

1. 基本的な MCP サーバーテンプレート

最小限の動作するサーバーには、basic-mcp-server.ts テンプレートを使用します。

// See templates/basic-mcp-server.ts
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 simple tool
server.registerTool(
  'echo',
  {
    description: 'Echoes back the input text',
    inputSchema: z.object({
      text: z.string().describe('Text to echo back')
    })
  },
  async ({ text }) => ({
    content: [{ type: 'text', text }]
  })
);

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

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

  // CRITICAL: Close transport on response end 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;

依存関係をインストールします：

npm install @modelcontextprotocol/sdk hono zod
npm install -D @cloudflare/workers-types wrangler typescript

デプロイします：

wrangler deploy

---

2. ツールサーバーテンプレート

複数のツール（API 統合、計算処理）を公開するには、tool-server.ts を使用します。

// Example: Weather API tool
server.registerTool(
  'get-weather',
  {
    description: 'Fetches current weather for a city',
    inputSchema: z.object({
      city: z.string().describe('City name'),
      units: z.enum(['metric', 'imperial']).default('metric')
    })
  },
  async ({ city, units }, env) => {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units}&appid=${env.WEATHER_API_KEY}`
    );
    const data = await response.json();

    return {
      content: [{
        type: 'text',
        text: `Temperature in ${city}: ${data.main.temp}°${units === 'metric' ? 'C' : 'F'}`
      }]
    };
  }
);

---

3. リソースサーバーテンプレート

データを公開するには、resource-server.ts を使用します。

import { ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';

// Static resource
server.registerResource(
  'config',
  new ResourceTemplate('config://app', { list: undefined }),
  { description: 'Application configuration' },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: 'application/json',
      text: JSON.stringify({ version: '1.0.0', features: ['tool1', 'tool2'] })
    }]
  })
);

// Dynamic resource with parameter
server.registerResource(
  'user-profile',
  new ResourceTemplate('user://{userId}', { list: undefined }),
  { description: 'User profile data' },
  async (uri, { userId }, env) => {
    const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();

    return {
      contents: [{
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(user)
      }]
    };
  }
);

---

4. 認証済みサーバーテンプレート

本番環境のセキュリティには、authenticated-server.ts を使用します。

import { Hono } from 'hono';

const app = new Hono();

// API Key authentication middleware
app.use('/mcp', async (c, next) => {
  const authHeader = c.req.header('Authorization');
  if (!authHeader || !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();
});

app.post('/mcp', async (c) => {
  // MCP server logic (user is authenticated)
  // ... transport setup and handling
});

---

認証パターン

パターン 1：API キー（ほとんどの場合に推奨）

設定：

1. KV 名前空間を作成します：wrangler kv namespace create MCP_API_KEYS
2. wrangler.jsonc に追加します：

{
  "kv_namespaces": [
    { "binding": "MCP_API_KEYS", "id": "YOUR_NAMESPACE_ID" }
  ]
}

実装：

async function verifyApiKey(key: string, env: Env): Promise<boolean> {
  const storedKey = await env.MCP_API_KEYS.get(`key:${key}`);
  return storedKey !== null;
}

キーを管理します：

# Add key
wrangler kv key put --binding=MCP_API_KEYS "key:abc123" "true"

# Revoke key
wrangler kv key delete --binding=MCP_API_KEYS "key:abc123"

パターン 2：Cloudflare Zero Trust Access

import { verifyJWT } from '@cloudflare/workers-jwt';

const jwt = c.req.header('Cf-Access-Jwt-Assertion');
if (!jwt) {
  return c.json({ error: 'Access denied' }, 403);
}

const payload = await verifyJWT(jwt, c.env.CF_ACCESS_TEAM_DOMAIN);
// User authenticated via Cloudflare Access

パターン 3：OAuth 2.0

OAuth の完全な実装については、references/authentication-guide.md を参照してください。

---

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)
      }]
    };
  }
);

Wrangler の設定：

{
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "..." }
  ]
}

KV ストレージツールの例

server.registerTool(
  'get-cache',
  {
    description: 'Retrieves cached value by key',
    inputSchema: z.object({ key: z.string() })
  },
  async ({ key }, env) => {
    const value = await env.CACHE.get(key);
    return {
      content: [{ type: 'text', text: value || 'Key not found' }]
    };
  }
);

R2 オブジェクトストレージツールの例

server.registerTool(
  'upload-file',
  {
    description: 'Uploads file to R2 bucket',
    inputSchema: z.object({
      key: z.string(),
      content: z.string(),
      contentType: z.string().optional()
    })
  },
  async ({ key, content, contentType }, env) => {
    await env.BUCKET.put(key, content, {
      httpMetadata: { contentType: contentType || 'text/plain' }
    });

    return {
      content: [{ type: 'text', text: `File uploaded: ${key}` }]
    };
  }
);

Vectorize 検索ツールの例

server.registerTool(
  'semantic-search',
  {
    description: 'Searches vector database',
    inputSchema: z.object({
      query: z.string(),
      topK: z.number().default(5)
    })
  },
  async ({ query, topK }, env) => {
    const embedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: query
    });

    const results = await env.VECTORIZE.query(embedding.data[0], {
      topK,
      returnMetadata: true
    });

    return {
      content: [{
        type: 'text',
        text: JSON.stringify(results.matches, null, 2)
      }]
    };
  }
);

---

テスト戦略

1. Vitest によるユニットテスト

import { describe, it, expect } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

describe('Calculator Tool', () => {
  it('should add two numbers', async () => {
    const server = new McpServer({ name: 'test', version: '1.0.0' });

    server.registerTool(
      'add',
      {
        description: 'Adds two numbers',
        inputSchema: z.object({
          a: z.number(),
          b: z.number()
        })
      },
      async ({ a, b }) => ({
        content: [{ type: 'text', text: String(a + b) }]
      })
    );

    // Test tool execution
    const result = await server.callTool('add', { a: 5, b: 3 });
    expect(result.content[0].text).toBe('8');
  });
});

インストール：

npm install -D vitest @cloudflare/vitest-pool-workers

実行：

npx vitest

2. MCP Inspector による統合テスト

# Run server locally
npm run dev

# In another terminal
npx @modelcontextprotocol/inspector

# Connect to: http://localhost:8787/mcp

3. Claude Agent SDK による E2E テスト

包括的なテストパターンについては、references/testing-guide.md を参照してください。

---

既知の問題の防止

このスキルは、公式の MCP SDK および Cloudflare リポジトリで報告されている、本番環境で発生する 10 件以上の問題を防ぎます。

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

エラー：「Cannot read properties of undefined (reading 'map')」 出典：honojs/hono#3955、honojs/vite-plugins#237 発生理由：Vite のビルドで誤ったエクスポート形式を使用すると、分かりにくいエラーが発生します 防止策：

// ❌ WRONG - Causes cryptic build errors
export default { fetch: app.fetch };

// ✅ CORRECT - Direct export
export default app;

Issue #2：未クローズのトランスポート接続

エラー：メモリーリーク、接続のハング 出典：SDK メンテナーによるベストプラクティス 発生する理由：リクエスト終了時に StreamableHTTPServerTransport をクローズしていない 予防策：

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport(/*...*/);

  // CRITICAL: Always close on response end
  c.res.raw.on('close', () => transport.close());

  // ... handle request
});

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

エラー：ListTools request handler fails to generate inputSchema 出典：GitHub modelcontextprotocol/typescript-sdk#1028 発生する理由：Zod スキーマが JSON Schema に適切に変換されていない 予防策：

// ✅ CORRECT - SDK handles Zod schema conversion automatically
server.registerTool(
  'tool-name',
  {
    inputSchema: z.object({ a: z.number() })
  },
  handler
);

// No need for manual zodToJsonSchema() unless custom validation

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

エラー：ハンドラーが undefined の引数を受け取る 出典：GitHub modelcontextprotocol/typescript-sdk#1026 発生する理由：登録時と呼び出し時のスキーマ型が一致していない 予防策：

const schema = z.object({ a: z.number(), b: z.number() });
type Input = z.infer<typeof schema>;

server.registerTool(
  'add',
  { inputSchema: schema },
  async (args: Input) => {
    // args.a and args.b properly typed and passed
    return { content: [{ type: 'text', text: String(args.a + args.b) }] };
  }
);

Issue #5：CORS の設定ミス

エラー：ブラウザクライアントが MCP サーバーに接続できない 出典：本番環境でよくある問題 発生する理由：HTTP トランスポートに必要な CORS ヘッダーがない 予防策：

import { cors } from 'hono/cors';

app.use('/mcp', cors({
  origin: ['http://localhost:3000', 'https://your-app.com'],
  allowMethods: ['POST', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization']
}));

Issue #6：レート制限がない

エラー：API の不正利用、DDoS の脆弱性 出典：本番環境のセキュリティに関するベストプラクティス 発生する理由：MCP エンドポイントにレート制限がない 予防策：

app.post('/mcp', async (c) => {
  const ip = c.req.header('CF-Connecting-IP');
  const rateLimitKey = `ratelimit:${ip}`;

  const count = await c.env.CACHE.get(rateLimitKey);
  if (count && parseInt(count) > 100) {
    return c.json({ error: 'Rate limit exceeded' }, 429);
  }

  await c.env.CACHE.put(
    rateLimitKey,
    String((parseInt(count || '0') + 1)),
    { expirationTtl: 60 }
  );

  // Continue...
});

Issue #7：TypeScript コンパイル時のメモリー問題

エラー：tsc のビルド中に Out of memory が発生する 出典：GitHub modelcontextprotocol/typescript-sdk#985 発生する理由：MCP SDK の依存関係ツリーが大きい 予防策：

# Add to package.json scripts
"build": "NODE_OPTIONS='--max-old-space-size=4096' tsc && vite build"

Issue #8：UriTemplate の ReDoS 脆弱性

エラー：悪意のある URI パターンによってサーバーがハングする 出典：GitHub modelcontextprotocol/typescript-sdk#965（セキュリティ） 発生する理由：URI テンプレートの解析における正規表現によるサービス拒否 予防策：SDK v1.20.2 以降に更新してください（修正が含まれています）

Issue #9：認証のバイパス

エラー：認証なしで MCP ツールにアクセスできる 出典：本番環境のセキュリティに関するベストプラクティス 発生する理由：認証がない、または適切に実装されていない 予防策：本番サーバーでは必ず認証を実装してください（「認証パターン」セクションを参照）

Issue #10：環境変数の漏えい

エラー：エラーメッセージやログにシークレットが露出する 出典：Cloudflare Workers のセキュリティに関するベストプラクティス 発生する理由：環境変数がログに記録される、またはレスポンスで返される 予防策：

// ❌ WRONG - Exposes secrets
console.log('Env:', JSON.stringify(env));

// ✅ CORRECT - Never log env objects
try {
  // ... use env.SECRET_KEY
} catch (error) {
  // Don't include env in error context
  console.error('Operation failed:', error.message);
}

---

デプロイワークフロー

ローカル開発

# Install dependencies
npm install

# Run locally with Wrangler
npm run dev
# or
wrangler dev

# Server available at: http://localhost:8787/mcp

本番デプロイ

# Build
npm run build

# Deploy to Cloudflare Workers
wrangler deploy

# Deploy to specific environment
wrangler deploy --env production

GitHub Actions による CI/CD

name: Deploy MCP Server
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm test

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

---

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

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.2",
    "@cloudflare/workers-types": "^4.20251011.0",
    "hono": "^4.10.1",
    "zod": "^3.23.8",
    "zod-to-json-schema": "^3.24.1"
  },
  "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 を参照してください。

---

同梱リソースの使用

テンプレート（templates/）

すべてのテンプレートは、本番環境で使用できる状態であり、Cloudflare Workers でテスト済みです。

• 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 の設定

Claude がこれらを使用する場面：新しい MCP サーバーを作成する際は、ユースケース（ツールのみ、リソースのみ、認証あり、またはすべての機能を備えたもの）に応じて適切なテンプレートをコピーしてください。

リファレンスガイド（references/）

高度なトピックに関する包括的なドキュメントです。

• references/tool-patterns.md - 一般的なツール実装パターン（API ラッパー、データベースクエリ、計算、ファイル操作）
• references/authentication-guide.md - すべての認証方式の詳細（API キー、OAuth 2.0、Zero Trust、JWT）
• references/testing-guide.md - ユニットテスト、MCP Inspector による統合テスト、Claude Agent SDK による E2E テスト
• references/deployment-guide.md - Wrangler のワークフロー、環境管理、GitHub Actions による CI/CD
• references/cloudflare-integration.md - D1、KV、R2、Vectorize、Workers AI、Queues、Durable Objects の使用方法
• references/common-errors.md - 10 件以上のエラーについて、詳細な解決策、根本原因、予防策を説明
• references/cloudflare-agents-vs-standalone.md - スタンドアロン MCP と Cloudflare Agents SDK のどちらを選ぶかを判断するためのマトリックス

Claude がこれらを読み込む場面：開発者が高度な実装の詳細、デバッグのサポート、またはアーキテクチャに関するガイダンスを必要とする際に読み込みます。

スクリプト（scripts/）

MCP サーバーの初期化とテストを自動化するスクリプトです。

• scripts/init-mcp-server.sh - 依存関係、wrangler 設定、テンプレートの選択を含む新しい MCP サーバープロジェクトを初期化します
• scripts/test-mcp-connection.sh - MCP サーバーへの接続をテストし、ツールとリソースのエンドポイントを検証します

Claude がこれらを使用する場面：新しいプロジェクトをセットアップする際や、接続の問題をデバッグする際に使用します。

---

公式ドキュメント

• 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）を使用する ✅ 本番用サーバーには認証を実装する ✅ API の不正利用を防ぐため、レート制限を追加する ✅ 型安全なツール定義には Zod スキーマを使用する ✅ 本番環境にデプロイする前に MCP Inspector でテストする ✅ セキュリティ修正を適用するため、SDK v1.20.2 以降に更新する ✅ すべてのツールにわかりやすい説明を記載する ✅ エラーを適切に処理し、意味のあるメッセージを返す ✅ シークレットには環境変数を使用する（ハードコードしない）

絶対に行わないこと

❌ オブジェクトでラップしてエクスポートする（export default { fetch: app.fetch }） ❌ StreamableHTTPServerTransport を閉じ忘れる ❌ 本番環境で認証なしにデプロイする ❌ 環境変数やシークレットをログに記録する ❌ CommonJS 形式を使用する（ES モジュールを使用する必要があります） ❌ ブラウザクライアント向けの CORS 設定を省略する ❌ API キーや認証情報をハードコードする ❌ 生のエラーオブジェクトを返す（機密データが漏えいする可能性があります） ❌ ツールやリソースをローカルでテストせずにデプロイする ❌ 既知の脆弱性がある古いバージョンの 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 でテストしてください：npx @modelcontextprotocol/inspector
4. 公式ドキュメントを確認してください：https://spec.modelcontextprotocol.io/
5. SDK のバージョンが 1.20.2 以降であることを確認してください

---

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