allure-testops-mcp

allure-testops-mcp

Allure TestOps 用の MCP サーバーです。LLM エージェント（Claude Code、Cursor、OpenCode など）から Allure REST API を通じて、プロジェクト、起動、テストケース、テスト結果、参照データを調査・管理できます。

• 技術スタック： Python 3.10 以降、FastMCP、stdio トランスポート。
• 互換性： SaaS の qameta.io、セルフホスト／オンプレミス（/api/rs の API）を問わず、あらゆる Allure TestOps インスタンスに対応します。
• インスタンス全体 — すべてのプロジェクトを一度に： 1 つの接続でインスタンス上のすべてのプロジェクトを利用できます。サーバーは単一のプロジェクトに固定されません。allure_list_projects でプロジェクトを確認し、任意の project_id を渡してください。プロジェクトの切り替えや比較に再設定は不要です。
• 企業での利用に適しています： API トークン認証、任意の SSL 検証切り替え、意図的なプロキシのバイパスに対応します。
• デフォルトで安全： 読み取り専用ツールは 13 個です。書き込みツール 7 個は、明示的に有効化しない限り無効です。

クイックスタート

claude mcp add allure -s user \
  --env ALLURE_URL=https://allure.example.com \
  --env ALLURE_TOKEN=your-api-token \
  -- uvx --from allure-testops-mcp allure-testops-mcp

続いて、エージェントに「Allure の全プロジェクトを一覧表示して」や「プロジェクト 175 の直近の起動で失敗したテストを表示して」と依頼します。 Allure TestOps の Profile → API tokens で API トークンを取得してください。他のクライアントについては設定、すべてのオプションについては環境変数を参照してください。

ツール一覧

ツールは 20 個あり、読み取り専用が 13 個（常に有効）、書き込みツールが 7 個（ALLURE_ENABLE_WRITE=true で有効化）です。すべてのツールに MCP アノテーションが付与されており、型付きの structuredContent ペイロードと Markdown の概要の両方を返します。

ツール	種類	用途
allure_list_projects	読み取り	すべてのプロジェクト（id、名前、略称）
allure_get_project_statistics	読み取り	TC 数、自動化率、直近の起動の概要
allure_list_launches	読み取り	最近の起動と成功／失敗の統計
allure_get_test_results	読み取り	起動内のテスト結果（ステータスで絞り込み）
allure_search_failed_tests	読み取り	直近または指定した起動内の FAILED／BROKEN テスト
allure_list_test_cases	読み取り	テストケース（自動／手動、オーナーで絞り込み）
allure_get_test_case	読み取り	1 件のテストケースの詳細とシナリオステップ
allure_get_test_case_custom_fields	読み取り	テストケースのカスタムフィールド値
allure_list_statuses	読み取り	プロジェクトのステータス（id、名前、色）
allure_list_layers	読み取り	プロジェクトのテストレイヤー（id、名前）
allure_list_custom_fields	読み取り	プロジェクトのカスタムフィールドスキーマ
allure_list_categories	読み取り	不具合カテゴリ（名前付き／色付きの分類）
allure_list_category_matchers	読み取り	正規表現の自動化ルール（メッセージ／トレース → カテゴリ）
allure_create_test_case	write ⚑	テストケースを作成
allure_update_test_case	write ⚑	テストケースを部分更新
allure_delete_test_case	write ⚑	完全に削除（破壊的操作 — confirm=true が必要）
allure_create_category	write ⚑	不具合カテゴリを作成
allure_delete_category	write ⚑	完全に削除（破壊的操作 — confirm=true が必要）
allure_create_category_matcher	write ⚑	正規表現の自動化ルールを作成して関連付け
allure_delete_category_matcher	write ⚑	完全に削除（破壊的操作 — confirm=true が必要）

⚑ ALLURE_ENABLE_WRITE=true の場合にのみ登録されます。このフラグがない場合、ツールはインポートされないため、エージェントに表示されません。セキュリティに関する考慮事項を参照してください。

書き込みツール — 名前または ID によるステータスとレイヤー

allure_create_test_case ／ allure_update_test_case では、ステータスとレイヤーを名前 （status ／ layer）または数値の ID（status_id ／ layer_id）で指定できます。名前はプロジェクトのステータス／レイヤー一覧（GET /api/rs/status、GET /api/rs/testlayer）を参照して自動的に ID に解決されます。名前が見つからない場合は、有効な選択肢を示す、次の操作につながるエラーが返されます。更新は部分更新です（渡したフィールドのみ変更されます）。また、allure_delete_test_case は元に戻せません。destructiveHint: True が設定され（準拠クライアントは確認を促します）、さらに明示的な confirm=true 引数が必要です。

