mcp-runner

mcp-runner

MCP（Model Context Protocol）サーバーを実行するための TypeScript SDK および CLI です。

概要

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]
# or
npm run cli -- runserver <server-name> [params] [options] # uses first available tool

オプション：

• --text：完全な JSON ではなく、レスポンスからテキストコンテンツのみを出力します。

例：

# Run a specific tool
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# Use first available tool
npm run cli -- runserver sequential-thinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# Output only text content
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 1}' --text

プログラムからの使用方法

基本的な例

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

async function main() {
  try {
    // First call (specific tool)
    const result1 = await runServer('openrouterai', 'chat_completion', {
      messages: [
        { role: 'user', content: 'Say hello!' }
      ]
    });
    console.log('Result 1:', result1);

    // Second call (uses first available tool)
    const result2 = await runServer('openrouterai', undefined, {
      messages: [
        { role: 'user', content: 'How are you?' }
      ]
    });
    console.log('Result 2:', result2);

    // Terminate server when done
    await terminateServer();
  } catch (error) {
    console.error('Error:', error);
    await terminateServer();
  }
}

エラー処理

SDK には、包括的なエラー処理が含まれています。

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

API

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

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

パラメーター：

• serverName：設定に記載されているサーバー名
• params：サーバーのツールに渡すパラメーター

戻り値：サーバーのレスポンスで解決される Promise

terminateServer()

SDK が管理するサーバープロセスを終了します。すべての操作が完了したときに呼び出してください。

戻り値：サーバーの終了時に解決される Promise

アーキテクチャ

ServerManager

ServerManager クラスは、MCP サーバープロセスのライフサイクルを管理するシングルトンとして実装されています。主な役割は次のとおりです。

• プロセスのライフサイクル管理
• クライアント接続の処理
• 正常な終了
• エラー処理とログ記録

このマネージャーは、常に実行中のサーバープロセスが 1 つだけになるようにし、サーバーの起動、再利用、終了を行うメソッドを提供します。

設定

SDK は cline_mcp_settings.json からサーバー設定を読み取ります。このファイルは標準の設定ディレクトリに配置する必要があります。各サーバー設定には、次の項目が含まれます。

{
  "command": "string",
  "args": "string[]",
  "env": "Record<string, string>",
  "disabled": "boolean",
  "alwaysAllow": "string[]"
}

開発

ビルド

npm run build

テストの実行

npm test

ライセンス

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

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。