bitbucket-automation

Rube MCP による Bitbucket の自動化

Composio の Bitbucket ツールキットを通じて、リポジトリの管理、プルリクエストのワークフロー、ブランチ操作、課題の追跡、ワークスペースの管理など、Bitbucket の操作を自動化します。

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

前提条件

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

セットアップ

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

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

主なワークフロー

1. プルリクエストを管理する

使用する場面：プルリクエストの作成、レビュー、または確認を行う場合

ツールの呼び出し順序：

1. BITBUCKET_LIST_WORKSPACES - アクセス可能なワークスペースを見つけます［前提条件］
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - 対象のリポジトリを見つけます［前提条件］
3. BITBUCKET_LIST_BRANCHES - ソースブランチと宛先ブランチが存在することを確認します［前提条件］
4. BITBUCKET_CREATE_PULL_REQUEST - タイトル、ソースブランチ、任意のレビュアーを指定して新しい PR を作成します［必須］
5. BITBUCKET_LIST_PULL_REQUESTS - 状態（OPEN、MERGED、DECLINED）で絞り込んで PR を一覧表示します［任意］
6. BITBUCKET_GET_PULL_REQUEST - ID を指定して特定の PR の詳細を取得します［任意］
7. BITBUCKET_GET_PULL_REQUEST_DIFF - コードレビュー用の統合差分を取得します［任意］
8. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 追加・削除された行数と変更ファイルを取得します［任意］

主なパラメーター：

• workspace：ワークスペースのスラッグまたは UUID（すべての操作で必須）
• repo_slug：URL で使用できる形式のリポジトリ名
• source_branch：マージする変更を含むブランチ
• destination_branch：対象ブランチ（省略した場合はリポジトリのメインブランチが既定値になります）
• reviewers：レビュアーの割り当てに使用する、uuid フィールドを持つオブジェクトのリスト
• state：LIST_PULL_REQUESTS の絞り込み条件。OPEN、MERGED、または DECLINED
• max_chars：大きな差分を扱うための GET_PULL_REQUEST_DIFF の文字数上限

注意点：

• reviewers にはユーザー名ではなく、uuid キーを持つオブジェクトの配列を指定します：[{"uuid": "{...}"}]
• UUID の形式には波括弧を含める必要があります：{123e4567-e89b-12d3-a456-426614174000}
• destination_branch を省略すると、リポジトリのメインブランチが既定値になります。main とは限りません
• GET/DIFF 操作で使用する pull_request_id は整数ですが、PR の一覧表示結果の一部として取得できます
• 大きな差分はコンテキストを圧迫する可能性があるため、GET_PULL_REQUEST_DIFF では必ず max_chars（例：50000）を設定してください

2. リポジトリとワークスペースを管理する

使用する場合：リポジトリの一覧表示、作成、削除、またはワークスペースの確認を行う場合

ツールの順序：

1. BITBUCKET_LIST_WORKSPACES - アクセス可能なすべてのワークスペースを一覧表示します［必須］
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - オプションの BBQL フィルターを使ってリポジトリを一覧表示します［必須］
3. BITBUCKET_CREATE_REPOSITORY - 言語、プライバシー、プロジェクトの設定を指定して新しいリポジトリを作成します［任意］
4. BITBUCKET_DELETE_REPOSITORY - リポジトリを完全に削除します（取り消し不可）［任意］
5. BITBUCKET_LIST_WORKSPACE_MEMBERS - レビュアーの割り当てやアクセス確認のためにメンバーを一覧表示します［任意］

主なパラメーター：

• workspace：ワークスペースのスラッグ（LIST_WORKSPACES で確認）
• repo_slug：作成／削除に使用する URL 対応の名前
• q：BBQL クエリフィルター（例：name~"api"、project.key="PROJ"、is_private=true）
• role：ユーザーのロールでリポジトリをフィルターします：member、contributor、admin、owner
• sort：ソート対象のフィールド。先頭に - を付けると降順になります（例：-updated_on）
• is_private：リポジトリの公開範囲を指定するブール値（デフォルトは true）
• project_key：Bitbucket のプロジェクトキー。省略すると、ワークスペース内で最も古いプロジェクトが使用されます

注意点：

• BITBUCKET_DELETE_REPOSITORY は取り消し不可で、フォークには影響しません
• BBQL の文字列値は必ず二重引用符で囲む必要があります：name~"my-repo"。name~my-repo ではありません
• repository は有効な BBQL フィールドではありません。代わりに name を使用してください
• デフォルトのページネーションでは結果が 10 件に制限されます。すべて表示するには pagelen を明示的に設定してください
• CREATE_REPOSITORY はデフォルトで非公開に設定されます。公開リポジトリにするには is_private: false を設定してください

