Demo MCP Basic

Demo MCP Basic

このプロジェクトでは、**Model Context Protocol（MCP）**を使用した基本的なクライアントとサーバー間のやり取りを実演します。MCP を使用すると、AI SDK（Google Gemini／Vertex AI など）経由でアクセスする AI モデルが、別のサーバープロセスから提供される外部ツールやリソースを安全に検出して利用できます。

この例では：

• サーバー（src/server/）は MCP プロバイダーとして動作し、簡単な計算ツール（加算、減算など）を提供します。
• クライアント（src/client/）は AI SDK を使用して Google AI モデルとやり取りし、MCP サーバーに接続することで、生成中に AI がサーバーのツールを利用できるようにします。

この構成は、MCP サーバーでホストされるカスタム機能へのアクセスを AI モデルに許可することで、その機能を拡張できることを示しています。

前提条件

• Node.js（package.jsonで指定されているバージョン >=23.0.0）
• npm（Node.js に付属）
• Google AI（Gemini）API キー。Google AI Studioから取得できます。（Gemini モデルの使用に必要です）

セットアップ

1. リポジトリをクローンします：

   git clone [email protected]:bertrandgressier/demo-ts-mcp-client-server.git
   cd demo-mcp-basic
   

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

   npm install
   

3. 環境ファイルを作成します： 環境ファイルのサンプル .env.example を、新しいファイル .env にコピーします：

   cp .env.example .env
   

   次に、.env ファイルを編集して、実際の API キーと設定を追加します。必須および任意の変数は次のとおりです：

   # Google Studio Models (Gemini) に必要
   GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
   
   # Google Vertex AI Models に必要
   VERTEX_PROJECT_ID=YOUR_VERTEX_PROJECT_ID
   
   # 任意：設定されていない場合はデフォルトで 'us-central1'
   # VERTEX_LOCATION=your-vertex-location
   
   # 任意：Vertex AI のサービスアカウントキーファイルへのパス。設定されていない場合はルートの 'vertex-key.json' がデフォルトで使用されます。
   # VERTEX_KEY_FILE=path/to/your/vertex-key.json
   

   YOUR_GOOGLE_API_KEY と YOUR_VERTEX_PROJECT_ID を実際の認証情報に置き換えてください。 Vertex AI のキーファイルを使用する場合は、正しい場所（ルートの vertex-key.json など）に配置するか、VERTEX_KEY_FILE に正しいパスを指定してください。

   • 重要： .gitignore ファイルは、.env と vertex-key.json が Git にコミットされないように設定されています。

利用可能なスクリプト

• TypeScript をビルド：

  npm run build
  

  src の TypeScript コードを dist 内の JavaScript にコンパイルします。

• 本番サーバーを起動：

  npm run start
  # or specifically
  npm run start:server
  

  プロジェクトをビルド（まだビルドされていない場合）して、dist/server/server.js からコンパイル済みのサーバーを実行します。

• 本番クライアントを起動：

  npm run start:client
  

  dist/client/client.js からコンパイル済みのクライアントを実行します。

• 開発モードでサーバーを実行：

  npm run dev:server
  

  別途ビルドせずに、ts-node（または --experimental-transform-types を使用する同等の仕組み）でサーバーを直接実行します。

• 監視付きの開発モードでサーバーを実行：

  npm run dev:server:watch
  

  nodemon を使用してサーバーを実行し、src/server ディレクトリで変更が検出されると自動的に再起動します。

• 開発モードでクライアントを実行：

  npm run dev:client
  

  ts-node（または同等の仕組み）でクライアントを直接実行します。

Example Client (src/client/client.ts)

主要なクライアントスクリプトの例では、以下の処理を示します。

1. MCP サーバーに接続します： ローカルで実行中の MCP サーバー（http://localhost:3001/sse を想定）への接続を確立します。
2. ツールを取得します： 接続したサーバーが提供するツールの一覧を取得します。
3. AI モデルを設定します： .env に設定された環境変数と、場合によっては src/models/google-ai-provider.ts に応じて、Google AI モデル（API キー経由の Gemini または Vertex AI）を設定した AI SDK（generateText）を使用します。
4. プロンプトを実行します： プロンプト（6 + 12）とともに、取得したツールを使って計算を解くよう AI に指示するシステムメッセージを送信します。
5. 結果を出力します： サーバーから提供されたツールを使用する場合はその処理を経て、AI モデルが生成した最終的なテキスト応答を出力します。

このクライアントは、AI 生成のワークフロー内でツールを活用するために、アプリケーションが MCP サーバーと連携する方法を基本的に示すものです。

Project Structure

• src/：TypeScript のソースコードが含まれています。
  • client/：MCP クライアントアプリケーションのコードです。
  • server/：MCP サーバーアプリケーションのコードです。
  • model.ts：AI モデルの初期化と環境変数の読み込みを処理します。
• dist/：コンパイル済みの JavaScript コードが含まれています（npm run build の実行後）。
• .env：環境変数（API キーなど）を保存します。このファイルはコミットしないでください。
• package.json：プロジェクトのメタデータと依存関係を記述します。
• tsconfig.json：TypeScript コンパイラーの設定です。