circleci-automation

Rube MCP による CircleCI の自動化

Rube MCP を介して Composio の CircleCI ツールキットを利用し、CircleCI の CI/CD 操作を自動化します。

ツールキットのドキュメント：composio.dev/toolkits/circleci

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS を利用可能であること）
• ツールキット circleci を使用した、RUBE_MANAGE_CONNECTIONS による有効な CircleCI 接続
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP を取得する：クライアントの設定で https://rube.app/mcp を MCP サーバーとして追加します。API キーは不要です。エンドポイントを追加するだけで動作します。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確かめます
2. ツールキット circleci を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って CircleCI の認証を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

主なワークフロー

1. パイプラインを起動する

使用する状況：ユーザーが新しい CI/CD パイプラインの実行を開始したい場合

ツールの手順：

1. CIRCLECI_TRIGGER_PIPELINE - プロジェクトで新しいパイプラインを起動します［必須］
2. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - 起動されたワークフローを監視します［任意］

主なパラメーター：

• project_slug：gh/org/repo または bb/org/repo 形式のプロジェクト識別子
• branch：パイプラインを実行する Git ブランチ
• tag：パイプラインを実行する Git タグ（branch とは相互排他）
• parameters：パイプラインのパラメーターのキーと値のペア

注意点：

• project_slug の形式は {vcs}/{org}/{repo} です（例：gh/myorg/myrepo）
• branch と tag は相互排他です。両方を指定するとエラーになります
• パイプラインのパラメーターは .circleci/config.yml で定義されたものと一致している必要があります
• 起動するとパイプライン ID が返されます。ワークフローは非同期で開始されます

2. パイプラインとワークフローを監視する

使用する状況：ユーザーがパイプラインまたはワークフローのステータスを確認したい場合

ツールの手順：

1. CIRCLECI_LIST_PIPELINES_FOR_PROJECT - プロジェクトの最近のパイプラインを一覧表示します［必須］
2. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - パイプライン内のワークフローを一覧表示します［必須］
3. CIRCLECI_GET_PIPELINE_CONFIG - 使用されたパイプライン設定を表示します［任意］

主なパラメーター：

• project_slug：{vcs}/{org}/{repo} 形式のプロジェクト識別子
• pipeline_id：特定のパイプラインの UUID
• branch：ブランチ名でパイプラインを絞り込みます
• page_token：次のページの結果を取得するためのページネーションカーソル

注意点：

• パイプライン ID は UUID であり、数値 ID ではありません
• ワークフローはパイプライン ID を引き継ぎます。1 つのパイプラインに複数のワークフローが含まれる場合があります
• ワークフローの状態には、success、running、not_run、failed、error、failing、on_hold、canceled、unauthorized があります
• ページネーションでは、レスポンスに page_token が返されます。存在しなくなるまで処理を続けてください

3. ジョブの詳細を確認する

使用する状況：ユーザーが特定のジョブの実行詳細を詳しく確認したい場合

ツールの手順：

1. CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID - ジョブを含むワークフローを検索します［前提条件］
2. CIRCLECI_GET_JOB_DETAILS - ジョブの詳細情報を取得します［必須］

主なパラメーター：

• project_slug：プロジェクト識別子
• job_number：数値のジョブ番号（UUID ではありません）

注意点：

• ジョブ番号は整数であり、UUID ではありません（パイプライン ID やワークフロー ID とは異なります）
• ジョブの詳細には、エグゼキューターの種類、並列度、開始・終了時刻、ステータスが含まれます
• ジョブのステータス：success、running、not_run、failed、retried、timedout、infrastructure_fail、canceled

4. ビルド成果物を取得する

使用する場面：ジョブによって生成された成果物をダウンロードまたは一覧表示したい場合

ツールの実行順序：

1. CIRCLECI_GET_JOB_DETAILS - ジョブが正常に完了したことを確認します［前提条件］
2. CIRCLECI_GET_JOB_ARTIFACTS - ジョブのすべての成果物を一覧表示します［必須］

主なパラメーター：

• project_slug：プロジェクト識別子
• job_number：数値のジョブ番号

注意点：

• 成果物はジョブの完了後にのみ利用できます
• 各成果物にはダウンロード用の path と url があります
• ダウンロードには、成果物の URL に認証ヘッダーが必要な場合があります
• サイズの大きい成果物にはダウンロードサイズの制限がある場合があります

5. テスト結果を確認する

使用する場面：特定のジョブのテスト結果を確認したい場合

ツールの実行順序：

1. CIRCLECI_GET_JOB_DETAILS - ジョブでテストが実行されたことを確認します［前提条件］
2. CIRCLECI_GET_TEST_METADATA - テスト結果とメタデータを取得します［必須］

主なパラメーター：

• project_slug：プロジェクト識別子
• job_number：数値のジョブ番号

注意点：

• テストメタデータを取得するには、ジョブがテスト結果（JUnit XML 形式）をアップロードしている必要があります
• テスト結果がアップロードされていない場合、レスポンスは空になります
• テストメタデータには、classname、name、result、message、run_time の各フィールドが含まれます
• 失敗したテストでは、message フィールドに失敗メッセージが含まれます

よく使われるパターン

プロジェクトスラッグの形式

Format: {vcs_type}/{org_name}/{repo_name}
- GitHub:    gh/myorg/myrepo
- Bitbucket: bb/myorg/myrepo

パイプライン -> ワークフロー -> ジョブの階層

1. Call CIRCLECI_LIST_PIPELINES_FOR_PROJECT to get pipeline IDs
2. Call CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID with pipeline_id
3. Extract job numbers from workflow details
4. Call CIRCLECI_GET_JOB_DETAILS with job_number

ページネーション

• レスポンスに next_page_token フィールドがあるか確認します
• 次のリクエストでは、トークンを page_token として渡します
• next_page_token が存在しないか、null になるまで続けます

既知の注意点

ID の形式：

• パイプライン ID：UUID（例：5034460f-c7c4-4c43-9457-de07e2029e7b）
• ワークフロー ID：UUID
• ジョブ番号：整数（例：123）
• エンドポイント間で UUID と整数を取り違えないでください

プロジェクトスラッグ：

• VCS プレフィックスを含める必要があります：GitHub の場合は gh/、Bitbucket の場合は bb/
• 組織名とリポジトリ名では大文字と小文字が区別されます
• スラッグの形式が正しくないと 404 エラーが発生します

レート制限：

• CircleCI API にはエンドポイントごとのレート制限があります
• 429 レスポンスに対して指数バックオフを実装してください
• 頻繁なポーリングは避け、適切な間隔（5～10 秒）を使用してください

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
パイプラインをトリガーする	CIRCLECI_TRIGGER_PIPELINE	project_slug, branch, parameters
パイプラインを一覧表示する	CIRCLECI_LIST_PIPELINES_FOR_PROJECT	project_slug, branch
ワークフローを一覧表示する	CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID	pipeline_id
パイプライン設定を取得する	CIRCLECI_GET_PIPELINE_CONFIG	pipeline_id
ジョブの詳細を取得する	CIRCLECI_GET_JOB_DETAILS	project_slug, job_number
ジョブの成果物を取得する	CIRCLECI_GET_JOB_ARTIFACTS	project_slug, job_number
テストメタデータを取得する	CIRCLECI_GET_TEST_METADATA	project_slug, job_number

---

Composio によって提供されています