MCP Server Boilerplate (TypeScript)

MCP Server Boilerplate (TypeScript)

TypeScript を使用して Model Context Protocol（MCP）サーバーを構築するための、整理され、保守しやすく、拡張性の高いボイラープレートプロジェクトです。このボイラープレートは、開発を加速し、一貫性を促進するとともに、MCP 連携を作成するためのベストプラクティスを取り入れることを目的としています。

特長

• TypeScript： モダンで型安全な JavaScript です。
• MCP SDK： 公式の @modelcontextprotocol/sdk を使用します。
• 特化した実装： シンプルさと信頼性を重視し、stdio トランスポートのサポートに絞っています。
• プリミティブの例： 基本的な例が含まれています：
  • ツール：greet（設定可能なプレフィックス付きの挨拶）と add（シンプルな計算機）
  • リソース：welcome（ウェルカムメッセージのリソース）
  • プロンプト：summarize（トピックの要約プロンプト）
• 設定： .env ファイルと環境変数から設定を読み込みます（src/config.ts）。
• 検証： プリミティブの引数を堅牢に検証するために zod を使用します。
• 構造化ログ： 構造化 JSON ログに pino を使用します（src/logger.ts）。開発時にはログを整形して出力します。
• エラー処理： カスタムエラークラス（src/errors.ts）と、すべてのハンドラーで一貫した try/catch パターンを使用します。
• コンテナ化： 本番環境向けに最適化されたイメージを作成するためのマルチステージ Dockerfile を備えています。
• Lint／フォーマット： ESLint と Prettier で設定されています。
• テスト： Vitest を使用します。設定の読み込み（tests/config.test.ts）と greet ツールのハンドラー（tests/greet.test.ts）のテスト例が含まれています。

前提条件

• Node.js（v18 以降を推奨）
• npm（通常は Node.js に同梱されています）
• Docker（任意。コンテナで実行する場合）

セットアップとインストール

1. リポジトリをクローンします（またはテンプレートとして使用します）：

   # If you cloned it
   git clone <repository-url>
   cd mcp-server-boilerplate
   

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

   npm install
   

3. 環境を設定します（任意）：

   • サンプル環境ファイルをコピーします：

     cp .env.example .env
     

   • .env ファイルを編集して、必要な設定を行います（設定 セクションを参照）。

設定

設定は環境変数で管理します。ローカル開発では、.env ファイルから環境変数を読み込むこともできます。

• LOG_LEVEL：ログの最小レベルです（例：trace、debug、info、warn、error、fatal）。（デフォルト：info）。
• NODE_ENV：最適化されたビルドと標準の JSON ログを使用するには、production に設定します。デフォルトは development（整形されたログを有効化）です。
• CUSTOM_GREETING_PREFIX：挨拶ツールに指定できる任意のプレフィックスです（例：「👋 」）。デフォルトは空です。

サーバーの実行

開発モード（ホットリロードと整形されたログを使用）

このコマンドは tsx を使用して TypeScript コードを直接実行し、出力を pino-pretty に渡します。

npm run dev

注：dev スクリプトを実行するには、pino-pretty をインストールする必要があります（npm install --save-dev pino-pretty）。

• ログはコンソールに整形して出力されます。

本番モード（コンパイル済み JavaScript）

1. TypeScript コードをビルドします：

   npm run build
   

   コードが dist/ ディレクトリにコンパイルされます。

2. サーバーを実行します：

   # Example: Set custom greeting prefix with emoji
   set CUSTOM_GREETING_PREFIX=👋 
   set NODE_ENV=production
   npm start
   

   ログは JSON 形式で出力されます。

Docker で実行する

1. Docker イメージをビルドします：

   docker build -t mcp-server-boilerplate .
   

2. コンテナを実行します：

   # Run with stdio transport 
   # (Needs an interactive terminal)
   docker run -i --rm --name mcp-server-stdio mcp-server-boilerplate
   

   • 必要に応じて環境変数（-e）を調整してください。

ボイラープレートの拡張

