MCP Quick Start Server

MCP クイックスタートサーバー

このプロジェクトは、TypeScript と @modelcontextprotocol/sdk で構築した、Model Context Protocol（MCP）サーバーのシンプルなクイックスタート例です。基本的なツール、リソース、プロンプトの定義方法を紹介します。

機能

• ツール：add：2つの数値を加算します。
  • パラメーター：a（数値）、b（数値）
  • 戻り値：合計を文字列で返します。
• ツール：fetch-chuck-jokes：ランダムな Chuck Norris のジョークを取得します。
  • パラメーター：なし
  • 戻り値：Chuck Norris のジョークを文字列で返します。
• リソース：greeting：パーソナライズされた挨拶を提供します。
  • URI スキーム：greeting://{name}
  • 例：greeting://World は「World」への挨拶を提供します。
• プロンプト：getGreetingAndJoke：AI クライアントに、ユーザーの名前を呼んで挨拶し、その後 Chuck Norris のジョークを伝えるよう指示します。
  • パラメーター：name（文字列）
  • 例：name: "Narendra" を指定して呼び出すと、AI が Narendra に挨拶し、ジョークを伝える会話が設定されます。

ディレクトリ構成

quick-start/
├── build/              # Compiled JavaScript output
├── src/                # TypeScript source files
│   ├── index.ts        # Main server setup and entry point
│   ├── tools/
│   │   └── index.ts    # Tool definitions
│   ├── resources/
│   │   └── index.ts    # Resource definitions
│   └── prompts/
│       └── index.ts    # Prompt definitions
├── .gitignore
├── package-lock.json
├── package.json
├── tsconfig.json
└── README.md           # This file

前提条件

• Node.js（v18.x 以降を推奨）
• npm（Node.js に同梱されています）

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

1. リポジトリをクローンします（まだの場合）：

   git clone https://github.com/scriptstar/mcp-starter-kit-node.git
   cd mcp-starter-kit-node
   

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

   npm install
   

サーバーのビルド

TypeScript コードを JavaScript にコンパイルするには、次のコマンドを実行します。

npm run build

このコマンドは、tsconfig.json の設定に従って tsc（TypeScript コンパイラー）を実行し、出力を build/ ディレクトリに配置します。また、メインのビルドファイルに実行権限を付与します。

サーバーの実行

ビルド後、次のコマンドを使って MCP サーバーを起動できます。

node build/index.js

また、本番環境に近い環境では、start スクリプトを使用できます。

npm start

サーバーが起動し、標準入力（stdin）でメッセージを受け取り、標準出力（stdout）に応答を送信します。これは StdioServerTransport を使用しているためです。

開発ワークフロー

より効率的に開発するには、dev スクリプトを使用できます。

npm run dev

このコマンドは concurrently を使用して、次の2つのプロセスを実行します。

1. tsc -w：TypeScript ファイルの変更を監視し、自動的に再コンパイルします。
2. nodemon build/index.js：build ディレクトリ（tsc が JavaScript を出力する場所）の変更を監視し、Node.js サーバーを自動的に再起動します。

これにより、開発中にライブリロードのような操作感が得られます。

Lint

このプロジェクトでは、コードの品質と一貫性を保つために、TypeScript をサポートする ESLint を使用しています。

• Lint エラーを確認するには：

  npm run lint
  

• 修正可能な Lint エラーを自動修正するには：

  npm run lint:fix
  

コードをコミットする前に、リンターを実行することをおすすめします。

仕組み

このサーバーは Model Context Protocol を実装しています。

• src/index.ts：McpServer インスタンスを初期化し、それぞれのモジュールからツール、リソース、プロンプトの登録関数をインポートします。これらの関数を呼び出してサーバーに登録し、通信を処理するために StdioServerTransport を接続します。
• src/tools/index.ts：registerTools 関数をエクスポートします。
  • add：2つの数値 a と b を受け取り、その合計を返します。
  • fetch-chuck-jokes：https://api.chucknorris.io/jokes/random に HTTP GET リクエストを送信し、ジョークを返します。
• src/resources/index.ts：registerResources 関数をエクスポートします。
  • greeting：リソーステンプレート greeting://{name} を定義します。この URI がリクエストされると、パーソナライズされた挨拶メッセージを返します。
• src/prompts/index.ts：registerPrompts 関数をエクスポートします。
  • getGreetingAndJoke：name 引数を受け取るプロンプトを定義します。AI クライアントを導くための一連の初期メッセージを構築します。1つ目のメッセージ（ロール：assistant）でコンテキストを設定し、2つ目のメッセージ（ロール：user）で指定された name を使ってリクエストを作成します。

サーバーとのやり取り（概念）

この MCP サーバーは、MCP クライアント（AI アシスタントや開発ツールなど）によって制御されるように設計されています。クライアントは JSON-RPC メッセージを標準入力に送信し、標準出力から応答を受け取ることで、サーバーと通信します。

定義された機能をクライアントがどのように利用するか、例を示します。

1. add ツールの呼び出し： クライアントは、次のような JSON-RPC リクエストを送信できます。

   {
     "jsonrpc": "2.0",
     "method": "callTool",
     "params": { "name": "add", "args": { "a": 5, "b": 3 } },
     "id": "request1"
   }
   

   サーバーは、結果を次のように返します。

   {
     "jsonrpc": "2.0",
     "result": { "content": [{ "type": "text", "text": "8" }] },
     "id": "request1"
   }
   

2. greeting リソースへのアクセス： クライアントは、リソース URI greeting://Alice の読み取りをリクエストできます。

   {
     "jsonrpc": "2.0",
     "method": "readResource",
     "params": { "uri": "greeting://Alice" },
     "id": "request2"
   }
   

   サーバーは、次のように応答します。

   {
     "jsonrpc": "2.0",
     "result": {
       "contents": [{ "uri": "greeting://Alice", "text": "Hello, Alice!" }]
     },
     "id": "request2"
   }
   

3. getGreetingAndJoke プロンプトの使用： 「Bob」を対象にこのガイド付きタスクを開始するクライアントは、次のように送信します。

   {
     "jsonrpc": "2.0",
     "method": "getPrompt",
     "params": {
       "uri": "prompt://getGreetingAndJoke",
       "args": { "name": "Bob" }
     },
     "id": "request3"
   }
   

   サーバーは、初期メッセージを次のように返します。

   {
     "jsonrpc": "2.0",
     "result": {
       "messages": [
         {
           "role": "assistant",
           "content": {
             "type": "text",
             "text": "You are a friendly assistant. Your task is to greet the user by their name and then tell them a Chuck Norris joke. You should use the available tools and resources to accomplish this. I will now wait for your instruction to proceed with greeting and joke telling for the specified user."
           }
         },
         {
           "role": "user",
           "content": {
             "type": "text",
             "text": "Please greet Bob and then tell a Chuck Norris joke."
           }
         }
       ]
     },
     "id": "request3"
   }
   

   AI クライアントはこれらのメッセージを処理し、その後、「Bob」向けに greeting リソースと fetch-chuck-jokes ツールを呼び出すことを決定します。その際、readResource リクエストと callTool リクエストをそれぞれ送信します。

今後の開発

• さまざまな入出力形式に対応する、より複雑なツールを追加します。
• ローカルファイルやデータベースと連携するリソースを実装します。
• 複数ターンの会話に対応する、より高度なプロンプトを作成します。
• 必要に応じて、HTTP などの他のトランスポート層を検討します。
• 包括的なエラー処理とロギングを追加します。

この README で、プロジェクトの概要を把握できるはずです！