Testingbot Mcp Server

TestingBot MCP サーバー

TestingBot 公式の Model Context Protocol（MCP）サーバー実装です。このサーバーを使用すると、AI アシスタントが TestingBot のテストインフラストラクチャと連携でき、会話形式のインターフェースを通じてテスト、ブラウザー、デバイスなどを管理できます。

⚡ ワンクリックインストール

Claude Desktop： リリースページから mcp-server.mcpb をダウンロードし、ダブルクリックしてください。Claude が TestingBot MCP サーバーを自動的にセットアップします。

インストール後、TestingBot アカウント設定で認証情報を設定してください。

機能

• 📱 App Automate - エージェントから直接、実機やエミュレーターで Maestro、Espresso、XCUITest のテストスイートを実行します
• 🖥️ Live Testing - 実際のブラウザーやデバイスで、対話型の手動テストセッションを開始します
• 🌐 ブラウザーとデバイスの管理 - 利用可能なブラウザーと実機を照会します
• 🧪 テスト管理 - 詳細情報とともに、テストの作成、取得、更新、削除を行います
• 📦 ストレージ管理 - モバイルアプリのファイル（APK、IPA、ZIP）をアップロードして管理します
• 📸 スクリーンショットテスト - クロスブラウザースクリーンショットを撮影します
• 🏗️ ビルド管理 - テストをビルドにまとめます
• 👤 ユーザーアカウント - アカウント情報を表示、更新します
• 👥 チーム管理 - チーム設定とチームメンバーを管理します
• 🔌 Chrome DevTools Protocol - 高度なブラウザー自動化のための CDP セッションを作成します
• 🚇 トンネル管理 - ローカルテスト用の TestingBot トンネルを管理します

前提条件

• Node.js >= 20（推奨：22.15.0 以降）
• API 認証情報を持つ TestingBot アカウント
• MCP 対応クライアント（Claude Desktop、Continue を含む VS Code、Cursor など）

インストール

クイックセットアップ

MCP サーバーをグローバルにインストールします：

npm install -g @testingbot/mcp-server

または、プロジェクトに追加します：

npm install @testingbot/mcp-server

設定

推奨：tb_login でログインする（コピーするキーやシークレットは不要です）

API 認証情報を探して貼り付ける必要はありません。サーバーをインストールし、認証情報を空欄のままにして、エージェントに次のように頼むだけです。

TestingBot にログインしてください。

エージェントは tb_login ツールを呼び出します。OAuth 形式のブラウザー認証を使用するため、シークレットがブラウザーの外に出ることはありません。また、環境に適した方式が自動的に選択されます。

• ブラウザー（ループバック。デスクトップではデフォルト）： ブラウザーで TestingBot の認証ページが開きます。必要に応じてサインインし、Authorize をクリックしてください。認証情報はローカルのコールバックで取得され、エージェントがサインインを完了します。入力は不要です。（RFC 8252。）

• デバイスコード（SSH／リモート／開発コンテナー／ウェブでは自動フォールバック）： 代わりに、ツールが短い URL とコードを表示します。

  1. ブラウザーで URL を開きます（例：https://testingbot.com/device）。
  2. コードを入力し、必要に応じてサインインして、Authorize をクリックします。
  3. 認証したことをエージェントに伝えます。エージェントが tb_login を再度呼び出して完了します。

  （RFC 8628。）

tb_login に mode: "loopback" または mode: "device" を渡すと、方式を指定できます（デフォルトは "auto" です）。

認証情報は ~/.testingbot/credentials（モード 0600）に書き込まれ、以降のすべてのツール呼び出しで使用されます。再起動や JSON の編集は不要です。これはすべての MCP クライアント（VS Code、Cursor、Cline、Claude Desktop など）で動作します。別のアカウントを使用するには TESTINGBOT_PROFILE を設定し、ファイルの保存先を変更するには TESTINGBOT_CONFIG_DIR を設定してください。

環境変数

または（環境変数がファイルより優先される CI での使用など）、TestingBot の認証情報を環境変数として設定します。

export TESTINGBOT_KEY="your-api-key"
export TESTINGBOT_SECRET="your-api-secret"

