wopee-mcp

Wopee MCP Server

アプリ向けのAIによる自律テストです。Claude、Cursor、またはMCP互換のAIエージェントをWopee.ioに接続すると、テストケースやユーザーストーリーを生成し、数秒で自律テストを実行できます。

npx wopee-mcp

ドキュメント | ランディングページ | ダッシュボード

セットアップ

前提条件

• Node.js（v18以上を推奨）
• CursorやVSCodeなど、MCP（Model Context Protocol）をサポートするIDE

MCP サーバーの設定

このサーバーをMCP設定に追加します。

設定例

{
  "mcpServers": {
    "wopee": {
      "command": "npx wopee-mcp",
      "env": {
        "WOPEE_PROJECT_UUID": "your-project-uuid-here",
        "WOPEE_API_KEY": "your-api-key-here"
      }
    }
  }
}

必須環境変数

• WOPEE_PROJECT_UUID - WopeeプロジェクトのUUIDです。作業対象のプロジェクトを識別します。
• WOPEE_API_KEY - WopeeのAPIキーです。cmd.wopee.ioで、プロジェクトの設定から作成できます。

任意の環境変数

• WOPEE_API_URL - Wopee APIのエンドポイントURLです。テストまたは開発目的の場合にのみ指定してください。

企業プロキシの設定

企業プロキシ／VPNを使用していて接続タイムアウトが発生する場合は、標準の環境変数を使ってプロキシ設定を構成できます。

{
  "mcpServers": {
    "wopee": {
      "command": "npx wopee-mcp",
      "env": {
        "WOPEE_PROJECT_UUID": "your-project-uuid-here",
        "WOPEE_API_KEY": "your-api-key-here",
        "HTTPS_PROXY": "http://your-proxy-server:8080"
      }
    }
  }
}

サポートされているプロキシ環境変数

• HTTPS_PROXY または https_proxy - HTTPS接続用のプロキシサーバーURL（推奨）
• HTTP_PROXY または http_proxy - 代替プロキシサーバーURL

プロキシ設定の確認方法

プロキシ設定が不明な場合は、VS Codeの設定（settings.json）でhttp.proxyの値を確認するか、IT部門にお問い合わせください。一般的な企業プロキシの形式は次のとおりです。

• http://proxy.company.com:8080
• http://10.x.x.x:8080
• http://username:[email protected]:8080（認証が必要な場合）

TLS／証明書の問題

MCPの動作にこれは必要ありません。 HTTPSまたは証明書関連のエラーが表示される場合は、環境内のTLSまたは証明書の信頼に関する問題を示しています。

**UNABLE_TO_VERIFY_LEAF_SIGNATUREやcertificate has expired**などのエラーでサーバーが失敗する場合、次の原因が考えられます。

• 自己署名証明書（例：WOPEE_API_URLが内部サーバーまたは開発サーバーを指している場合）
• 企業プロキシ／SSLインスペクション（企業CAでトラフィックが再暗号化されており、そのCAをマシンが信頼していない場合）
• NodeのトラストストアにCA証明書がない

推奨される解決方法（安全）

1. 有効なTLS証明書を使用します。たとえば、Let’s Encryptまたは内部CAを使用し、証明書チェーン全体が提供されるようにします。

2. Nodeが信頼できるように、企業または内部CAをインストールします。

   例：

   export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-ca.pem
   

   MCP設定のenvに追加します。

   "env": {
     "WOPEE_PROJECT_UUID": "your-project-uuid-here",
     "WOPEE_API_KEY": "your-api-key-here",
     "NODE_EXTRA_CA_CERTS": "/path/to/ca.pem"
   }
   

安全性の低い回避策（非推奨）

ローカルでのデバッグに限り、NodeのTLS検証を無効にできます。本番環境では絶対に使用しないでください。HTTPSのセキュリティが無効になり、トラフィックが傍受される危険があります。

export NODE_TLS_REJECT_UNAUTHORIZED=0

または、MCP設定のenvに追加します。

"env": {
  "WOPEE_PROJECT_UUID": "your-project-uuid-here",
  "WOPEE_API_KEY": "your-api-key-here",
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}

これはデバッグ専用の一時的な回避策として扱い、通常のセットアップ手順として使用しないでください。

