MCP Server Tester

MCP サーバーテスター

⚠️ 開発中：このプロジェクトは現在も活発に開発されており、まだ十分なテストが行われていません。機能が未完成であったり、バグが含まれていたり、大幅に変更されたりする可能性があります。本番環境では使用せず、自己責任でご利用ください。

Model Context Protocol（MCP）サーバー向けの、強力で設定駆動型のテストツールです。このプロジェクトは、Claude などの AI モデルと連携する MCP サーバーの検証、ベンチマーク、信頼性の確保を包括的にサポートします。

現在の状況

このツールはアルファ版リリースに向けて開発中で、現在は次の機能を提供しています。

• ✅ 基本的な設定フレームワーク
• ✅ MCP サーバーへの接続と CLI サポート
• ✅ Claude AI を使用したテスト生成
• ✅ テスト用の自然言語クエリ生成
• ✅ 複数のルールによる包括的な応答検証
• ✅ コンソール、JSON、HTML、Markdown 形式でのレポート生成
• 🚧 テスター自体の自動テストカバレッジの拡大
• 🚧 本番環境向けの堅牢化とパッケージングの改善

貢献に関心がある方は、ぜひイシューを作成し、プルリクエストをお送りください。

はじめに

Model Context Protocol（MCP）を使用すると、AI モデルは標準化されたインターフェースを通じて外部のツールやデータソースにアクセスできます。MCP サーバーの複雑さと重要性が増すにつれ、正しく機能することを確かめる必要性も高まっています。MCP サーバーテスターは、次の方法でこのニーズに対応します。

• MCP サーバーが公開するすべてのツールのテストを自動化
• Claude AI を活用して、内容に即したインテリジェントなテストケースを生成
• 期待される結果とスキーマに照らして応答を検証
• 問題やパフォーマンスのボトルネックを特定するための詳細なレポートを提供

このツールは、MCP の実装が堅牢で信頼性が高く、プロトコル仕様に正しく準拠していることを確認する必要がある、MCP サーバーの開発者、AI 統合チーム、品質保証の専門家を対象としています。

概要

Model Context Protocol は、AI モデルが外部ツールを呼び出せるようにする標準規格です。MCP サーバーは、シンプルな HTTP インターフェースを介して 1 つ以上のツールを公開します。各ツールは、モデルが安全に呼び出せるよう、名前、パラメーター、応答スキーマを定義します。

mcp-server-tester は、MCP サーバーとそのツールが正しく動作することを確認するプロセスを自動化します。

1. 検出 – サーバーに問い合わせ、利用可能なすべてのツールを取得します。
2. テスト生成 – Claude AI を使って、各ツール向けの現実的なテストケースを作成します。
3. 実行 – サーバーに対してテストを実行します。
4. 検証 – 設定可能なルールを使って応答を検証します。
5. レポート作成 – 結果をコンソール、または JSON、HTML、Markdown 形式でまとめます。

期待される動作と実際の動作の不一致をすばやく見つけ、本番環境のモデルにツールを公開する前に問題を修正できるようにすることが目的です。

目的

• 信頼性 – MCP サーバーのバグや一貫性のない動作を検出します。
• 回帰テスト – サーバーが変更されるたびに、同じテストセットを実行します。
• ドキュメント – 生成されたレポートには、各ツールのクエリと期待される結果が記載されます。
• 自動化 – テスターを CI パイプラインに組み込み、継続的な品質を確保します。

リポジトリ

• GitHub：https://github.com/r-huijts/mcp-server-tester
• イシュー：https://github.com/r-huijts/mcp-server-tester/issues
• ライセンス：MIT

特長

• 🔍 あらゆる MCP サーバーから利用可能なツールを自動的に検出します
• 🧪 Claude AI を使用して、各ツールの現実的なテストケースを生成します
• ⚡ テストを実行し、応答を検証します
• 📊 詳細なテストレポートを提供します
• 🔑 設定を通じて複数の接続方法に対応します
• 設定ベース：テスト対象の MCP サーバーを定義するシンプルな JSON 設定
• 複数サーバー対応：複数の MCP サーバーを一度にテスト
• 包括的なテスト：各サーバーが公開するすべてのツールをテスト
• 自然言語のコンテキスト：各ツールを呼び出すユーザークエリを含めることで、実際の利用状況を再現
• 詳細なレポート：コンソール、JSON、HTML、Markdown 形式でレポートを生成
• セキュア：API キーは設定ファイルではなく、環境変数に保存