または、プロジェクトに .env ファイルを作成します。

TESTINGBOT_KEY=your-api-key
TESTINGBOT_SECRET=your-api-secret

キーにはエイリアス TB_KEY／TESTINGBOT_USERNAME も使用できます。シークレットには TB_SECRET／TESTINGBOT_ACCESS_KEY も使用できます。

認証情報の解決方法

認証情報は、優先度の高い順に次のように解決されます。

1. 環境変数（上記）。キーとシークレットの両方を設定する必要があります。これにより、CI やクライアントごとの設定で、ほかのすべての設定を上書きできます。
2. tb_login によって書き込まれた、アクティブなプロファイル（default または TESTINGBOT_PROFILE）用の ~/.testingbot/credentials ファイル。
3. どちらも設定されていない場合： サーバーは縮退モードで起動し、tb_login 以外のすべてのツールが「Run tb_login to authenticate」と報告します。そのため、初回実行時に致命的なエラーが発生するのではなく、自動的に復旧できます。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%/Claude/claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  }
}

VS Code（Continue 拡張機能を使用）

.continue/config.json に追加します。

{
  "mcpServers": [
    {
      "name": "testingbot",
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  ]
}

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret"
      }
    }
  }
}

🤖 AI エージェントにリモートブラウザーやデバイスを操作させる

このサーバーには、@testingbot/automation-mcp の自動化ツールがすでに含まれています。このパッケージをインストールすると、TestingBot のグリッド上にあるリモートブラウザーや実機のモバイルデバイスを、リソースの管理だけでなく、エージェントが実際に操作できるようになります。

次のように頼むだけです。

TestingBot で macOS 上の Safari 17 を開いてください。example.com に移動し、「More information」リンクをクリックしてください。

エージェントは tb_openBrowser、tb_navigate、tb_snapshot、tb_click を呼び出し、リアルタイムで動作を確認できるライブビュー URLを表示します。実機の iOS／Android デバイスでは、同梱の appium-mcp 子サーバーにより、エージェントは完全な appium_* ツール一式（appium_session_management、appium_gesture、appium_set_value、appium_screenshot など約 30 個）を利用できます。個別のインストールや設定は不要です。「TestingBot で iOS 17 の iPhone 15 Pro を開き、ログインボタンをタップして、スクリーンショットを撮ってください」と頼むだけです。すべてのツールの一覧、注意事項（セッションは従量課金です）、設定オプションについては、@testingbot/automation-mcp README を参照してください。

利用可能なツール

ライブテスト

startLiveSession

TestingBot でインタラクティブなライブテストセッションを開始します。手動テスト用に実際のブラウザーまたはモバイルデバイスを開きます。

パラメーター：

• platformType：「desktop」または「mobile」
• desiredURL：開く URL
• desiredOS：オペレーティングシステム（デスクトップの場合は Windows、Mac、Linux、モバイルの場合は android、ios）
• desiredOSVersion：OS のバージョン
• desiredBrowser（デスクトップのみ）：ブラウザー名（chrome、firefox、safari、edge、ie）
• desiredBrowserVersion（デスクトップのみ）：ブラウザーのバージョン、または「latest」
• desiredDevice（モバイルのみ）：デバイス名（例：「iPhone 14」、「Galaxy S23」）

プロンプトの例：

「https://example.com を対象に、Windows 11 の Chrome latest でライブテストセッションを開始して」 「手動テスト用に、iOS 16 の iPhone 14 で https://myapp.com を開いて」

startDesktopLiveSession

デスクトップブラウザーのライブテストセッションを開始するための便利なツールです。

パラメーター：

• desiredURL：開く URL
• desiredOS：Windows、Mac、または Linux
• desiredOSVersion：OS のバージョン
• desiredBrowser：chrome、firefox、safari、edge、または ie
• desiredBrowserVersion（任意）：ブラウザーのバージョン、または「latest」（デフォルト：latest）

プロンプトの例：

「https://example.com を対象に、Mac Monterey の Firefox 120 でデスクトップのライブセッションを開始して」

startMobileLiveSession