注： PYTHONHTTPSVERIFY=0も設定したという報告があります。このMCPサーバーはPythonを使用しないため、この変数は影響しません。この変数が適用されるのは、PythonベースのMCPホスト、または同じ環境でHTTPSを使用するその他のツールを実行している場合のみであり、このサーバーの範囲外です。

はじめに

このMCPサーバーのほとんどのツールでは、動作にsuiteUuidが必要です。開始方法は2つあります。

オプション1：既存のスイートを使用する

まず、既存の分析スイートを取得します。

Use the wopee_fetch_analysis_suites tool to retrieve all available suites for your project.

UUIDを含むすべての分析スイートの一覧が返されます。そのUUIDを他のツールで使用できます。

オプション 2：新しいスイートを作成する

まだスイートがない場合は、次の 2 つの方法があります。

自動分析： 分析／クローリングを行うスイートを作成して実行します。

Use the wopee_dispatch_analysis tool to create and dispatch a new analysis/crawling suite.

空のスイート： 手動で設定するための空のスイートを作成します。

Use the wopee_create_blank_suite tool to create a blank analysis suite.

どちらの方法でもスイートの UUID が返されます。UUID は以降の操作で使用できます。

利用可能なツール

スイート管理

wopee_fetch_analysis_suites

プロジェクトのすべての分析スイートを取得します。利用可能なスイートを確認するのに適した方法です。

• 戻り値： UUID、名前、ステータス、メタデータを含む分析スイートの配列

使用例：

Fetch all existing analysis suites for my project

wopee_dispatch_analysis

プロジェクトの新しい分析／クローリングスイートを作成して実行するか、既存のスイートを再実行します。新しい分析セッションを開始したり、以前の分析を再度実行したりするときに使用します。

• パラメーター：
  • additionalInstructions (任意) - 分析／クローリング中にエージェントを誘導する追加の指示（注目する領域、無視する項目、ログイン手順など）
  • additionalVariables (任意) - 分析に渡す追加の環境変数。オブジェクトの配列で、各オブジェクトには次の内容を指定します。
    • key - 変数名。大文字とアンダースコアのみを使用する必要があります（例：MY_VAR、BASE_URL）
    • value - 変数の値（空でない文字列）
  • rerun (任意) - 指定すると、新しいスイートを作成せずに既存の分析スイートを再実行します。次の内容を持つオブジェクトです。
    • suiteUuid - 再実行する既存スイートの UUID
    • analysisIdentifier - 既存スイートの分析識別子
    • mode - 再実行モード：FULL（クローリングと生成を含む分析全体を再実行）または CRAWLING（クローリングフェーズのみを再実行）
• 戻り値： 作成または再実行したスイートの情報を含む成功メッセージ

使用例：

Dispatch a new analysis suite

Dispatch a new analysis suite and focus on the checkout flow

Dispatch a new analysis suite with additional variables CARD_FILAMENT=123321123 and AUTH_TOKEN=abc123

Rerun the full analysis for suite <suiteUuid> with analysis identifier <analysisIdentifier>

Rerun only the crawling phase for suite <suiteUuid> with analysis identifier <analysisIdentifier>

wopee_create_blank_suite

プロジェクトの空の分析スイートを作成します。自動分析ではなく、スイートを手動で設定してデータを追加するときに使用します。

• 戻り値： UUID を含む、作成したスイートの情報

使用例：

Create a blank analysis suite for my project

生成ツール

これらのツールは、指定したスイートのさまざまなアーティファクトを生成します。生成にはすべて suiteUuid と type が必要です。

wopee_generate_artifact

選択したスイートの特定のファイル（アーティファクト）を生成します。

• パラメーター：
  • suiteUuid - スイートの UUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES_WITH_TEST_CASES" | "TEST_CASES" | "TEST_CASE_STEPS" | "REUSABLE_TEST_CASES" | "REUSABLE_TEST_CASE_STEPS"
  • mode (任意、TEST_CASES のみ) - "UPDATE"（デフォルト）では、既存のテストケースとそのステップ、実行履歴を保持します。"CREATE" では、対象範囲内のテストケースを置き換え、そのステップ、実行、コードを削除します
  • selectedUserStories (任意) - TEST_CASES／TEST_CASE_STEPS の対象を絞り込むユーザーストーリー ID（例：["US001"]）。空の場合はすべてのストーリーが対象になります
  • selectedTestCases (任意) - TEST_CASE_STEPS の対象を絞り込むテストケース識別子（例：["US001:TC002"]）
  • instructions (任意) - AI エンジンに渡す変更リクエスト
  • async (任意、TEST_CASES／USER_STORIES_WITH_TEST_CASES) - アーティファクトの完了を待たず、実行がキューに追加された時点で返します