設計上の特長

• すべてのツールにアノテーション — 読み取りツールには readOnlyHint: True ／ openWorldHint: True が設定されるため、クライアントは確認を促しません。allure_delete_test_case には destructiveHint: True が設定されます。
• すべてのツールで構造化出力 — 各ツールは TypedDict の戻り値型を宣言するため、FastMCP が outputSchema を自動生成し、すべての結果に structuredContent と Markdown ブロックの両方が含まれます。
• 次の操作につながるエラー — 認証／400／403／404／409／429／5xx／環境変数不足のエラーを、次に行うべき操作を示す具体的なメッセージに変換します（例：「認証に失敗しました — ALLURE_TOKEN に API スコープがあることを確認してください」）。
• Pydantic による入力検証 — すべての引数に型付き制約（範囲、長さ、リテラル）があり、JSON Schema として公開されます。RQL インジェクションを防ぐため、ユーザー名はアルファベットに制限されています。
• ページネーション — リストツールは page、total、has_more、next_page を含む pagination ブロックを返します。
• 進捗の報告 — 複数の呼び出しを行うツールは、ctx.report_progress と ctx.info のイベントを送信します。
• バージョンに依存しない更新動詞 — allure_update_test_case は PATCH を実行し、HTTP 405 の場合は PUT にフォールバックするため、どちらか一方の動詞のみを公開する Allure デプロイでも動作します。
• バージョン情報の単一の信頼できる情報源 — __version__ はインストール済みパッケージのメタデータから取得されます。また、pyproject.toml が server.json の両方のバージョンフィールドと一致することをテストで検証するため、公開バージョンに食い違いが生じません。

インストール

Python 3.10 以降が必要です。uvx（推奨）を使う場合は手動インストールは不要です。MCP クライアントが実行します。

# run on demand via uvx (recommended)
uvx --from allure-testops-mcp allure-testops-mcp

# or install with pipx
pipx install allure-testops-mcp

設定

Claude Code — 次のコマンドを 1 つ実行します。

claude mcp add allure -s user \
  --env ALLURE_URL=https://allure.example.com \
  --env ALLURE_TOKEN=your-api-token \
  --env ALLURE_SSL_VERIFY=true \
  -- uvx --from allure-testops-mcp allure-testops-mcp

任意の MCP クライアント — ~/.claude.json、プロジェクトの .mcp.json、Cursor の mcp.json などに追加します。

{
  "mcpServers": {
    "allure": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "allure-testops-mcp", "allure-testops-mcp"],
      "env": {
        "ALLURE_URL": "https://allure.example.com",
        "ALLURE_TOKEN": "${ALLURE_TOKEN}",
        "ALLURE_SSL_VERIFY": "true"
      }
    }
  }
}

テンプレートについては .env.example を参照してください。接続を確認します。

claude mcp list
# allure: uvx --from allure-testops-mcp allure-testops-mcp - ✓ Connected

環境変数

変数	必須	デフォルト	説明
ALLURE_URL	はい	—	Allure TestOps の URL（例：https://allure.example.com）
ALLURE_TOKEN	はい	—	API トークン（Allure → Profile → API tokens）
ALLURE_SSL_VERIFY	いいえ	true	true／false。自己署名の社内証明書を使用する場合は false に設定します
ALLURE_ENABLE_WRITE	いいえ	false	true にすると、書き込みツール 7 個が登録されます。デフォルトでは読み取り専用サーバーです

ALLURE_TEST_PROJECT_ID（および任意の ALLURE_TEST_STATUS ／ ALLURE_TEST_LAYER）は、オプトイン方式のライブ統合テストでのみ使用されます。開発を参照してください。

更新

このサーバーは stdio プロセスで、クライアントがセッションごとに再起動します。そのため、実行中のバージョンは uvx の呼び出しによって決まります。uvx は解決した環境を ~/.cache/uv にキャッシュするため、更新するまで古いバージョンが使われ続けます。

uvx --refresh --from allure-testops-mcp allure-testops-mcp   # force latest on next run
uv cache clean allure-testops-mcp                            # or drop the cached env

その後、サーバーに再接続します（/mcp → 再接続、またはセッションを再起動）。設定からバージョンを制御するには、args を編集します。安定性を重視する場合はバージョンを固定し、常に最新を使う場合は最新バージョンにします。

// Pin a version (deterministic; bump consciously)
"args": ["--from", "allure-testops-mcp==0.8.0", "allure-testops-mcp"]

// Always latest on every start (adds a PyPI lookup per launch)
"args": ["--refresh", "--from", "allure-testops-mcp", "allure-testops-mcp"]

プロンプトの例

読み取り専用：