モバイルデバイスのライブテストセッションを開始するための便利なツールです。

パラメーター：

• desiredURL：開く URL
• desiredOS：android または ios
• desiredOSVersion：OS のバージョン
• desiredDevice：デバイス名

プロンプトの例：

「https://example.com を対象に、Android 13 の Galaxy S23 でモバイルのライブセッションを開始して」

ブラウザーとデバイスの管理

getBrowsers

テストに利用できるブラウザーとプラットフォームの一覧を取得します。

パラメーター：

• type（任意）：「web」または「mobile」で絞り込みます

プロンプトの例：

「テストに利用できるすべてのブラウザーを表示して」 「利用できるモバイルブラウザーを教えて」

getDevices

利用できるモバイルデバイス（実機とシミュレーター）の一覧を取得します。

プロンプトの例：

「利用できるすべての iOS デバイスを一覧表示して」 「テスト用の Android デバイスを表示して」

テストの管理

getTests

ページネーションを使用して最近のテスト一覧を取得します。

パラメーター：

• offset（任意）：ページネーションのオフセット（デフォルト：0）
• limit（任意）：取得するテスト数（デフォルト：10、最大：100）

プロンプトの例：

「直近 20 件のテストを表示して」 「最近のテスト結果を取得して」

getTestDetails

特定のテストに関する詳細情報を取得します。以下が含まれます。

• テストのステータス、ブラウザー、プラットフォーム、タイミング情報
• 動画録画の URL とスクリーンショットの URL
• Selenium、ブラウザー、Appium のログ
• コマンドとタイムスタンプを含むテスト実行手順
• ネットワークログ、例外ログ、JS エラー

パラメーター：

• sessionId：テストのセッション ID

プロンプトの例：

「テストセッション abc123 の詳細を取得して」 「テスト xyz789 の動画とログを表示して」 「テスト abc123 の実行手順を表示して」

updateTest

名前、ステータス、ビルドなどのテストメタデータを更新します。

パラメーター：

• sessionId：テストのセッション ID
• name（任意）：テストの新しい名前
• status（任意）：「passed」または「failed」
• build（任意）：ビルド識別子
• extra（任意）：追加のメタデータ（JSON 文字列）

プロンプトの例：

「テスト abc123 を passed にして」 「テスト xyz789 の名前を『Login Flow Test』に更新して」

deleteTest

セッション ID を指定してテストを削除します。

パラメーター：

• sessionId：削除するテストのセッション ID

プロンプトの例：

「テスト abc123 を削除して」

stopTest

セッション ID を指定して実行中のテストを停止します。

パラメーター：

• sessionId：停止するテストのセッション ID

プロンプトの例：

「テスト abc123 を停止して」

ビルドの管理

getBuilds

ページネーションを使用してビルドの一覧を取得します。

パラメーター：

• offset（任意）：ページネーションのオフセット（デフォルト：0）
• limit（任意）：取得するビルド数（デフォルト：10、最大：100）

プロンプトの例：

「最近のビルドを表示して」

getTestsForBuild

特定のビルド ID に関連付けられたすべてのテストを取得します。

パラメーター：

• buildId：ビルド ID

プロンプトの例：

「ビルド 12345 のすべてのテストを表示して」

deleteBuild

ビルドと、関連付けられたすべてのテストを削除します。

パラメーター：

• buildId：削除するビルド ID

プロンプトの例：

「ビルド 12345 を削除して」

ストレージ管理

uploadFile

ローカルファイル（APK、IPA、または ZIP）を TestingBot ストレージにアップロードします。

パラメーター：

• localFilePath：アップロードするファイルのパス

プロンプトの例：

「/path/to/app.apk を TestingBot にアップロードして」

uploadRemoteFile

リモート URL からファイルを TestingBot ストレージにアップロードします。

パラメーター：

• remoteUrl：アップロードするファイルの URL

プロンプトの例：

「https://example.com/app.ipa を TestingBot にアップロードして」

getStorageFiles

TestingBot ストレージ内のすべてのファイルを一覧表示します。

パラメーター：