• 戻り値： 生成に成功した場合、生成された出力

使用例：

Generate app context for my most recent analysis suite

取得ツール

これらのツールは、指定したスイートの生成済みアーティファクトを取得します。すべて suiteUuid と type が必要です。

wopee_fetch_artifact

選択したスイートから指定されたファイル（アーティファクト）を取得します。

• パラメーター：
  • suiteUuid - スイートの UUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES" | "PLAYWRIGHT_CODE" | "PROJECT_CONTEXT"
  • identifier - Playwright コードを取得するテストケースの識別子（例：US003:TC004）
• 戻り値： 取得に成功した場合、ファイルの内容

使用例：

Fetch user stories for the latest suite

更新ツール

これらのツールは、特定のスイートのファイル（アーティファクト）を更新または設定するために使用します。suiteUuid、type、contentは必須です。

wopee_update_artifact

特定のスイートの既存ファイル（アーティファクト）を更新／置換します

• パラメーター：
  • suiteUuid - スイートのUUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES" | "PLAYWRIGHT_CODE" | "PROJECT_CONTEXT"
  • content - app context、general user stories、project contextのMarkdownコンテンツ、またはuser storiesの構造化JSON
  • identifier - Playwrightコードを取得するテストケースの識別子。例：US003:TC004
• 戻り値： ツール呼び出しの成功状況を示すブール値

使用例：

Update app context file for the most recent suite with this content: <YourMarkdown>

エージェントテスト

wopee_dispatch_agent

選択したスイートのテストケースを実行する自律型テストエージェントをディスパッチします。テストは非同期で実行されます（通常1～3分）。このツールはディスパッチを確認し、追跡情報を返します。最終結果は返しません。

• パラメーター：
  • suiteUuid - テストケースを含むスイートのUUID
  • analysisIdentifier - スイートの分析識別子
  • testCases - 実行するテストケースオブジェクトの配列。各オブジェクトには以下が含まれます。
    • testCaseId - テストケースのID
    • userStoryId - 関連付けられたユーザーストーリーのID
• 戻り値： 追跡情報を含むディスパッチ確認（スイートUUID、分析識別子、テストケースごとの実行状況）。合否の結果は返しません。後で結果を確認するには、wopee_fetch_recent_executionsまたはwopee_fetch_executed_test_casesを使用してください。

使用例：

Dispatch agent for my latest suite's user story US001 and test case TC003

テスト結果

wopee_fetch_recent_executions

現在のプロジェクトで最近実行されたテストケースを最大20件、新しい順に取得します。特定のスイートUUIDを覚えておかなくても、最近ディスパッチしたテストの状況をすばやく確認できます。

• パラメーター： なし（環境変数WOPEE_PROJECT_UUIDを使用）
• 戻り値： 実行状況（IN_PROGRESS、IN_QUEUE、FINISHED、FAILED）、エージェントレポート、合否の結果を含む最近の実行一覧

使用例：

What's the status of my recent test runs?

How did my tests go?

wopee_fetch_executed_test_cases

指定した分析スイートの実行済みテストケースとその結果を取得します。ディスパッチしたエージェントの実行状況とレポートを確認するために使用します。

• パラメーター：
  • suiteUuid - 結果を取得する分析スイートのUUID
  • analysisIdentifier (省略可) - 結果を絞り込む分析識別子（例：A068）
• 戻り値： ユーザーストーリーごとにグループ化された結果の配列。各結果には、実行状況、エージェントレポート、エージェントレポートの状態、コードレポート、コードレポートの状態を含む実行済みテストケースが含まれます。

使用例：

Fetch test results for suite <suiteUuid>

Show me the executed test cases for my latest analysis suite

レポート