• 「Allure のプロジェクトをすべて一覧表示して」
• 「プロジェクト 63 の直近 10 件のローンチを表示して」
• 「プロジェクト 175 の直近のローンチで失敗したテスト」
• 「プロジェクト 842 の自動化率は？」
• 「プロジェクト 63 とプロジェクト 842 の自動化率を比較して」— 1 つのセッションでプロジェクトをまたいで動作します
• 「テストケース 641012 のステップを表示して」
• 「プロジェクト 1664 にはどのカスタムフィールドがありますか？」

ALLURE_ENABLE_WRITE=true の場合、自然言語でテストケースの CRUD 操作を実行できます：

• 「プロジェクト 63 に『Login flow』という名前の Draft の手動 TC を作成して」
• 「プロジェクト 63 に smoke タグ、E2E レイヤーの自動化スモーク TC を追加して」
• 「テストケース 555 の名前を『Login (rewritten)』に変更して、ステータスを Active に設定して」
• 「テストケース 555 を削除して」— エージェントは confirm=true を渡し、準拠しているクライアントは最初に確認を求めます

セキュリティに関する考慮事項

• API トークンは ALLURE_TOKEN からのみ読み取られます — コマンドラインに渡されず、ログにも書き込まれません。
• シークレットがツールの応答に含まれることはありません（ヘッダーのダンプや認証情報の反映はありません）。
• 自己署名 SSL は明示的に有効化する必要があります（ALLURE_SSL_VERIFY=false。デフォルトは true）。公開ネットワークで検証を無効にするのはリスクがあるため、信頼できる社内インスタンスでのみ使用してください。
• プロキシの検出は無効です（session.trust_env = False）— サーバーは HTTP_PROXY / HTTPS_PROXY を無視するため、意図しないプロキシ経由で密かにルーティングされることはありません。
• 書き込みはオプトイン方式で、最小権限に基づきます — ALLURE_ENABLE_WRITE=true が設定されていない場合、サーバーは読み取り専用の 13 個のツールのみを登録し、書き込み権限付きトークンを使っても、何も作成、変更、削除できません。有効にすると、破壊的なツール（allure_delete_test_case / allure_delete_category / allure_delete_category_matcher）には destructiveHint: True が設定され、confirm=true が必須になります。
• Pydantic による入力検証 — すべての引数は型と範囲が指定されており、検索エンドポイント経由の RQL インジェクションを防ぐため、ユーザー名には使用可能な文字を制限しています。
• トークンの権限がアカウントの権限を超えることはありません — Allure の Api-Token 認証は発行したユーザーのロールを引き継ぐため、ALLURE_ENABLE_WRITE フラグの設定にかかわらず、読み取り専用（ゲスト）アカウントではサーバーも読み取り専用になります。

レート制限

Allure TestOps はインスタンスごとにレート制限を適用します（通常、トークンあたり約 60 リクエスト／分）。HTTP 429 が返された場合、サーバーは 30～60 秒待つ、size を減らす、またはページを小さくしてページネーションを行うことを提案する、実行可能なエラーメッセージを返します。2 つのツールは内部で複数の API 呼び出しを行います — allure_get_project_statistics（3 回）と allure_search_failed_tests（2～3 回） — また、MCP の Context を通じてステップごとの進捗を報告します。

開発

git clone https://github.com/mshegolev/allure-testops-mcp.git
cd allure-testops-mcp
pip install -e '.[dev]'
pytest          # unit suite (all HTTP mocked)
ruff check src tests && ruff format --check src tests

サーバーを直接実行します（stdio トランスポート — MCP メッセージを stdin から受信するまで待機します）：

ALLURE_URL=... ALLURE_TOKEN=... allure-testops-mcp

ライブインスタンスでの統合テスト

オプトイン方式のテストスイートは、ライブ Allure プロジェクトに対して実際の作成 → 更新 → 削除のライフサイクルを実行します。デフォルトでは選択解除されており、認証情報がない場合は自動的にスキップされるため、通常の pytest は成功します：

export ALLURE_URL=https://allure.example.com
export ALLURE_TOKEN=...                 # token from an account with write access
export ALLURE_ENABLE_WRITE=true
export ALLURE_TEST_PROJECT_ID=63        # a throwaway project you can write to
pytest -m integration tests/integration -v

コントリビュート

Issue と PR を歓迎します。ユニットテストスイートが成功する状態（pytest）を保ち、リンターの警告がない状態（ruff check、ruff format）を維持してください。CI では Python 3.10 / 3.11 / 3.12 で両方を実行します。リリース履歴については CHANGELOG.md を参照してください。

ライセンス

MIT © Mikhail Shchegolev