前提条件

• Node.js 18 以降
• テストケースの生成に使用する Anthropic API キー

インストール

このプロジェクトはまだ開発中のため、リポジトリをクローンしてインストールします。

# Clone the repository
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# Install dependencies
npm install

# Build the project
npm run build

# Create a symbolic link to use it globally (optional)
npm link

設定ベースの使い方

MCP Server Tester は、設定ファイルのみで操作するよう設計されています。この方法には、次のような利点があります。

• 再利用性：サーバーを一度定義すれば、繰り返しテストできます
• バージョン管理：テスト設定をコードと一緒にコミットできます
• 共有：サーバーのテスト設定をチームメンバーと簡単に共有できます

基本的な使い方

# Create a .env file with your Anthropic API key
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env

# Run tests using the configuration
mcp-server-tester

# Use a custom configuration file
mcp-server-tester path/to/my-config.json

設定ファイルの構造

設定ファイル（mcp-servers.json）ですべてのテスト内容を制御します。

{
  "numTestsPerTool": 3,
  "timeoutMs": 10000,
  "outputFormat": "console",
  "outputPath": "./reports/results.json",
  "verbose": false,
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "env": {
        "DEBUG": "true"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    },
    "dev-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/dev-server.js"],
      "env": {
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

デフォルトでは、mcpServers セクションに定義されたすべてのサーバーがテストされます。特定のサーバーのみをテストする場合は、任意の servers 配列を追加できます。

{
  "servers": ["filesystem", "dev-server"],
  "numTestsPerTool": 3,
  // other settings...
  "mcpServers": {
    // server definitions...
  }
}

設定オプション

テスト設定

オプション	説明	デフォルト
servers	テスト対象とする特定のサーバー名を指定する任意の配列	mcpServers 内のすべてのサーバー
numTestsPerTool	ツールごとに生成するテスト数	3
timeoutMs	テスト実行のタイムアウト時間（ミリ秒）	10000
outputFormat	テストレポートの形式（json、console、html、markdown）	"console"
outputPath	出力ファイルのパス	undefined
verbose	詳細なログ出力を有効にする	false

サーバー定義

mcpServers セクションで、テスト可能なすべてのサーバーを定義します。

プロパティ	説明	必須
command	実行する実行ファイルまたはコマンド	はい
args	コマンドライン引数の配列	はい
env	設定する環境変数	はい

サーバー接続の種類

設定では、さまざまな種類の MCP サーバーを定義できます。

NPM パッケージ

"npm-package": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {}
}

相対パスを使ったローカルスクリプト

"python-script": {
  "command": "python",
  "args": ["./servers/custom_server.py"],
  "env": {
    "PORT": "8080"
  }
}

絶対パスを使ったローカルスクリプト

サーバーの開発版をテストする際に便利です。

"dev-server": {
  "command": "node",
  "args": ["/absolute/path/to/your/dev-server.js"],
  "env": {
    "DEBUG": "true",
    "NODE_ENV": "development"
  }
}

ソケット接続

"remote-socket": {
  "command": "nc",
  "args": ["localhost", "3000"],
  "env": {}
}

API キーの管理

セキュリティ上の理由から、Anthropic API キーは次のいずれかの方法でのみ設定してください。

1. 環境変数：ANTHROPIC_API_KEY=your-api-key
2. プロジェクトディレクトリ内の .env ファイル：

   ANTHROPIC_API_KEY=your-api-key
   

3. Claude モデルを任意で設定：

   CLAUDE_MODEL=claude-3-opus
   

   指定しない場合、ツールはデフォルトで claude-3-7-sonnet-20250219 を使用します。

重要：API キーを設定ファイルに記載しないでください。バージョン管理にコミットされる可能性があります。

コマンドラインオプション

MCP Server Tester は、最小限のコマンドラインオプションに対応しています。

オプション	説明
--init または -i	デフォルトの設定ファイルを作成
--list または -l	設定に定義されたすべてのサーバーを一覧表示
--help または -h	ヘルプ情報を表示
--servers または -s	テスト対象のサーバーをカンマ区切りで指定
[config-path]	カスタム設定ファイルのパスを指定