• offset（任意）：ページネーションのオフセット（デフォルト：0）
• limit（任意）：取得するファイル数（デフォルト：10、最大：100）

プロンプトの例：

「アップロード済みのアプリをすべて表示して」

deleteStorageFile

TestingBot ストレージからファイルを削除します。

パラメーター：

• appUrl：削除するファイルの app_url

プロンプトの例：

「ストレージからアプリ tb://app123 を削除して」

App Automate — Maestro

Maestro のフローを TestingBot の実機、エミュレーター、シミュレーターで実行します。実行は非同期です。実行を開始し、ステータスをポーリングしてから結果を取得するため、デバイスで実行している間もエージェントがブロックされることはありません。

uploadMaestroApp

テスト対象のアプリ（.apk、.aab、.ipa、または ZIP 形式の .app）をアップロードします。チェックサムで重複を判定するため、同じバイナリを再アップロードする場合は即座に完了します。

パラメーター：

• localFilePath：アプリファイルのローカルパス

他の Maestro ツールで使用するプロジェクト IDを返します。

プロンプトの例：

「Maestro テスト用に ./build/app.apk をアップロードして」

uploadMaestroFlows

プロジェクトの Maestro フロー YAML ファイルをアップロードします。ディレクトリ（構造が保持されるため、runFlow のサブフローも引き続き機能します）、作成済みの .zip、またはエージェントが記述したインライン YAMLを受け付けます。以前にアップロードされたフローは置き換えられます。

パラメーター：

• projectId：uploadMaestroApp が返したプロジェクト ID
• flowsPath（任意）：フロー YAML ファイルのディレクトリまたは .zip
• flows（任意）：[{ fileName, content }] 形式のインラインフロー

runMaestroTest

Maestro の実行を開始します。実行 ID をすぐに返します。getMaestroRunStatus でポーリングしてください。

パラメーター：

• projectId：プロジェクト ID
• platformName：「Android」または「iOS」
• deviceName（任意）：デバイス名。ワイルドカード／正規表現をサポートします（例："Pixel 8"、"iPhone 1[4-6]"、"*"）
• version（任意）：OS バージョン
• realDevice（任意）：実機で実行します（.ipa の場合は必須）
• name（任意）：ダッシュボードに表示される実行名
• env（任意）：フローに渡す環境変数
• includeTags / excludeTags（任意）：Maestro タグでフローを絞り込みます
• shardSplit（任意）：フローを複数のデバイスに分割して並列実行します
• otherApps（任意）：アプリと一緒にインストールする、最大 4 つのコンパニオンアプリの URL

プロンプトの例：

「Android 14 を搭載した実機の Pixel 8 で Maestro フローを実行して」

getMaestroRunStatus

実行の進行状況をポーリングします。フローごとのステータス（WAITING、READY、DONE、FAILED、CANCELLED）を一覧表示します。失敗したフローが先に表示されます。

getMaestroRunResults

完了した実行の最終結果を取得します。フローごとの結果と JUnit XML レポートが含まれます。

getMaestroFlowDetails

1 つのフローを詳しく調査します。エラーメッセージ、ステップレベルの JUnit レポート、動画、スクリーンショット、デバイスログへのリンクを取得します。これはデバッグ用のツールです。失敗したフローの詳細を取得し、YAML を修正してから再試行してください。

パラメーター： projectId、runId、flowId

cancelMaestroRun / retryMaestroRun

実行中の実行をキャンセルするか、実行を再試行します。失敗したフローを 1 つだけ再試行するには、flowId を指定します。

uploadMaestroCompanionApp

テスト対象のアプリと一緒にインストールする補助アプリをアップロードします。runMaestroTest の otherApps で使用する tb:// URL を返します。

listMaestroProjects / listMaestroRuns

既存のプロジェクト（アプリ、フロー、実行 ID）と、アカウント全体の実行を確認します。listMaestroRuns は buildName を指定して名前で実行を検索できます。たとえば、「昨夜の nightly ビルドで失敗したものをすべて再実行する」といった用途に使えます。

maestroCheatSheet

Maestro の YAML 構文リファレンス（コマンド、セレクター、フロー構造、TestingBot のワークフロー）を返します。エージェントは、フローの作成や修正の前にこのツールを呼び出します。

