MCP Server Boilerplate

🟢 MCP Server in Node.js

わずか 2 分で Node.js のカスタム MCP サーバーを構築して実行 ⏱️

概要 · 機能 · インストール · MCP Inspector でのテスト · テスト用環境変数の設定 · Cursor AI との統合 · Cursor での MCP ツールの使用（エージェントモード） · コードの概要 · 参考資料とリソース · ライセンス

概要

MCP（Model Context Protocol） は、Cursor AI などの AI 支援開発環境にカスタムツールを統合できるフレームワークです。MCP サーバーは、データ取得やコード解析などの機能を公開するため、LLM ベースの IDE が必要に応じてこれらのツールを呼び出せます。MCP の詳細については、Model Context Protocol の概要をご覧ください。

このプロジェクトでは、Node.js を使用して JavaScript で実装された MCP サーバーを紹介します。2 つのツールを定義しています。add は 2 つの数値を受け取り、その合計を返します。getApiKey は API_KEY 環境変数から API キーを取得します。また、AI モデルが加算ツールの使い方を推測できるようにする、定義済みプロンプト add_numbers も提供します。

要件

• Node.js： バージョン 20 以上が必要です。

機能

• MCP 統合： LLM ベースの IDE にツールの機能を公開します。
• 加算ツール： 2 つの数値パラメーターを受け取り、その合計を返します。
• MCP プロンプト： AI モデルがツールの使い方を推測できるように、定義済みプロンプト（「add_numbers」）を提供します。
• 環境変数の取得： 設定ファイルから環境変数の例を読み込む方法を紹介します。
• 入力検証： スキーマ検証に Zod を使用します。
• 標準入出力トランスポート： StdioServerTransport を介して接続し、開発環境と統合します。

インストール

1. リポジトリをクローンする

   git clone <repository_url>
   cd <repository_directory>
   

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

   プロジェクトの依存関係は、次のいずれかの方法でインストールできます。

   オプション 1：既存の package.json を使ってインストールする

   次のコマンドを実行するだけです。

   npm install
   

   オプション 2：依存関係を手動でインストールする

   必要に応じて、既存の package.json を削除し、必要なパッケージを手動でインストールできます。

   npm install @modelcontextprotocol/sdk zod
   

   次に、新しく生成された package.json ファイルを更新し、ES Modules を有効にして mcp inspector コマンドを追加するため、以下の行を含めます。

   "type": "module",
   "scripts": {
    "inspector": "npx @modelcontextprotocol/inspector node ./mcp-server.js"
   }
   

MCP Inspector でのテスト

MCP Inspector は、IDE と統合する前にサーバーのツールを対話的にテストできるデバッグツールです。

オプション 1：npx で直接実行する

npx @modelcontextprotocol/inspector node ./mcp-server.js

オプション 2：npm スクリプトを使用する

npm run inspector

これにより、次の処理が行われます。

1. MCP inspector サーバーを起動します
2. ブラウザーで Inspector のインターフェースを開きます
3. ツール、リソース、プロンプトをテストできます

ブラウザーで MCP Server Inspector を開きます。 http://localhost:6274/

テスト用環境変数の設定

異なる API キーで getApiKey ツールをテストするには、Inspector の実行前に環境変数を設定します。

Linux/macOS（Bash/Zsh）：

# Temporary (current session only)
export API_KEY="your-test-key"
npm run inspector

# Or set for single command
API_KEY="your-test-key" npm run inspector

Windows（コマンドプロンプト）：

# Set for current session
set API_KEY=your-test-key
npm run inspector

Windows（PowerShell）：

# Set for current session
$env:API_KEY="your-test-key"
npm run inspector

# Or set for single command
$env:API_KEY="your-test-key"; npm run inspector

Cursor AI との統合

この MCP サーバーを Cursor IDE と統合するには、Cursor の設定インターフェースから構成を追加する必要があります。

1. Cursor IDE を開きます
2. Settings → Tools & Integrations に移動します
3. Add Custom MCP Server をクリックします
4. 以下の構成を追加します

重要： すでに他の MCP サーバーを構成している場合は、構成全体を上書きしないでください。代わりに、既存の "mcpServers" オブジェクトに "MCP Server Boilerplate" オブジェクトを追加します。