--servers オプションを指定すると、設定ファイル内の servers 配列が上書きされます。

テスト生成プロセス

このツールは Claude AI を使用して、MCP サーバーが公開する各ツールに適したテストケースを自動生成します。

1. サーバーから利用可能なすべてのツールを検出します
2. 各ツールについて、以下を分析します。
   • ツール名と説明
   • 必須パラメーターとオプションのパラメーター
   • パラメーターの型と制約
3. Claude がツールごとに複数のテストケースを生成します。
   • 有効な入力を使った正常系テスト
   • 境界値を使ったエッジケーステスト
   • 無効な入力を使ったエラーケーステスト

各テストケースには以下が含まれます。

• テスト対象の説明
• 入力パラメーター
• 期待される結果の基準

検証ルールの種類

検証ルールは、ツールの応答の構造と内容をチェックするために使用します。 以下のルールの種類に対応しています。

• contains – 文字列または配列に指定した値が含まれていることを確認します
• matches – 等価性または正規表現との一致を確認します
• hasProperty – プロパティが存在することを確認します
• equals – 値が期待される値と完全に一致することを検証します
• arrayLength – 配列が指定した長さであることを要求します
• custom – ユーザー定義の検証関数を呼び出します

テストの実行と検証

設定で指定された各サーバー（指定されていない場合はすべてのサーバー）について、以下を行います。

1. ツールがサーバーに接続します
2. 利用可能なすべてのツールを検出します
3. 各ツールのテストケースを生成します
4. 各テストケースをサーバーに対して実行します
5. 期待される結果に照らして応答を検証します
6. 結果のレポートを生成します

レポートのオプション

ツールは複数の形式でレポートを生成できます。形式は outputFormat 設定オプションで指定します。

コンソール出力（デフォルト）

テスト結果をターミナルに直接表示します。

JSON レポート

outputPath で指定したパスに、構造化された JSON ファイルを作成します。

HTML レポート

outputPath で指定したパスに、可視化を含む HTML レポートを生成します。

Markdown レポート

outputPath で指定したパスに、持ち運び可能な Markdown ファイルを作成します。

完全な例

基本的なセットアップとテスト

1. デフォルトの設定ファイルを作成します。

   mcp-server-tester --init
   

2. mcp-servers.json ファイルを編集して、独自のサーバーと設定を追加します

3. Anthropic API キーを含む .env ファイルを作成します。

   echo "ANTHROPIC_API_KEY=your-api-key-here" > .env
   

4. テストを実行します。

   mcp-server-tester
   

サーバーの開発版をテストする

MCP サーバーの開発版をテストするには、以下の手順を実行します。

1. 絶対パスを指定して、開発サーバーの設定を追加します。