ワークフローの例：

User: "Run the Maestro flows in ./flows against ./app.apk on a real Pixel 8. Fix any failures."
Assistant: [uploadMaestroApp → uploadMaestroFlows → runMaestroTest]
Assistant: [polls getMaestroRunStatus until complete]
Assistant: [getMaestroFlowDetails for the failed flow, reads the error + screenshots]
Assistant: [fixes the flow YAML, uploadMaestroFlows, retryMaestroRun]

App Automate — Espresso と XCUITest

TestingBot のデバイスで、事前に作成した Espresso（Android）および XCUITest（iOS）のテストスイートを実行します。非同期のパターンは同じです。開始し、ポーリングして、結果を取得します。

uploadAppAutomateApp

テスト対象のアプリをアップロードします。Espresso では .apk / .aab、XCUITest では .ipa を使用します。

パラメーター： framework（"espresso" または "xcuitest"）、localFilePath

uploadAppAutomateTests

テストスイートをアップロードします。Espresso ではインストルメント化されたテスト用の .apk、XCUITest では ZIP 圧縮した XCUITest ランナーバンドルを使用します。

パラメーター： framework、projectId、localFilePath

runAppAutomateTest

テストの実行を開始します。実行 ID をすぐに返します。

パラメーター：

• framework、projectId
• deviceName、version、realDevice、name、build（任意）：デバイスの選択とメタデータ
• testClasses、skipTestClasses、packages、annotations、testRunner（任意、Espresso のみ）：テストのフィルタリング
• locale、timeZone（任意）

プロンプトの例：

「実機の Galaxy S23 で、com.example.LoginTest クラスだけを Espresso で実行してください」

getAppAutomateRunStatus / getAppAutomateRunResults

実行の進行状況をポーリングしてから、実行ごとの結果と JUnit XML レポートを取得します。各実行の Appium セッション ID が表示されるため、ログや動画を確認する際に getTestDetails / getFailureLogs を利用できます。

スクリーンショットテスト

takeScreenshot

複数のブラウザーやプラットフォームで、URL のスクリーンショットを撮影します。

パラメーター：

• url：スクリーンショットを撮影する URL
• browsers：ブラウザー設定の配列
  • browserName：ブラウザー名（chrome、firefox、safari など）
  • version（任意）：ブラウザーのバージョン、または "latest"
  • os：オペレーティングシステム（WIN11、MAC など）
• resolution（任意）：画面解像度（デフォルト："1920x1080"）
• waitTime（任意）：スクリーンショット撮影前に待機する秒数（デフォルト：5、最大：60）
• fullPage（任意）：ページ全体をキャプチャするか、ビューポートをキャプチャするか（デフォルト：false）

プロンプトの例：

"https://example.com のスクリーンショットを Chrome と Firefox で撮影してください" "モバイルデバイスでホームページのスクリーンショットを撮影してください"

retrieveScreenshots

スクリーンショット ID を指定して、スクリーンショットの結果を取得します。

パラメーター：

• screenshotId：takeScreenshot から返されたスクリーンショット ID

プロンプトの例：

"ジョブ abc123 のスクリーンショットを取得してください"

getScreenshotList

すべてのスクリーンショットジョブの一覧を取得します。

パラメーター：

• offset（任意）：ページネーションのオフセット（デフォルト：0）
• limit（任意）：取得するジョブ数（デフォルト：10、最大：100）

プロンプトの例：

"最近のスクリーンショットジョブを表示してください"

ユーザー管理

getUserInfo

使用済み分数、プランの詳細、上限など、現在のユーザーアカウント情報を取得します。

プロンプトの例：

"アカウント情報を表示してください" "何分使用しましたか？"

updateUserInfo

ユーザーアカウント情報を更新します。

パラメーター：

• firstName（任意）：名
• lastName（任意）：姓
• email（任意）：メールアドレス

プロンプトの例：

"メールアドレスを [email protected] に更新してください"

チーム管理

getTeam

並列実行数の上限、許可された並列 VM 数、モバイルの並列実行数など、チーム情報を取得します。

