typescript-mcp-server-generator

TypeScript MCP サーバーを生成する

MCP TypeScript SDK v2 を使用して、以下の仕様で完全な Model Context Protocol (MCP) サーバーを TypeScript で作成します。

要件

1. プロジェクト構成: 適切なディレクトリ構成で新しい TypeScript/Node.js プロジェクトを作成する
2. NPM パッケージ: v1 のモノリシックな @modelcontextprotocol/sdk パッケージは廃止されました。用途別に分割された v2 パッケージを使用してください:
   • @modelcontextprotocol/server — サーバー実装(@modelcontextprotocol/server/stdio サブパス経由の stdio トランスポート)
   • @modelcontextprotocol/node — Node HTTP トランスポート(NodeStreamableHTTPServerTransport)、またはフレームワークアダプター: @modelcontextprotocol/express、@modelcontextprotocol/hono、@modelcontextprotocol/fastify — 各アダプターは、対応するピアフレームワークを一緒にインストールする必要があります(例: @modelcontextprotocol/express + express)
   • @modelcontextprotocol/core — 共有プロトコルスキーマ(*Schema 定数はここからインポートしてください。sdk/types.js からではありません)
   • zod@^4.2 — v2 では Zod 4.2+ が必要です。zod@3 は使用しないでください
3. ランタイム: Node.js 20+(v2 の最小要件)。ESM ファーストで "type": "module" を設定(CommonJS ビルドも同梱されているため、必要に応じて require() も動作します)
4. サーバータイプ: HTTP(Streamable HTTP トランスポート)または stdio ベースのサーバーから選択してください。SSE および WebSocket トランスポートは v2 で削除されたため、生成しないでください。
5. ツール: 適切なスキーマ検証を備えた、少なくとも 1 つの有用なツールを作成する
6. エラー処理: 包括的なエラー処理と検証を含める

実装の詳細

プロジェクトのセットアップ

• npm init で初期化し、package.json を作成する
• 依存関係をインストールする: @modelcontextprotocol/server、zod@^4.2、およびトランスポートパッケージ — 素の Node HTTP には @modelcontextprotocol/node、またはフレームワークアダプターとそのピアフレームワーク(例: npm install @modelcontextprotocol/express express)
• TypeScript を ES モジュールで構成する: package.json に "type": "module" を設定
• 開発用の dev 依存関係を追加する: tsx または ts-node
• 適切な .gitignore ファイルを作成する

サーバー構成

• 高レベル実装には @modelcontextprotocol/server の McpServer クラスを使用する
• サーバー名とバージョンを設定する
• 適切なトランスポートを選択する:
  • HTTP(Node): @modelcontextprotocol/node の NodeStreamableHTTPServerTransport
  • HTTP(Web 標準ランタイム): @modelcontextprotocol/server の WebStandardStreamableHTTPServerTransport
  • stdio: @modelcontextprotocol/server/stdio の StdioServerTransport
• HTTP の場合: 適切なミドルウェアとエラー処理を備えたフレームワークアダプター(@modelcontextprotocol/express など)を推奨します
• v2 では Web 標準の Headers/Request 型を使用することに注意してください。ヘッダーは ctx.http?.req?.headers.get('x-custom') で読み取ります

ツールの実装

• 設定オブジェクトを指定して registerTool() を使用します — v1 の可変引数の .tool() シグネチャは廃止されました:

  server.registerTool('greet', {
    description: 'Greet user',
    inputSchema: z.object({ name: z.string() })
  }, async ({ name }, ctx) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  });
  

• スキーマは完全な Zod オブジェクト(z.object({...}))である必要があります — 生の形状オブジェクト({ name: z.string() })は非推奨です
• 明確な title と description フィールドを指定する
• 結果には content と structuredContent の両方を返す
• ハンドラーの第 2 引数は構造化された ctx オブジェクトです(v1 の extra を置き換えます): ctx.mcpReq.signal、ctx.mcpReq.id、ctx.mcpReq.send(...)、ctx.mcpReq.notify(...)
• try-catch ブロックによる適切なエラー処理を実装する。v1 の McpError/StreamableHTTPError の代わりに、v2 のエラー階層(ProtocolError、SdkError、.status を持つ SdkHttpError)を使用してください
• 必要に応じて非同期操作をサポートする

リソース/プロンプトのセットアップ(任意)

• 動的 URI には ResourceTemplate とともに registerResource() を使用してリソースを追加する
• 引数スキーマとともに registerPrompt() を使用してプロンプトを追加する(registerTool() と同じ設定オブジェクトスタイル)
• より良い UX のために補完サポートの追加を検討してください。v2 の completable() ラッパーの順序に注意: completable(z.string(), callback).optional()(optional は外側に適用)

コード品質

• 型安全性のために TypeScript を使用する
• async/await パターンを一貫して使用する
• トランスポートのクローズイベントで適切なクリーンアップを実装する
• 設定には環境変数を使用する
• 複雑なロジックにはインラインコメントを追加する
• 関心の分離を明確にしたコード構成にする

検討すべきツールタイプの例

• データの処理と変換
• 外部 API との連携
• ファイルシステム操作（読み取り、検索、分析）
• データベースクエリ
• テキスト分析または要約（複数ラウンドの input_required パターンによる LLM 支援）
• システム情報の取得

設定オプション

• HTTP サーバーの場合:

  • 環境変数によるポート設定
  • ブラウザクライアント向けの CORS 設定
  • セッション管理（ステートレス vs ステートフル）
  • ローカルサーバー向けの DNS リバインディング保護
  • 厳格な Content-Type の扱い: v2 は application/json 以外の POST ボディを拒否します

• stdio サーバーの場合:

  • 適切な stdin/stdout の処理
  • 環境変数ベースの設定
  • プロセスのライフサイクル管理

既存の v1 サーバーの移行

• まず公式の codemod を実行します: npx @modelcontextprotocol/codemod@latest v1-to-v2 .
• 次に、手動での判断が必要な箇所（トランスポートの選択、ヘッダーの読み取り、エラー分類）について @mcp-codemod-error マーカーを検索します
• McpError + ErrorCode のチェックを新しいエラークラスに置き換えます。HTTP ステータスは error.code ではなく error.status に格納されるようになりました
• Server.createMessage()、listRoots()、sendLoggingMessage() および roots/sampling/logging のケイパビリティフィールドは v2 で非推奨です — 新しいコードでは使用しないでください

テストのガイダンス

• サーバーの実行方法を説明します（npm start または npx tsx server.ts）
• MCP Inspector のコマンドを記載します: npx @modelcontextprotocol/inspector
• HTTP サーバーの場合は、接続 URL を含めます: http://localhost:PORT/mcp
• ツール呼び出しの例を含めます
• よくある問題のトラブルシューティングのヒントを追加します

検討すべき追加機能

• 複数ラウンドの input_required パターン（非推奨の sampling サブシステムに代わる v2 の仕組み）を使用した LLM 活用ツール
• インタラクティブなワークフローのためのユーザー入力の引き出し
• 有効化/無効化機能を備えた動的ツール登録
• 一括更新のための通知デバウンス
• 効率的なデータ参照のためのリソースリンク

包括的なドキュメント、型安全性、エラー処理を備えた、完全で本番環境に対応した MCP サーバーを生成します。