1. ツールの追加：

   • src/index.ts（または別の src/tools/ ディレクトリ）で、引数の Zod スキーマを定義します。
   • server.tool(name, schemaDefinition, handler) を使用します。
   • ハンドラーのロジックを実装します。一貫性を保つため、src/errors.ts のカスタムエラーを使用することもできます。
   • 重要： ツールはシンプルな名前のみで登録します（例：「mcp_minimal_add」ではなく「add」）。Cursor は AI ツール呼び出しの際に、自動でプレフィックスを付与します。

2. リソースの追加：

   • 静的リソースの場合：server.resource(name, uri, metadata, handler)。
   • 動的リソースの場合：ResourceTemplate を定義し、server.resource(name, template, metadata, handler) を使用します。
   • ハンドラーのロジックを実装します。

3. プロンプトの追加：

   • 引数の Zod スキーマを定義します。
   • server.prompt(name, schemaDefinition, handler) を使用します。
   • 希望するメッセージ構造を返すハンドラーのロジックを実装します。

4. 設定の追加：

   • .env.example に新しい環境変数を追加します。
   • 検証済みの値を src/config.ts から読み込み、エクスポートします。

MCP ツールの呼び出し

MCP ツールを使用する際は、どのように呼び出されるかを理解しておくことが重要です。

1. AI によるツールの呼び出し： MCP ツールは、ユーザーが直接呼び出すのではなく、AI アシスタントが呼び出すように設計されています。AI は、プレフィックス付きの名前を使ってツールを直接呼び出せます。

2. ツールの命名：

   • ツールはシンプルな名前（例：「add」）で登録します。
   • AI にはプレフィックス付きの名前（例：「mcp_mcp_minimal_add」）で表示されます。
   • プレフィックス付きの名前でツールを登録しないでください。重複が発生します。

3. ログ出力に関する注意事項：

   • stdio モードで実行する場合、すべてのログは stderr に出力し、stdout には出力しないでください。
   • stdout は JSON-RPC メッセージ専用です。
   • console.log() を使用すると JSON-RPC プロトコルが破損します。stderr に書き込むカスタムロガーを使用してください。

4. ユーザーインターフェース：

   • ユーザーはチャットインターフェースで MCP ツールを直接呼び出せません。
   • AI アシスタントが仲介役となり、ユーザーに代わってツールを呼び出します。

よくある問題

このボイラープレートの開発経験から、注意すべきよくある問題をいくつか紹介します。

1. JSON-RPC プロトコルの問題：

   • console.log の出力など、JSON-RPC 以外のメッセージが stdout に送信されると、stdio トランスポートの仕組みが破損します。デバッグログはすべて stderr に出力する必要があります。
   • stdio モードでは、有効な JSON-RPC メッセージのみを stdout に送信してください。

2. ツール名のプレフィックス付与：

   • Cursor は AI アシスタントからの呼び出しに備えて、ツール名に自動でプレフィックスを付与します。たとえば、サーバー名が「mcp_minimal」で、ツール名「add」を登録した場合、AI は「mcp_mcp_minimal_add」として呼び出します。
   • シンプルな名前とプレフィックス付きの名前の両方でツールを登録しないでください。AI が利用できるツールに重複した項目が作成されます。

3. MCP ツールの呼び出し：

   • MCP ツールは、チャットでユーザーが直接呼び出すのではなく、AI アシスタントが呼び出すように設計されています。ユーザーはチャットインターフェースで「@Tool」構文を使用して MCP ツールを呼び出せません。
   • AI は登録済みのツールを自動的に検出し、ユーザーによる設定なしで呼び出せます。

クライアント設定の例

このサーバーに接続するための、Cursor などのクライアントの設定例を紹介します。

Stdio 経由での接続（ローカル開発に推奨）

この方法では、Cursor の mcp.json ファイルを使用します（通常、Linux/macOS では ~/.cursor/mcp.json、Windows では C:\Users\<username>\.cursor\mcp.json にあります）。

1. dist/index.js ファイルを作成するため、npm run build を実行済みであることを確認してください。

