Lucius MCP

Allure TestOps MCP サーバー

Lucius は、FastMCP と Starlette で構築された、Allure TestOps 専用の Model Context Protocol（MCP）サーバーです。

🎯 動機

Allure TestOps は、膨大な API を備えた強力なツールです。AI エージェントを使ってテストを管理する場合、詳細に迷ったり、ちょっとした技術的なミスで失敗したりすることがあります。

Lucius は、シンプルに使えて壊れにくいツールを AI に提供することで、この作業を簡単にします。

• わかりやすいツール：「テストケースの検索」や「起動の更新」など、各ツールは特定のタスク向けに設計されています。
• 役立つエラー：AI が間違えた場合、Lucius はコードを返すだけでなく、何が問題だったのか、どう修正すればよいのかを正確に説明する「エージェント向けヒント」も提供します。
• 堅牢な基盤：明快な「Thin Tool」構造に従っているため、ロジックに一貫性があり、人間にも AI にも理解しやすくなっています。

🛠️ 対応ツール

詳細はツールリファレンスを参照してください。

ツールカテゴリ	説明	すべてのツール
テストケース管理	テストドキュメントのライフサイクル全体を管理します。	create_test_case、update_test_case、delete_test_case、delete_archived_test_cases、get_test_case_details、get_test_case_custom_fields
自動化コード生成	既存のテストケースからフレームワーク固有のコードを生成します。	generate_test_code
検索と探索	高度な検索とプロジェクトメタデータの探索を行います。	list_test_cases、search_test_cases、get_custom_fields、list_integrations、get_project
共有ステップ	再利用可能なステップのシーケンスを作成、管理します。	create_shared_step、list_shared_steps、update_shared_step、delete_shared_step、delete_archived_shared_steps、link_shared_step、unlink_shared_step
テストレイヤー	テストの分類体系と自動マッピング用スキーマを管理します。	list_test_layers、create_test_layer、update_test_layer、delete_test_layer、list_test_layer_schemas、create_test_layer_schema、update_test_layer_schema、delete_test_layer_schema
テスト階層	ツリー形式のパスでスイートを整理し、テストを割り当てます。	create_test_suite、list_test_suites、assign_test_cases_to_suite、delete_test_suite
カスタムフィールド	プロジェクトレベルでカスタムフィールドの値を管理します。	list_custom_field_values、create_custom_field_value、update_custom_field_value、delete_custom_field_value、delete_unused_custom_fields
ローンチ管理	ローンチ、結果のアップロード、手動実行、再実行、添付ファイルを管理します。	create_launch、list_launches、get_launch、list_launch_test_results、upload_test_results、attach_file_to_launch、rerun_test_results_manually、start_manual_test_session、submit_manual_test_results、add_test_result_attachment
テスト結果管理	TestOps の個別の結果を確認し、検証済みの証跡をダウンロードできるように準備します。	get_test_result、prepare_attachment_download
テスト計画	テスト計画とその内容を管理します。	create_test_plan、update_test_plan、delete_test_plan、list_test_plans、manage_test_plan_content、run_test_plan
不具合管理	不具合、関連付け、自動化ルールを追跡します。	create_defect、get_defect、update_defect、delete_defect、list_defects、link_defect_to_test_case、unlink_issue_from_test_case、list_defect_test_cases、create_defect_matcher、list_defect_matchers、update_defect_matcher、delete_defect_matcher

🚀 クイックスタート

1. uv をインストール：curl -LsSf https://astral.sh/uv/install.sh | sh
2. 認証情報を設定：以下の変数を含む .env ファイルを作成するか、lucius auth で CLI 認証を保存します。
3. サーバーを起動：uv run start

クイックスタート用の基本的な .env

変数	説明	例
ALLURE_ENDPOINT	Allure TestOps のベース URL	https://example.testops.cloud
ALLURE_PROJECT_ID	デフォルトの Allure プロジェクト ID（get_project では任意、プロジェクトスコープのツールでは必須）	123
ALLURE_API_TOKEN	Allure API トークン	<your_api_token>
MCP_MODE	Lucius ランタイムの MCP トランスポートモード	stdio

🔌 Claude Desktop との連携

Claude Desktop で Lucius を使用する最も簡単な方法は、.mcpb バンドルを利用することです。

1. Releases から最新の lucius-mcp.mcpb をダウンロードします。
2. Claude Desktop で開きます。
3. UI で Allure の認証情報を設定します。

💻 Claude Code との連携

Claude Code に Lucius を追加するには、プロジェクトディレクトリ内で次のコマンドを実行します。

claude mcp add --transport stdio --scope project \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  testops-mcp -- uvx --from lucius-mcp --refresh start

