MCP Runner

🚀 mcp-runner

TypeScriptベースのSDKとCLIツールで、MCP（モデルコンテキストプロトコル）サーバーを実行するために使用します。

🚀 クイックスタート

mcp-runnerは、cline_mcp_settings.json設定ファイルに基づいてMCPサーバーを実行するプロセスを簡素化することを目的としています。サーバープロセスの再利用とエレガントなクリーンアップをサポートし、複数の操作で同じサーバーインスタンスを使用できます。コマンドラインから呼び出すことも、TypeScriptプロジェクトのライブラリとして使用することもでき、他のMCPサーバーにも利用できます。

✨ 主な機能

• サーバープロセスの再利用
• タイムアウト処理付きのエレガントな終了
• サーバーのライフサイクルの自動管理
• TypeScriptのサポート
• 包括的なエラー処理とログ記録

📦 インストール

npm install

💻 使用例

CLIの使用方法

このパッケージには、MCPサーバーと対話するためのコマンドラインインターフェイスが含まれています。

基本的な使用法

ツールの一覧表示

指定されたMCPサーバーの利用可能なすべてのツールを一覧表示します。

npm run cli -- list-tools <server-name>

例:

npm run cli -- list-tools sequential-thinking

サーバーの実行

指定されたMCPサーバーを実行し、オプションでツール名とパラメータを指定できます。

npm run cli -- runserver <server-name> [tool-name] [params] [options]
# または
npm run cli -- runserver <server-name> [params] [options] # 最初に利用可能なツールを使用

オプション:

• --text：応答のテキスト内容のみを出力し、完全なJSONではなくします。

例:

# 特定のツールを実行
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "初期思考", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# 最初に利用可能なツールを使用
npm run cli -- runserver sequential-thinking '{"thought": "初期思考", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# テキスト内容のみを出力
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "初期思考", "thoughtNumber": 1, "totalThoughts": 1}' --text

プログラムによる使用方法

基本的な使用法

import { runServer, terminateServer } from 'mcp-runner';

async function main() {
  try {
    // 最初の呼び出し（ツールを指定）
    const result1 = await runServer('openrouterai', 'chat_completion', {
      messages: [
        { role: 'user', content: 'Say hello!' }
      ]
    });
    console.log('結果 1:', result1);

    // 2回目の呼び出し（最初に利用可能なツールを使用）
    const result2 = await runServer('openrouterai', undefined, {
      messages: [
        { role: 'user', content: 'How are you?' }
      ]
    });
    console.log('結果 2:', result2);

    // 完了時にサーバーを終了
    await terminateServer();
  } catch (error) {
    console.error('エラー:', error);
    await terminateServer();
  }
}

高度な使用法

SDKは包括的なエラー処理を提供します。

• サーバープロセスのエラー
• ツール実行のエラー
• タイムアウト処理付きのエレガントな終了
• エラー発生時の自動クリーンアップ

📚 ドキュメント

API

runServer(serverName: string, params: Record<string, unknown>)

指定されたサーバーでツールを実行し、提供されたパラメータを使用します。サーバープロセスは、明示的に終了するまで後続の呼び出しで再利用されます。

• serverName：設定ファイルから取得したサーバー名
• params：ツールに渡すパラメータ

terminateServer()

現在実行中のサーバープロセスをすぐに停止します。

アーキテクチャ

ServerManagerクラス

ServerManagerは、MCPサーバーのライフサイクルを管理するシングルトンクラスです。設定ファイルをロードし、サーバーインスタンスを作成および終了し、エラーを処理します。

ConfigurationLoaderクラス

ConfigurationLoaderは、cline_mcp_settings.jsonファイルから設定情報をロードする役割を担います。サーバー設定の読み取りと更新機能を提供します。

設定ファイルの形式

cline_mcp_settings.jsonは、MCPサーバーの関連設定を定義するJSONファイルです。

{
  "servers": [
    {
      "name": "server1",
      "url": "http://localhost:8080",
      "tools": [
        {
          "name": "tool1",
          "command": "node tool1.js"
        }
      ]
    }
  ]
}

エラー処理

すべての操作はServerManagerでエラーが捕捉され、ログ記録ツールを通じて詳細なエラー情報が出力されます。

例

my_serverという名前のサーバーがあり、以下のように設定されていると仮定します。

{
  "servers": [
    {
      "name": "my_server",
      "url": "http://localhost:8000",
      "tools": [
        {
          "name": "tool_a",
          "command": "node tool_a.js"
        }
      ]
    }
  ]
}

サーバーを実行し、tool_aツールを使用するには、次のコマンドを実行します。

npm run cli -- runserver my_server tool_a '{"input": "data"}'

参考ドキュメント

• MCPプロトコル
• Node.jsドキュメント
• 設定ファイルの仕様

📄 ライセンス

[プロジェクトのライセンス情報]