2. コンパイル済みの stdio サーバーを明示的に実行するスクリプトを package.json に追加します。

   "scripts": {
     // ... other scripts
     "start:stdio": "cross-env NODE_ENV=production node dist/index.js --stdio"
   }
   

3. まだインストールしていない場合は、cross-env をインストールします：npm install --save-dev cross-env。

4. mcp.json でサーバーを設定します（ファイル内に JSON コメント // がないことを確認してください）。

   {
     "mcpServers": {
       "mcp_minimal": {
         "displayName": "MCP Minimal",
         "command": "node",
         "args": [
           "C:\\path\\to\\your\\project\\dist\\index.js",
           "--stdio"
         ],
         "env": {
           "NODE_ENV": "production"
         },
         "enabled": true
       }
     }
   }
   

   • 重要： "C:\\path\\to\\your\\project\\dist\\index.js" を、お使いの プロジェクトディレクトリにある dist/index.js ファイルの正しい 絶対パス に置き換えてください。Windows では、パスの区切り文字として二重バックスラッシュ（\\）を使用してください。
   • この設定では、Cursor の起動時に npm や相対パスに関する問題が発生する可能性を回避し、絶対スクリプトパスを指定して node を直接呼び出します。

基本的なセキュリティ上の考慮事項

• 入力検証： 基本的な検証には Zod スキーマが使用されています。スキーマが用途に対して十分に厳格であることを確認してください。
• エラー処理： クライアントに返すエラーメッセージから、機密情報が漏えいしないようにしてください。現在の設定ではエラーがスローされ、SDK が変換します。SDK のエラー形式を確認してください。
• リソースアクセス： 機密データにアクセスしたり、制限された操作を実行したりするリソース／ツールハンドラーでは、認可チェックを実装してください（現在は実装されていません）。
• 依存関係： 依存関係の脆弱性を定期的に監査してください（npm audit）。
• コンテナーのセキュリティ： Dockerfile では非 root ユーザーを使用しています。ベースイメージを最新の状態に保ってください。

テスト

• Vitest を使用してテストを実行します：

  npm test
  

• ウォッチモードでテストを実行します：

  npm run test:watch
  

• カバレッジレポートを生成します：

  npm run coverage
  

• tests/ ディレクトリに *.test.ts パターンに従って新しいテストファイルを追加します。

Lint とフォーマット

• フォーマットを確認します：npm run format
• フォーマットを適用します：npm run format:fix
• リンターを実行します：npm run lint
• リンターのエラーを修正します：npm run lint:fix

制限事項

MCP は非常に新しいプロトコルで、現在も活発に開発されています。注意すべき既知の留意事項があります。

• AI モデルとの互換性： Cursor の AI エージェントがカスタム MCP ツールを自動的に使用する、または使用するよう促される機能は、モデルによって異なる場合があります。設定に正しく表示されていても、動的に検出されたツールの呼び出しを開始するのが難しいモデルもあります。AI ツールの呼び出しに問題が発生した場合は、Cursor で異なる AI モデルを試す必要があるかもしれません。
• ツールの数： MCP サーバーによっては、または多くの MCP サーバーを有効にしているユーザーの場合、Cursor が使用できるツールが多数になることがあります。現在、Cursor は最初の 40 個のツールのみをエージェントに送信します。
• リモート開発： Cursor は、stdio を介して直接、または sse を使用したネットワーク経由で、ローカルマシンから MCP サーバーと直接通信します。そのため、SSH 経由やその他の開発環境から Cursor にアクセスする場合、MCP サーバーが正しく動作しないことがあります。今後のリリースでの改善を目指しています。
• MCP 機能のサポート： MCP サーバーは、ツール、リソース、プロンプトという 3 つの主な機能を提供します。現在、Cursor がサポートしているのはツールのみです。リソースとプロンプトはプロトコルで定義され、このサーバーにも実装されていますが、Cursor からはまだアクセスできません。今後の Cursor のリリースで、これらの追加機能がサポートされることを期待しています。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。