プロジェクトスコープのテキスト設定例（.mcp.json）：

{
  "mcpServers": {
    "testops-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "lucius-mcp",
        "--refresh",
        "start"
      ],
      "env": {
        "ALLURE_ENDPOINT": "https://example.testops.cloud",
        "ALLURE_PROJECT_ID": "123",
        "ALLURE_API_TOKEN": "<your_api_token>",
        "MCP_MODE": "stdio"
      }
    }
  }
}

🧠 Codex との連携

Codex（CLI または IDE 拡張機能）に Lucius を追加するには、次を使用します。

codex mcp add testops-mcp \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  -- uvx --from lucius-mcp --refresh start

テキスト設定例（~/.codex/config.toml またはプロジェクトの .codex/config.toml）：

[mcp_servers.testops-mcp]
command = "uvx"
args = ["--from", "lucius-mcp", "--refresh", "start"]

[mcp_servers.testops-mcp.env]
ALLURE_ENDPOINT = "https://example.testops.cloud"
ALLURE_PROJECT_ID = "123"
ALLURE_API_TOKEN = "<your_api_token>"
MCP_MODE = "stdio"

Claude Desktop（MCPB）との連携を含む詳細な設定については、セットアップガイドを参照してください。

🐍 対応する Python バージョン

Lucius はランタイムで Python 3.10 から 3.14 までをサポートしています。生成される MCPB マニフェストと代表的な Nuitka CLI コンパイラーのマトリックスでも、同じ範囲が検証されます。Python 3.15 のサポートは実験的です。インストール時にソースからのビルドが必要になる場合があり、プラットフォームとの互換性も引き続き検証中です。現在の制限事項については、開発ガイドを参照してください。固定された Starlette の要件で Python 3.10 以降が必要なため、Python 3.9 は引き続きサポートされません。

💻 コマンドラインインターフェース（CLI）

Lucius では、コマンドラインからツールを直接実行するための汎用 CLI エントリーポイントも利用できます。

# List available actions for an entity
uv run lucius test_case

# Execute an action
uv run lucius test_case get --args '{"test_case_id": 1234}'

# Show help for a specific entity/action
uv run lucius test_case get --help

# Save reusable CLI auth
uv run lucius auth --url https://example.testops.cloud --token <your_api_token> --project 123
uv run lucius auth status
uv run lucius auth clear

CLI の機能：

• 🎯 検証機能付きの型安全なエンティティ／アクション呼び出し
• 🔐 ユーザーごとのネイティブな設定ストレージを使った、任意の永続 CLI 認証
• 📊 複数の出力形式（JSON、table、csv、plain）
• 🔍 パラメーターと例を含む、アクションごとのヘルプ
• 🛡️ ガイダンス付きの明確なエラーメッセージ
• 📦 Linux、macOS、Windows 用のスタンドアロンバイナリ

CLI 認証の優先順位は次のとおりです。

1. api_token や project_id などの明示的なツール引数
2. 環境変数
3. uv run lucius auth で保存した CLI 認証設定
4. デフォルト値

保存された CLI 認証では、OS ごとのネイティブな設定場所が使用されます。

• Linux/Unix：$XDG_CONFIG_HOME/lucius/auth.json または ~/.config/lucius/auth.json
• macOS：XDG が明示的に設定されていない場合は ~/Library/Application Support/lucius/auth.json
• Windows：%LOCALAPPDATA%\lucius\auth.json

CLI の全ドキュメントとインストール手順については、CLI ガイドを参照してください。

📡 テレメトリー

Lucius はツールの品質向上のため、プライバシーを保護した利用状況のテレメトリーを収集します。テレメトリーはデフォルトで有効になっており、プロジェクトの所有者が運営するエンドポイント https://stats.ostanin.me にメタデータを送信します（このエンドポイントにアクセスできる第三者はいません）。

お使いの環境で問題がなければ、オプトイン状態を維持することで Lucius の継続的な改善に役立ちます。オプトアウトする場合は、環境に TELEMETRY_ENABLED=false を設定してください。

API トークン、テスト内容、ツール引数は送信されません。

データ辞書とテレメトリーの動作に関する詳細は、テレメトリーとプライバシーを参照してください。

📂 ドキュメント

ドキュメント一式は docs/ フォルダーにあります。

• アーキテクチャと設計
• ツールリファレンス
• 設定とセットアップ
• テレメトリーとプライバシー
• 添付ファイルのダウンロード機能のリンク
• 開発ガイド
• AI エージェントプロトコル

🤝 Contributing

Contributions are welcome! Please see the Contribution Guidelines and the Development Guide for more details.