{
  "mcpServers": {
    "my-dev-server": {
      "command": "node",
      "args": ["/path/to/your/project/dist/server.js"],
      "env": {
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

2. テストを実行します。

mcp-server-tester

複数の異なる設定をテストする

テストシナリオごとに異なる設定ファイルを用意できます。

# Create different config files for different environments
cp mcp-servers.json config-dev.json
cp mcp-servers.json config-prod.json

# Edit each file with appropriate settings

# Run tests with specific config
mcp-server-tester ./config-dev.json
mcp-server-tester ./config-prod.json

トラブルシューティング

接続の問題

MCP サーバーへの接続に問題がある場合は、以下を確認してください。

1. mcp-servers.json ファイル内のサーバー設定を確認します
2. サーバーが MCP プロトコルに対応しているか確認します
3. 応答が遅いサーバーでは、timeoutMs の値を大きくしてみます
4. verbose: true を設定して、詳細ログを有効にします
5. 環境変数 DEBUG=true を使用して、サーバープロセスの起動状況を確認します

API キーの問題

API キーに問題がある場合は、以下を確認してください。

1. Anthropic API キーが有効であることを確認します
2. API キーが環境変数または .env ファイルに正しく設定されていることを確認します
3. API キーに空白や余分な文字が含まれていないか確認します
4. .env ファイルが正しい場所（プロジェクトのルート）にあることを確認します

ツールの実行エラー

ツールの実行に失敗する場合は、以下を確認してください。

1. サーバーが MCP プロトコルを正しく実装していることを確認します
2. サーバーログにエラーがないか確認します
3. ツールのパラメーターが有効であることを確認します
4. ツールの実行に時間がかかる場合は、タイムアウトを延長します

Node.js の非推奨警告

punycode Module Deprecation Warning

次の警告が表示された場合：

(node:71439) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

これは、内部モジュールの非推奨化について Node.js が出す無害な警告です。MCP Server Tester の機能には影響しません。この警告は依存関係の1つに由来するもので、今後のアップデートで解消される予定です。

対処方法：

1. 警告を無視する - 機能には影響しません
2. 警告を抑制する - NODE_NO_WARNINGS=1 環境変数を指定して実行します：

   NODE_NO_WARNINGS=1 mcp-server-tester
   

3. npm scripts を使用する - 同梱の npm scripts では、これらの警告がすでに抑制されています：

   npm start
   

開発

開発環境をセットアップするには：

# Clone the repository
git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester

# Install dependencies (including dev dependencies)
npm install
# Run the Jest test suite
npm test
# Lint the code for style issues
npm run lint

# Create your .env file
cp .env.example .env
# Edit .env and add your API key

# Run the tool in development mode
npm run dev

コード構成

正式なテストジェネレーターは src/test-generator/TestGenerator.ts にあります。 混乱を避けるため、src/generator/TestGenerator.ts などの古いファイルは削除されています。 すべてのインポートで、src/test-generator/ 内のモジュールを参照してください。

パッケージ化と配布

このプロジェクトは、インストールを簡単にするため npm パッケージとして公開できます。

# Compile TypeScript sources
npm run build

# Create a tarball of the package
npm pack

# Publish to npm (requires npm credentials)
npm publish

公開パッケージには、dist フォルダーの内容と必要なドキュメントのみが含まれます。npm publish の実行時に、ビルドが自動的に実行されます。

ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。

インストール（クイックスタート）

1. Node.js 18 以降をインストールします。
2. リポジトリをクローンし、依存関係をインストールします：

git clone https://github.com/r-huijts/mcp-server-tester.git
cd mcp-server-tester
npm install
npm run build

3. 必要に応じてパッケージをグローバルにリンクし、mcp-server-tester コマンドをシステム全体で利用できるようにします：

npm link

設定の概要

すべての動作は JSON 設定ファイル（デフォルトでは mcp-servers.json）で制御します。この設定には、テストする MCP サーバーの一覧と、タイムアウトやレポート形式などのオプションを指定します。

--init を使ってファイルを作成するか、用意されているサンプルをコピーします：

mcp-server-tester --init
# or
cp mcp-servers.json.example mcp-servers.json

ファイルを編集して、サーバーを追加します。最小限の例は次のとおりです：

{
  "numTestsPerTool": 2,
  "timeoutMs": 10000,
  "outputFormat": "console",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "env": { "DEBUG": "true" }
    }
  }
}

Anthropic API キーを .env ファイルに記述するか、ANTHROPIC_API_KEY としてエクスポートします：

ANTHROPIC_API_KEY=your-api-key

テストの実行

設定と環境変数を用意したら、次を実行します：

mcp-server-tester

別の設定を指定するには mcp-server-tester path/to/config.json を使用します。また、--servers filesystem,github を指定すると、特定のサーバーのみをテストできます。

結果の確認

デフォルトでは、結果はコンソールに表示されます。構造化レポートを生成することもできます：

• JSON – 後続の処理に使用できる、機械可読なデータです。
• HTML – 折りたたみ可能なセクションを備えた、閲覧しやすいサマリーです。
• Markdown – コードレビューで共有するのに適した形式です。

レポートには、各ツール、呼び出しに使用した自然言語クエリ、応答が検証ルールを満たしたかどうか、および失敗に関する詳細が記載されます。

トラブルシューティングの基本

• 接続の問題 – サーバーのパスを確認し、必要に応じて timeoutMs を大きくしてください。
• API キーの問題 – ANTHROPIC_API_KEY が余分な空白なしで設定されていることを確認してください。
• ツールの失敗 – サーバーログを確認し、実装が MCP 仕様に準拠していることを確認してください。