サンプル構成ファイル： このプロジェクトには、参照またはコピーできるサンプル構成ファイル ./cursor/mcp.json が含まれています。

構成の構造

追加が必要な構成は以下のとおりです。

Linux/macOS の例：

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["/home/john/mcp-server-node/mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

Windows の例：

{
  "MCP Server Boilerplate": {
    "command": "node",
    "args": ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"],
    "env": {
      "API_KEY": "abc-1234567890"
    }
  }
}

すでに MCP サーバーを構成している場合、構成全体は次のようになります。

{
  "mcpServers": {
    "existing-server": {
      "command": "python",
      "args": ["/path/to/existing/server.py"]
    },
    "MCP Server Boilerplate": {
      "command": "node",
      "args": ["/home/john/mcp-server-node/mcp-server.js"],
      "env": {
        "API_KEY": "abc-1234567890"
      }
    }
  }
}

構成パラメーター

• MCP Server Boilerplate：
  サーバー構成のキーです。任意の名前を付けることができます。

• command：
  サーバーの実行に使用する Node.js 実行ファイルです。次のいずれかを指定できます。

  • "node"（Node.js が PATH に含まれている場合）
  • Node.js 実行ファイルのフルパス（必要な場合）

  Node.js のパスの確認方法：

  Linux/macOS：

  which node
  # Example output: /home/john/.nvm/versions/node/v20.13.1/bin/node
  

  Windows（コマンドプロンプト）：

  where node
  # Example output: C:\Program Files\nodejs\node.exe
  

  Windows（PowerShell）：

  Get-Command node
  # Example output: C:\Program Files\nodejs\node.exe
  

• args：
  MCP サーバーファイルへの絶対パスを含む配列です。

  Linux/macOS の例：

  ["/home/john/mcp-server-node/mcp-server.js"]
  

  Windows の例：

  ["C:\\Users\\john\\mcp-server-node\\mcp-server.js"]
  

• env：（任意）
  MCP サーバープロセスの環境変数を定義します。この例では、API_KEY に "abc-1234567890" を設定しています。環境に応じてこの値を調整してください。

コードの概要

このプロジェクトは、次の主要な部分で構成されています。

• MCP サーバーの初期化：
  MCP SDK の McpServer を使用して MCP サーバーをインスタンス化し、StdioServerTransport を介して接続します。

• ツールの定義：

  • add：
    2 つの数値（a と b）を受け取り、その合計をテキストとして返す Zod スキーマで定義されています。
  • getApiKey：
    環境変数 API_KEY から API キーを取得し、テキストとして返します。

• プロンプトの定義：

  • add_numbers：
    AI モデルが加算ツールの使い方を推測できるようにする、事前定義済みのプロンプトです。

重要な注意事項：ツールにプロンプトを定義する必要はありません。この例では、入力に基づいて AI モデルが使用するツールを推測できるようにするという、プロンプトの機能の一つを示しています。AI は、タスクに必要だと判断した場合、ツールを直接使用することもできます。

Cursor で MCP ツールを使用する（エージェントモード）

MCP サーバーを Cursor IDE に統合し、エージェントモードを有効にすると、いくつかの方法でツールを使用できます。

加算ツールの使用方法

方法 1：自然言語のプロンプト 次のような自然言語のプロンプトを使用します。

add 3 and 5

または

what is 7 plus 12?

方法 2：プロンプトベースのツール呼び出し チャットに次のプロンプトを入力します。

/add_numbers

このプロンプトを入力して Enter キーを押すと、Cursor は次の処理を自動的に行います。

1. Node Server の add ツールを使用したいことを認識します
2. 2 つの数値パラメーターの入力を求める GUI プロンプトを表示します
3. AI モデルは、結果を計算するために add ツールを使用する必要があると推測します

加算ツールのパラメーター：

• パラメーター a：加算する最初の数値
• パラメーター b：加算する 2 番目の数値
• 戻り値：2 つの数値の合計をテキストとして返します

API キーツールの使用方法

getApiKey ツールには、次のように入力できます。

what is my API key?

または

get my API key

AI エージェントは、リクエストに基づいて適切なツールを自動的に推測します。

参考資料とリソース

• Model Context Protocol: typescript-sdk
• Cursor で独自の MCP を 5 分で使う
• Model Context Protocol の紹介

ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。