confluence-automation

Rube MCP 経由の Confluence 自動化

Composio の Confluence ツールキットを通じて、ページの作成と更新、CQL を使ったコンテンツ検索、スペースの管理、ラベルの付与、ページ階層の移動など、Confluence の操作を自動化します。

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

前提条件

• Rube MCP が接続されており（RUBE_SEARCH_TOOLS が利用可能）
• RUBE_MANAGE_CONNECTIONS でツールキット confluence を指定し、有効な Confluence 接続がある
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出す

セットアップ

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

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

主なワークフロー

1. ページの作成と更新

使用する場面：新しいドキュメントを作成する場合、または既存の Confluence ページを更新する場合

ツールの呼び出し順序：

1. CONFLUENCE_GET_SPACES - スペースの一覧を取得し、対象のスペース ID を確認します［前提条件］
2. CONFLUENCE_SEARCH_CONTENT - 重複を避けるため、または親ページを探すために既存のページを検索します［任意］
3. CONFLUENCE_GET_PAGE_BY_ID - 更新前に現在のページの内容とバージョン番号を取得します［更新時の前提条件］
4. CONFLUENCE_CREATE_PAGE - スペースに新しいページを作成します［作成時に必須］
5. CONFLUENCE_UPDATE_PAGE - 新しい内容と増分したバージョンで既存のページを更新します［更新時に必須］
6. CONFLUENCE_ADD_CONTENT_LABEL - 作成後にページへラベルを付けます［任意］

主なパラメーター：

• spaceId：スペース ID またはキー（例："DOCS"、"12345678"）。スペースキーは自動的に ID に変換されます
• title：ページのタイトル（スペース内で一意である必要があります）
• parentId：子ページを作成する場合の親ページ ID。スペースのホームページの下に配置する場合は省略します
• body.storage.value：Confluence のストレージ形式による HTML/XHTML コンテンツ
• body.storage.representation：作成操作では "storage" を指定する必要があります
• version.number：更新時は、現在のバージョンに 1 を加えた値を指定する必要があります
• version.message：変更内容の説明（任意）

注意点：

• Confluence ではスペースごとにページタイトルが一意である必要があります。重複したタイトルでページを作成すると失敗します
• UPDATE_PAGE では version.number に現在のバージョン + 1 を設定する必要があります。更新前に必ず GET_PAGE_BY_ID で現在のバージョンを取得してください
• コンテンツはプレーンテキストや Markdown ではなく、Confluence のストレージ形式（XHTML）で指定する必要があります
• CREATE_PAGE では body.storage.value を使用し、UPDATE_PAGE では body.value と body.representation を使用します
• GET_PAGE_BY_ID には数値の long ID が必要です。UUID や文字列は使用できません

2. コンテンツを検索する

使用する場面：Confluence 全体からページ、ブログ投稿、またはコンテンツを見つけたい場合

ツールの実行順序：

1. CONFLUENCE_SEARCH_CONTENT - インテリジェントな関連度ランキングによるキーワード検索［必須］
2. CONFLUENCE_CQL_SEARCH - Confluence Query Language を使った高度な検索［代替］
3. CONFLUENCE_GET_PAGE_BY_ID - 選択した検索結果の全コンテンツを取得［任意］
4. CONFLUENCE_GET_PAGES - 検索結果の関連度が低い場合に日付順でページを閲覧［フォールバック］

SEARCH_CONTENT の主なパラメーター：

• query：インテリジェントなランキングでページタイトルを照合する検索テキスト
• spaceKey：検索対象を特定のスペースに限定します
• limit：結果の最大数（デフォルトは 25、最大 250）
• start：ページネーションのオフセット（0 始まり）

CQL_SEARCH の主なパラメーター：

• cql：CQL クエリ文字列（例：text ~ "API docs" AND space = DOCS AND type = page）
• expand：カンマ区切りのプロパティ（例：content.space、content.body.storage）
• excerpt：highlight、indexed、または none
• limit：結果の最大数（最大 250。ただし、本文の展開を使用する場合は 25～50 に減少します）

CQL の演算子とフィールド：

• フィールド：text、title、label、space、type、creator、lastModified、created、ancestor
• 演算子：=、!=、~（含む）、!~、>、<、>=、<=、IN、NOT IN
• 関数：currentUser()、now("-7d")、now("-30d")
• 例：title ~ "meeting" AND lastModified > now("-7d") ORDER BY lastModified DESC

注意事項：