3. イシューを管理する

使用する場合：リポジトリのイシューの作成、更新、一覧表示、またはコメントの追加を行う場合

ツールの順序：

1. BITBUCKET_LIST_ISSUES - 状態、優先度、種別、担当者のオプションフィルターを使ってイシューを一覧表示します［必須］
2. BITBUCKET_CREATE_ISSUE - タイトル、内容、優先度、種別を指定して新しいイシューを作成します［必須］
3. BITBUCKET_UPDATE_ISSUE - イシューの属性（状態、優先度、担当者など）を変更します［任意］
4. BITBUCKET_CREATE_ISSUE_COMMENT - 既存のイシューに Markdown コメントを追加します［任意］
5. BITBUCKET_DELETE_ISSUE - イシューを完全に削除します［任意］

主なパラメーター：

• issue_id：イシューの文字列識別子
• title、content：作成時に必須です
• kind：bug、enhancement、proposal、または task
• priority：trivial、minor、major、critical、または blocker
• state：new、open、resolved、on hold、invalid、duplicate、wontfix、closed
• assignee：CREATE では Bitbucket のユーザー名、UPDATE では assignee_account_id（UUID）
• due_on：ISO 8601 形式の日付文字列

注意点：

• API 呼び出しを成功させるには、リポジトリでイシュートラッカーが有効になっている必要があります（has_issues: true）
• CREATE_ISSUE では assignee（ユーザー名の文字列）を使用しますが、UPDATE_ISSUE では assignee_account_id（UUID）を使用します。これらは別のフィールドです
• DELETE_ISSUE は完全削除で、元に戻せません
• state の値にはスペースが含まれます："on hold" を使用し、"on_hold" は使用しないでください
• LIST_ISSUES で assignee によるフィルタリングを行う場合、ユーザー名ではなくアカウント ID を使用します。担当者未割り当ての場合は文字列 "null" を使用してください

4. ブランチを管理する

使用するタイミング：ユーザーがブランチを作成したい場合、またはブランチ構造を調べたい場合

ツールの順序：

1. BITBUCKET_LIST_BRANCHES - オプションの BBQL フィルターと並べ替えを指定してブランチを一覧表示します［必須］
2. BITBUCKET_CREATE_BRANCH - 特定のコミットハッシュから新しいブランチを作成します［必須］

主なパラメーター：

• name：refs/heads/ プレフィックスなしのブランチ名（例：feature/new-login）
• target_hash：ブランチの作成元となる完全な SHA1 コミットハッシュ（リポジトリに存在する必要があります）
• q：BBQL フィルター（例：name~"feature/"、name="main"）
• sort：name または -target.date（コミット日時の降順）で並べ替えます
• pagelen：ページあたりの結果数（1～100、デフォルトは 10）

注意点：

• CREATE_BRANCH の target_hash には、ブランチ名ではなく完全なコミットハッシュが必要です
• ブランチ名に refs/heads/ プレフィックスを含めないでください
• ブランチ名は Bitbucket の命名規則（英数字、/、.、_、-）に従う必要があります
• BBQL の文字列値は二重引用符で囲む必要があります：name~"feature/" のように指定し、name~feature/ とはしません

5. コメント付きでプルリクエストをレビューする

使用するタイミング：ユーザーが、インラインコードコメントを含むプルリクエストへのレビューコメントを追加したい場合

ツールの順序：

1. BITBUCKET_GET_PULL_REQUEST - PR の詳細を取得し、存在を確認します［前提条件］
2. BITBUCKET_GET_PULL_REQUEST_DIFF - 実際のコード変更をレビューします［前提条件］
3. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 変更されたファイルの一覧を取得します［任意］
4. BITBUCKET_CREATE_PULL_REQUEST_COMMENT - レビューコメントを投稿します［必須］

主なパラメーター：

• pull_request_id：PR の文字列 ID
• content_raw：Markdown 形式のコメントテキスト
• content_markup：デフォルトは markdown。plaintext もサポートされています
• inline：インラインコードコメント用の path、from、to を含むオブジェクト
• parent_comment_id：既存のコメントへのスレッド返信に使用する整数 ID

注意点：

• pull_request_id は、CREATE_PULL_REQUEST_COMMENT では文字列ですが、GET_PULL_REQUEST では整数です
• インラインコメントには、少なくとも inline.path が必要です。from／to は任意の行番号です
• parent_comment_id を指定するとスレッド返信になり、トップレベルのコメントでは省略します
• インラインコメントの行番号は、ソースファイルではなく diff を参照します

共通パターン

ID の解決

操作の前に、人が読める名前を必ず ID に解決します：