wopee_create_github_issue

現在のプロジェクトにリンクされているリポジトリに GitHub イシューを作成します。失敗した実行の executedTestCaseUuid を指定すると、Wopee.io は実行に関して把握している情報（失敗したステップ、期待値と実際の値、失敗したステップのスクリーンショット、Commander 内の実行へのリンク）を入力したテキストの下に追加します。

• パラメーター:
  • title - イシューのタイトル
  • body (任意) - Markdown。実行の証拠の上にそのまま保持されます
  • labels (任意) - 適用するラベル。例：["bug"]。リポジトリに存在しないラベルは GitHub によって適用されない場合があります。適用されたラベルは結果に記載されます
  • executedTestCaseUuid (任意) - 証拠を添付する実行。wopee_fetch_recent_executions または wopee_dispatch_agent に表示されます
• 戻り値: イシュー番号と URL、および含められなかった項目（アップロードできなかったスクリーンショットなど）に関する注記
• 要件: イシューは Wopee.io GitHub App によって作成され、本文にはあなたの名前が記載されます。App のインストールには、リポジトリの Issues: Read & write 権限と、別の wopee-issue-assets ブランチにコミットされるスクリーンショット用の Contents: Read & write 権限が必要です。このブランチにはコードとの共通履歴がなく、安全に削除できます。削除すると、既存のイシュー内の画像が表示されなくなるだけです。

使用例:

File the failed checkout test as a GitHub issue

一般的なワークフロー

1. スイートから開始します:

   • wopee_fetch_analysis_suites を使って既存のスイートを確認します。または、
   • wopee_dispatch_analysis を使って新しいスイートを作成します

2. アーティファクトを生成します:

   • アプリのコンテキストを生成するには、APP_CONTEXT と特定の suiteUuid を指定して wopee_generate_artifact を使います
   • 一般的なユーザーストーリーを生成するには、GENERAL_USER_STORIES と特定の suiteUuid を指定して wopee_generate_artifact を使います
   • テストケース付きのユーザーストーリーを生成するには、USER_STORIES_WITH_TEST_CASES と特定の suiteUuid を指定して wopee_generate_artifact を使います
   • 再利用可能なテストケースを生成するには、REUSABLE_TEST_CASES と特定の suiteUuid を指定して wopee_generate_artifact を使います
   • 再利用可能なテストケースのステップを生成するには、REUSABLE_TEST_CASE_STEPS と特定の suiteUuid を指定して wopee_generate_artifact を使います
   • テストケースのステップを生成するには、TEST_CASE_STEPS と特定の suiteUuid を指定して wopee_generate_artifact を使います

3. 生成されたコンテンツを取得します:

   • フェッチツールを使って、生成された Markdown／JSON ファイルを取得します

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

   • wopee_dispatch_agent を使って、自律型テストエージェントでテストケースを実行します

5. 結果を確認します:

   • wopee_fetch_recent_executions を使って、最近のテスト実行のステータスをすばやく確認します
   • wopee_fetch_executed_test_cases を使って、特定のスイートの詳細なステータスとレポートを確認します
   • または、fetch-test-results プロンプトを使って、すべてのテスト結果を整形された要約で確認します

6. 失敗を報告します:

   • 失敗した実行の executedTestCaseUuid を指定して wopee_create_github_issue を使い、リポジトリにイシューを作成します

利用可能なプロンプト

fetch-project-summary

分析スイートとそのユーザーストーリー／テストケースを取得し、スイートの概要と詳細なテストケースの内訳という 2 つの Markdown テーブルで、整形された要約を表示します。

fetch-test-results

分析スイートと実行済みテストケースの結果を取得し、各テストケースの実行ステータス、エージェントレポートのステータス、コードレポートのステータスを示す整形された Markdown テーブルを表示します。失敗したレポートの詳細も表示します。

注記

• ほとんどのツールには suiteUuid が必要です。必ずスイートを取得するか、作成してから開始してください。
• wopee_dispatch_analysis ツールは、アプリケーションのクロールから各ファイル（アーティファクト）の生成まで、処理のサイクル全体を順番に実行します。
• 生成されたデータやエージェント実行の結果を視覚的に確認するには、cmd.wopee.io の利用をおすすめします。