• CONFLUENCE_SEARCH_CONTENT は最大 300 件のページを取得し、クライアント側でフィルタリングします。真の全文検索ではありません
• CONFLUENCE_CQL_SEARCH が実際の全文検索です。コンテンツ本文を検索するには text ~ "term" を使用してください
• HTTP 429 のレート制限が発生する場合があります。バックオフを行い、リクエスト頻度を約 2 リクエスト/秒に抑えてください
• CQL_SEARCH で本文の展開を使用すると、結果の最大数が 25～50 に減少する場合があります
• 検索インデックスへの反映は即時ではありません。作成直後のページは検索結果に表示されない場合があります

3. スペースを管理する

使用する場面：Confluence のスペースを一覧表示、作成、または確認したい場合

ツールの実行順序：

1. CONFLUENCE_GET_SPACES - 必要に応じて絞り込みながら、すべてのスペースを一覧表示［必須］
2. CONFLUENCE_GET_SPACE_BY_ID - 特定のスペースの詳細なメタデータを取得［任意］
3. CONFLUENCE_CREATE_SPACE - キーと名前を指定して新しいスペースを作成［任意］
4. CONFLUENCE_GET_SPACE_PROPERTIES - スペースのプロパティとして保存されたカスタムメタデータを取得［任意］
5. CONFLUENCE_GET_SPACE_CONTENTS - スペース内のページ、ブログ投稿、または添付ファイルを一覧表示［任意］
6. CONFLUENCE_GET_LABELS_FOR_SPACE - スペースのラベルを一覧表示［任意］

主なパラメーター：

• key：スペースキー。英数字のみ使用でき、アンダースコアやハイフンは使用できません（例：DOCS、PROJECT1）
• name：人が読みやすいスペース名
• type：global または personal
• status：current（アクティブ）または archived
• spaceKey：GET_SPACE_CONTENTS で使用し、スペースキーで絞り込みます
• id：GET_SPACE_BY_ID 用の数値のスペース ID（スペースキーではありません）

注意事項：

• スペースキーには英数字のみ使用できます（アンダースコア、ハイフン、特殊文字は使用できません）
• GET_SPACE_BY_ID にはスペースキーではなく、数値のスペース ID が必要です。数値 ID を確認するには GET_SPACES を使用してください
• クリック可能なスペース URL を組み立てるには、_links.webui（相対パス）と _links.base を結合する必要がある場合があります
• デフォルトのページネーションは 25 です。limit を明示的に設定してください（スペースの最大値は 200）

4. ページ階層とラベルを操作する

使用する場面：ページツリー、子ページ、祖先ページを確認したい場合、またはラベルを管理したい場合

ツールの手順：

1. CONFLUENCE_SEARCH_CONTENT - 対象ページ ID を検索します［必須］
2. CONFLUENCE_GET_CHILD_PAGES - 親ページの直接の子ページを一覧表示します［必須］
3. CONFLUENCE_GET_PAGE_ANCESTORS - ページの祖先をすべて取得します［任意］
4. CONFLUENCE_GET_LABELS_FOR_PAGE - 特定のページに付いているラベルを一覧表示します［任意］
5. CONFLUENCE_ADD_CONTENT_LABEL - ページにラベルを追加します［任意］
6. CONFLUENCE_GET_LABELS_FOR_SPACE_CONTENT - スペース内のすべてのコンテンツに付いているラベルを一覧表示します［任意］
7. CONFLUENCE_GET_PAGE_VERSIONS - ページの編集履歴を監査します［任意］

主なパラメーター：

• id：子ページ、祖先、ラベル、バージョンを取得するページ ID
• cursor：GET_CHILD_PAGES 用の不透明なページネーションカーソル（_links.next から取得）
• limit：1 ページあたりの項目数（子ページの場合は最大 250）
• sort：子ページの並べ替えオプション：id、-id、created-date、-created-date、modified-date、-modified-date、child-position、-child-position

注意点：

• GET_CHILD_PAGES が返すのは直接の子ページのみで、入れ子になった子孫ページは含まれません。ツリー全体を取得するには再帰的に呼び出してください
• GET_CHILD_PAGES のページネーションにはカーソル方式が使われます（start/limit ではありません）
• 親ページとして使用する前に、検索結果から正しいページ ID を確認してください。検索ではタイトルが似たページが返されることがあります
• GET_PAGE_VERSIONS に必要なのはページ ID であり、バージョン番号ではありません

よくあるパターン

ID の解決