• ワークスペース：BITBUCKET_LIST_WORKSPACES でワークスペースのスラッグを取得します
• リポジトリ：q フィルターを指定して BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE を使用し、リポジトリのスラッグを検索します
• ブランチ：PR 作成前に BITBUCKET_LIST_BRANCHES でブランチの存在を確認します
• メンバー：BITBUCKET_LIST_WORKSPACE_MEMBERS でレビュアーの割り当てに必要な UUID を取得します

ページネーション

Bitbucket はカーソルベースではなく、ページベースのページネーションを使用します：

• page（1 から開始）と pagelen（ページあたりの項目数）パラメーターを使用します
• デフォルトのページサイズは通常 10 です。pagelen を明示的に設定してください（PR は最大 50、それ以外は最大 100）
• さらにページがあるかどうかを確認するには、レスポンスの next URL または合計件数を確認します
• 結果をすべて取得するため、必ず全ページを順に処理してください

BBQL フィルタリング

リスト取得エンドポイントでは、Bitbucket Query Language を使用できます：

• 文字列値は必ず二重引用符で囲みます：name~"pattern"
• 演算子：=（完全一致）、~（部分一致）、!=（不一致）、>、>=、<、<=
• AND／OR と組み合わせます：name~"api" AND is_private=true

既知の注意点

ID の形式

• ワークスペース：スラッグ文字列（例：my-workspace）または波括弧で囲んだ UUID（{uuid}）
• レビュアーの UUID は波括弧で囲む必要があります：{123e4567-e89b-12d3-a456-426614174000}
• Issue ID は文字列です。PR ID はツールによって整数の場合と文字列の場合があります
• コミットハッシュは完全な SHA1（40 文字）である必要があります

パラメーターに関する注意点

• assignee と assignee_account_id：CREATE_ISSUE はユーザー名を使用し、UPDATE_ISSUE は UUID を使用します
• Issue の state 値にはスペースを含めます："on_hold" ではなく "on hold" です
• destination_branch を省略すると、文字どおりの main ではなく、リポジトリのメインブランチがデフォルトになります
• BBQL では repository は有効なフィールドではありません。代わりに name を使用してください

レート制限

• Bitbucket Cloud API にはレート制限があるため、大規模な一括操作では遅延を挟んでください
• ページネーションを使用したリクエストもレート制限の対象となるため、不要なページ取得は最小限にしてください

破壊的な操作

• BITBUCKET_DELETE_REPOSITORY は取り消せず、フォークも削除しません
• BITBUCKET_DELETE_ISSUE は完全に削除され、復元する方法はありません
• 削除操作を実行する前に、必ずユーザーに確認してください

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
ワークスペースを一覧表示	BITBUCKET_LIST_WORKSPACES	q, sort
リポジトリを一覧表示	BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE	workspace, q, role
リポジトリを作成	BITBUCKET_CREATE_REPOSITORY	workspace, repo_slug, is_private
リポジトリを削除	BITBUCKET_DELETE_REPOSITORY	workspace, repo_slug
ブランチを一覧表示	BITBUCKET_LIST_BRANCHES	workspace, repo_slug, q
ブランチを作成	BITBUCKET_CREATE_BRANCH	workspace, repo_slug, name, target_hash
PR を一覧表示	BITBUCKET_LIST_PULL_REQUESTS	workspace, repo_slug, state
PR を作成	BITBUCKET_CREATE_PULL_REQUEST	workspace, repo_slug, title, source_branch
PR の詳細を取得	BITBUCKET_GET_PULL_REQUEST	workspace, repo_slug, pull_request_id
PR の差分を取得	BITBUCKET_GET_PULL_REQUEST_DIFF	workspace, repo_slug, pull_request_id, max_chars
PR の差分統計を取得	BITBUCKET_GET_PULL_REQUEST_DIFFSTAT	workspace, repo_slug, pull_request_id
PR にコメント	BITBUCKET_CREATE_PULL_REQUEST_COMMENT	workspace, repo_slug, pull_request_id, content_raw
課題を一覧表示	BITBUCKET_LIST_ISSUES	workspace, repo_slug, state, priority
課題を作成	BITBUCKET_CREATE_ISSUE	workspace, repo_slug, title, content
課題を更新	BITBUCKET_UPDATE_ISSUE	workspace, repo_slug, issue_id
課題にコメント	BITBUCKET_CREATE_ISSUE_COMMENT	workspace, repo_slug, issue_id, content
課題を削除	BITBUCKET_DELETE_ISSUE	workspace, repo_slug, issue_id
メンバーを一覧表示	BITBUCKET_LIST_WORKSPACE_MEMBERS	workspace

---

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