プロンプトの例：

"チーム情報を表示してください" "チームの並列実行数の上限を教えてください"

getUsersInTeam

チーム内のすべてのユーザーを、役割とアクセスレベルとともに一覧表示します。

パラメーター：

• offset（任意）：ページネーションのオフセット（デフォルト：0）
• limit（任意）：取得するユーザー数（デフォルト：10、最大：100）

プロンプトの例：

"チームメンバー全員を表示してください" "チーム内のユーザーを一覧表示してください"

getUserFromTeam

ユーザー ID を指定して、特定のチームメンバーの詳細情報を取得します。

パラメーター：

• userId：取得するユーザー ID

プロンプトの例：

「ユーザー 12345 の詳細を表示して」

Chrome DevTools Protocol (CDP)

createCdpSession

高度なブラウザー自動化のための Chrome DevTools Protocol セッションを作成します。ブラウザーへの接続に使用する WebSocket URL を返します。

パラメーター：

• browserName：ブラウザー名（chrome、firefox、safari、edge など）
• browserVersion（任意）：ブラウザーのバージョンまたは「latest」（デフォルト：latest）
• platform：オペレーティングシステムのプラットフォーム
• screenResolution（任意）：画面解像度（例：「1920x1080」）
• name（任意）：セッション名
• build（任意）：ビルド識別子

プロンプトの例：

「Windows 11 で Chrome latest の CDP セッションを作成して」 「自動化用に Firefox 120 の CDP セッションを開始して」

トンネル管理

getTunnelList

アクティブな TestingBot トンネルの一覧を取得します。トンネルを使うと、ファイアウォールの背後やローカルマシン上のウェブサイトをテストできます。

プロンプトの例：

「アクティブなトンネルをすべて表示して」 「TestingBot のトンネルを一覧表示して」

deleteTunnel

ID を指定してアクティブな TestingBot トンネルを削除します。これにより、トンネル接続が終了します。

パラメーター：

• tunnelId：削除するトンネル ID

プロンプトの例：

「トンネル 12345 を削除して」

使用例

例 1：クロスブラウザーテストの実行

User: "Show me all available browsers for web testing"
Assistant: [Lists all web browsers]

User: "Take a screenshot of https://myapp.com on Chrome latest and Firefox latest on Windows 11"
Assistant: [Creates screenshot job and returns ID]

User: "Get the screenshots for job abc123"
Assistant: [Returns screenshot URLs]

例 2：モバイルアプリテストの管理