操作の前に、人が読める名前を必ず ID に解決してください：

• スペースキー -> スペース ID：spaceKey フィルターを指定して CONFLUENCE_GET_SPACES を使用するか、CREATE_PAGE にスペースキーを直接指定します
• ページタイトル -> ページ ID：query パラメーターを指定して CONFLUENCE_SEARCH_CONTENT を実行し、ページ ID を抽出します
• URL からスペース ID を取得：Confluence の URL から数値 ID を抽出するか、GET_SPACES を使用します

ページネーション

Confluence では 2 種類のページネーション方式が使われます：

• オフセット方式（ほとんどのエンドポイント）：start（0 始まりのオフセット）と limit（ページサイズ）を使用します。返される結果が limit より少なくなるまで、start を limit ずつ増やします。
• カーソル方式（GET_CHILD_PAGES、GET_PAGES）：レスポンスの _links.next にある cursor を使用します。next リンクがなくなるまで続けます。

コンテンツのフォーマット

• ページでは Markdown ではなく、Confluence のストレージ形式（XHTML）を使用します
• 基本要素：<p>、<h1>-<h6>、<strong>、<em>、<code>、<ul>、<ol>、<li>
• 表：<table><tbody><tr><th> / <td> 構造
• マクロ：コードブロックには <ac:structured-macro ac:name="code"> などを使用します
• コンテンツは必ず適切な XHTML タグで囲んでください

既知の注意点

ID の形式

• スペース ID は数値です（例：557060）。スペースキーは短い文字列です（例：DOCS）
• GET_PAGE_BY_ID 用のページ ID は長い数値です。一部のツールでは UUID 形式も使用できます
• GET_SPACE_BY_ID に必要なのは数値 ID であり、スペースキーではありません
• GET_PAGE_BY_ID が受け取るのは整数であり、文字列ではありません

レート制限

• 検索エンドポイントでは HTTP 429 が発生することがあります。Retry-After ヘッダーに従ってください
• 指数バックオフとジッターを使用し、リクエスト頻度を約 2 リクエスト/秒に抑えてください
• CQL_SEARCH で本文を展開すると、結果の上限は 25～50 件に減少します

コンテンツ形式

• コンテンツには Markdown やプレーンテキストではなく、Confluence のストレージ形式（XHTML）を使用する必要があります
• XHTML が無効だと、ページの作成や更新は失敗します
• CREATE_PAGE では本文を body.storage.value の下に配置します。UPDATE_PAGE では body.value と body.representation を使用します

バージョンの競合

• 更新には、正確な次のバージョン番号（現在のバージョン + 1）が必要です
• 同時編集によってバージョンが競合することがあります。更新の直前に必ず現在のバージョンを取得してください
• 更新時にタイトルを変更する場合も、スペース内で一意である必要があります

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
スペースの一覧表示	CONFLUENCE_GET_SPACES	type、status、limit
ID でスペースを取得	CONFLUENCE_GET_SPACE_BY_ID	id
スペースを作成	CONFLUENCE_CREATE_SPACE	key、name、type
スペースのコンテンツ	CONFLUENCE_GET_SPACE_CONTENTS	spaceKey、type、status
スペースのプロパティ	CONFLUENCE_GET_SPACE_PROPERTIES	id、key
コンテンツを検索	CONFLUENCE_SEARCH_CONTENT	query、spaceKey、limit
CQL 検索	CONFLUENCE_CQL_SEARCH	cql、expand、limit
ページの一覧表示	CONFLUENCE_GET_PAGES	spaceId、sort、limit
ID でページを取得	CONFLUENCE_GET_PAGE_BY_ID	id（整数）
ページを作成	CONFLUENCE_CREATE_PAGE	title、spaceId、body
ページを更新	CONFLUENCE_UPDATE_PAGE	id、title、body、version
ページを削除	CONFLUENCE_DELETE_PAGE	id
子ページ	CONFLUENCE_GET_CHILD_PAGES	id、limit、sort
ページの祖先	CONFLUENCE_GET_PAGE_ANCESTORS	id
ページのラベル	CONFLUENCE_GET_LABELS_FOR_PAGE	id
ラベルを追加	CONFLUENCE_ADD_CONTENT_LABEL	コンテンツ ID、ラベル
ページのバージョン	CONFLUENCE_GET_PAGE_VERSIONS	id
スペースのラベル	CONFLUENCE_GET_LABELS_FOR_SPACE	スペース ID

---

Composio 提供