User: "Upload my app from https://example.com/app.apk"
Assistant: [Uploads app and returns tb://app123]

User: "Show me all my uploaded apps"
Assistant: [Lists storage files]

User: "Show me the last 10 tests"
Assistant: [Shows recent test results]

例 3：実機でのエージェント駆動型 Maestro テスト

User: "Write a Maestro flow that logs into my app and run it on a real Pixel 8"
Assistant: [maestroCheatSheet for syntax, writes the flow YAML]
Assistant: [uploadMaestroApp ./app.apk → project 42]
Assistant: [uploadMaestroFlows with the inline flow]
Assistant: [runMaestroTest on Pixel 8 with realDevice: true → run 101]
Assistant: [polls getMaestroRunStatus, then getMaestroRunResults]

User: "The checkout flow failed — figure out why and fix it"
Assistant: [getMaestroFlowDetails → reads error + screenshots + video]
Assistant: [fixes the YAML, uploadMaestroFlows, retryMaestroRun]

例 4：ビルド管理

User: "Show me my recent builds"
Assistant: [Lists recent builds]

User: "Show all tests for build 12345"
Assistant: [Lists tests in that build]

User: "Mark test xyz789 as passed with build name 'Release 1.0'"
Assistant: [Updates test]

例 5：チームとトンネルの管理

User: "Show me my team information"
Assistant: [Shows team concurrency limits and settings]

User: "List all team members"
Assistant: [Lists all users in the team]

User: "Show me all active tunnels"
Assistant: [Lists active TestingBot tunnels]

例 6：CDP 自動化

User: "Create a CDP session on Chrome latest with Windows 11"
Assistant: [Creates session and returns WebSocket URL]

User: "Show me test execution steps for session abc123"
Assistant: [Shows detailed command history with timestamps]

開発

セットアップ

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

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

コマンド

# Build the project (runs lint, format, test, and compile)
npm run build

# Development mode with watch
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Build the .mcpb bundle for Claude Desktop (see section below)
npm run mcpb

ローカルでの実行

# Development mode
npm run dev

# Production mode
npm start

MCP Inspector でのテスト

開発中にツールをテストするには、MCP Inspector を使用します。

npx @modelcontextprotocol/inspector node dist/index.js

その後、ブラウザーで http://localhost:5173 を開きます。

.mcpb バンドルのビルド（Claude Desktop リリース）

.mcpb アーカイブは、ユーザーがダブルクリックして Claude Desktop にインストールするファイルです。インストーラーは manifest.json#user_config を読み込み、認証情報の入力を促します。JSON の編集や環境変数の調整は不要です。

# Prerequisites: mcpb CLI (one-time)
npm install -g @anthropic-ai/mcpb

# Build the bundle
npm run mcpb

これにより scripts/build-mcpb.sh が実行され、次の処理が行われます。

1. 品質チェックの全工程を実行します（npm run build → lint → format → test → tsc）。
2. 一時ディレクトリにクリーンなツリーをステージングします（dist/、manifest.json、package.json、LICENSE、README.md、存在する場合は icon.png のみ）。
3. ステージング内で npm ci --omit=dev を実行します。開発用依存関係（typescript、eslint、vitest）はバンドルに含まれません。@testingbot/automation-mcp は package.json で固定されたバージョンが npm から取得されます。
4. マニフェストを検証し、.mcpbignore に従って mcpb pack を実行します（テスト用フィクスチャー、ソースマップ、依存関係の変更履歴を除外します）。
5. releases/testingbot-mcp-server-<version>.mcpb を書き込み、mcpb info を実行します。

出力サイズは約 160 MB です。その大部分を占めるのは、バンドルされたモバイルドライバースタック appium-mcp（XCUITest、UiAutomator2）です。バンドルの料金が発生するのはインストール時の一度だけで、実行時には発生しません。

開発中の関連リポジトリ

@testingbot/mcp-server と @testingbot/automation-mcp の両方を連携して開発する場合は、このリポジトリで npm run dev:rebuild を使用します。両方をビルドした後、関連リポジトリをこのリポジトリの node_modules に npm link でリンクするため、再公開しなくても、次回の再ビルド後に ../testingbot-automation-mcp/src/ の編集内容が反映されます。

このリンクは一度だけ設定します。いったん設定すると、dev:rebuild はリンクが存在することを検知し、ビルドのみを実行します。このリポジトリで npm install を実行するとリンクがレジストリ版に置き換わるため、dev:rebuild を再実行して復元してください。

リリース

リリースフローでは、連携して進める 2 つの公開手順があります。

1. @testingbot/automation-mcp を npm に公開します（../testingbot-automation-mcp から実行）：

   npm version patch    # or minor / major
   npm publish          # publishConfig.access is "public" — handles scoped-pkg defaults
   

2. このリポジトリで新しい automation-mcp を利用するよう更新し、リリースを作成します：

   npm install @testingbot/automation-mcp@latest   # updates package-lock.json
   npm version patch                                # also syncs manifest.json + server.json
   git push --follow-tags
   # → Create a GitHub release at the new tag. The Build MCPB workflow
   #   fires on release:published and attaches releases/*.mcpb to it.
   

リリース CI（.github/workflows/build-mcpb.yml）は macos-latest で npm run mcpb を実行し、バンドルをワークフローのアーティファクト（30 日間保持）とリリースアセットの両方としてアップロードします。手動で再ビルドするには、Actions タブから「Build MCPB bundle」を実行し、タグを入力します。

バンドルされた appium-xcuitest-driver にネイティブコンポーネントを含めるため、macOS を選択しています。Linux／Windows のユーザーのみを対象にする場合は、ランナーを ubuntu-latest に切り替えると、分数あたりの料金を約 10 分の 1 に抑えられます。ただし、バンドルされたモバイル機能で iOS のサポートが失われます。WebDriver を介したブラウザツールは、どちらの場合もクロスプラットフォームで動作します。

ビルドせずにマニフェストを検証するには、次のコマンドを実行します。

npm run mcpb:validate

ビルド済みのバンドルを確認するには、次のコマンドを実行します。

mcpb info releases/testingbot-mcp-server-<version>.mcpb
mcpb unpack releases/testingbot-mcp-server-<version>.mcpb /tmp/unpacked  # see what's inside

バンドルは署名されていません。配布用に署名するには、mcpb sign --self-signed（スモークテスト用）を実行するか、実際の証明書を指定して mcpb sign を実行します。詳しくは mcpb sign --help を参照してください。

releases/*.mcpb は Git の追跡対象外です。ビルド後、アーティファクトを GitHub のリリースページ（またはインストール URL の参照先）にアップロードしてください。

プロジェクト構成

testingbot-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server-factory.ts     # MCP server setup
│   ├── config.ts             # Configuration management
│   ├── lib/
│   │   ├── types.ts          # TypeScript types
│   │   ├── constants.ts      # Constants and enums
│   │   ├── error.ts          # Error classes
│   │   ├── logger.ts         # Logging setup
│   │   ├── utils.ts          # Utility functions
│   │   ├── get-auth.ts       # Authentication helpers
│   │   └── app-automate-client.ts  # REST client for Maestro/Espresso/XCUITest
│   └── tools/
│       ├── maestro.ts        # Maestro run tools (upload, run, poll, diagnose)
│       ├── app-automate.ts   # Espresso & XCUITest run tools
│       ├── browsers.ts       # Browser & device tools
│       ├── tests.ts          # Test management tools
│       ├── builds.ts         # Build management tools
│       ├── storage.ts        # Storage tools
│       ├── screenshots.ts    # Screenshot tools
│       ├── user.ts           # User management tools
│       ├── team.ts           # Team management tools
│       ├── cdp.ts            # Chrome DevTools Protocol tools
│       ├── tunnels.ts        # Tunnel management tools
│       └── live.ts           # Live testing session tools
├── tests/
│   └── tools/                # Unit tests
├── dist/                     # Compiled output
└── package.json

トラブルシューティング

認証エラー

認証エラーが表示された場合は、次を試してください。

1. tb_login ツールを実行します（エージェントに「TestingBot にログインして」と頼むだけです）。キーやシークレットが不要なため、最も簡単な方法です。
2. または、https://testingbot.com/members/user/security で認証情報を確認します。
3. 環境変数が正しく設定されていることを確認します（環境変数は tb_login の認証情報ファイルより優先されます）。
4. 認証情報に余分なスペースが含まれていないことを確認します。

接続の問題

MCP サーバーに接続できない場合は、次を試してください。

1. MCP クライアント（Claude Desktop、VS Code など）を再起動します。
2. MCP クライアントのログにエラーがないか確認します。
3. Node.js のバージョンが >= 20 であることを確認します。

ツールの実行エラー

ツールを実行できない場合は、次を試してください。

1. サーバーログで詳細なエラーメッセージを確認します。
2. TestingBot アカウントで十分な権限／クォータがあることを確認します。
3. 必須のパラメーターがすべて指定されていることを確認します。

デバッグログ

デバッグログを有効にするには、LOG_LEVEL 環境変数を設定します。

export LOG_LEVEL=debug

または、MCP クライアントの設定で指定します。

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server"],
      "env": {
        "TESTINGBOT_KEY": "your-api-key",
        "TESTINGBOT_SECRET": "your-api-secret",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）。
3. 変更をコミットします（git commit -m 'Add some amazing feature'）。
4. ブランチにプッシュします（git push origin feature/amazing-feature）。
5. プルリクエストを作成します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

サポート

• 📧 メール：[email protected]
• 🐛 問題：GitHub Issues
• 📖 ドキュメント：TestingBot MCP Documentation

関連項目

• TestingBot API Package
• Model Context Protocol
• TestingBot Platform