confluence-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseConfluence Automation via Rube MCP
通过Rube MCP实现Confluence自动化
Automate Confluence operations including page creation and updates, content search with CQL, space management, label tagging, and page hierarchy navigation through Composio's Confluence toolkit.
通过Composio的Confluence工具包,自动化Confluence操作,包括页面创建与更新、基于CQL的内容搜索、空间管理、标签标记及页面层级导航。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Confluence connection via with toolkit
RUBE_MANAGE_CONNECTIONSconfluence - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 必须已连接Rube MCP(需可用RUBE_SEARCH_TOOLS)
- 通过并使用工具包
RUBE_MANAGE_CONNECTIONS建立有效的Confluence连接confluence - 请始终先调用以获取最新的工具架构
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONSconfluence - If connection is not ACTIVE, follow the returned auth link to complete Confluence OAuth
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。
https://rube.app/mcp- 确认可响应,以此验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包
RUBE_MANAGE_CONNECTIONSconfluence - 如果连接状态未显示为ACTIVE,请按照返回的授权链接完成Confluence OAuth认证
- 在运行任何工作流之前,确认连接状态为ACTIVE
Core Workflows
核心工作流
1. Create and Update Pages
1. 创建与更新页面
When to use: User wants to create new documentation or update existing Confluence pages
Tool sequence:
- - List spaces to find the target space ID [Prerequisite]
CONFLUENCE_GET_SPACES - - Find existing page to avoid duplicates or locate parent [Optional]
CONFLUENCE_SEARCH_CONTENT - - Get current page content and version number before updating [Prerequisite for updates]
CONFLUENCE_GET_PAGE_BY_ID - - Create a new page in a space [Required for creation]
CONFLUENCE_CREATE_PAGE - - Update an existing page with new content and incremented version [Required for updates]
CONFLUENCE_UPDATE_PAGE - - Tag the page with labels after creation [Optional]
CONFLUENCE_ADD_CONTENT_LABEL
Key parameters:
- : Space ID or key (e.g.,
spaceId,"DOCS") -- space keys are auto-converted to IDs"12345678" - : Page title (must be unique within a space)
title - : Parent page ID for creating child pages; omit to place under space homepage
parentId - : HTML/XHTML content in Confluence storage format
body.storage.value - : Must be
body.storage.representationfor create operations"storage" - : For updates, must be current version + 1
version.number - : Optional change description
version.message
Pitfalls:
- Confluence enforces unique page titles per space; creating a page with a duplicate title will fail
- requires
UPDATE_PAGEset to current version + 1; always fetch current version first withversion.numberGET_PAGE_BY_ID - Content must be in Confluence storage format (XHTML), not plain text or Markdown
- uses
CREATE_PAGEwhilebody.storage.valueusesUPDATE_PAGEwithbody.valuebody.representation - requires a numeric long ID, not a UUID or string
GET_PAGE_BY_ID
适用场景:用户需要创建新文档或更新现有Confluence页面
工具执行顺序:
- - 列出所有空间以找到目标空间ID [前提步骤]
CONFLUENCE_GET_SPACES - - 查找现有页面以避免重复或定位父页面 [可选步骤]
CONFLUENCE_SEARCH_CONTENT - - 在更新前获取当前页面内容和版本号 [更新操作的前提步骤]
CONFLUENCE_GET_PAGE_BY_ID - - 在指定空间中创建新页面 [创建操作的必要步骤]
CONFLUENCE_CREATE_PAGE - - 使用新内容更新现有页面并递增版本号 [更新操作的必要步骤]
CONFLUENCE_UPDATE_PAGE - - 创建页面后为其添加标签 [可选步骤]
CONFLUENCE_ADD_CONTENT_LABEL
关键参数:
- : 空间ID或空间键(例如:
spaceId,"DOCS")—— 空间键会自动转换为IDs"12345678" - : 页面标题(同一空间内必须唯一)
title - : 创建子页面时的父页面ID;若省略则将页面置于空间首页下
parentId - : Confluence存储格式的HTML/XHTML内容
body.storage.value - : 创建操作时必须设置为
body.storage.representation"storage" - : 更新操作时必须设置为当前版本 + 1
version.number - : 可选的变更描述
version.message
注意事项:
- Confluence要求同一空间内页面标题唯一;创建重复标题的页面会失败
- 要求
UPDATE_PAGE设置为当前版本号+1;请始终先通过version.number获取当前版本GET_PAGE_BY_ID - 内容必须采用Confluence存储格式(XHTML),而非纯文本或Markdown
- 使用
CREATE_PAGE,而body.storage.value使用UPDATE_PAGE并配合body.valuebody.representation - 需要数值型长ID,而非UUID或字符串
GET_PAGE_BY_ID
2. Search Content
2. 搜索内容
When to use: User wants to find pages, blog posts, or content across Confluence
Tool sequence:
- - Keyword search with intelligent relevance ranking [Required]
CONFLUENCE_SEARCH_CONTENT - - Advanced search using Confluence Query Language [Alternative]
CONFLUENCE_CQL_SEARCH - - Hydrate full content for selected search results [Optional]
CONFLUENCE_GET_PAGE_BY_ID - - Browse pages sorted by date when search relevance is weak [Fallback]
CONFLUENCE_GET_PAGES
Key parameters for SEARCH_CONTENT:
- : Search text matched against page titles with intelligent ranking
query - : Limit search to a specific space
spaceKey - : Max results (default 25, max 250)
limit - : Pagination offset (0-based)
start
Key parameters for CQL_SEARCH:
- : CQL query string (e.g.,
cql)text ~ "API docs" AND space = DOCS AND type = page - : Comma-separated properties (e.g.,
expand,content.space)content.body.storage - :
excerpt,highlight, orindexednone - : Max results (max 250; reduced to 25-50 when using body expansions)
limit
CQL operators and fields:
- Fields: ,
text,title,label,space,type,creator,lastModified,createdancestor - Operators: ,
=,!=(contains),~,!~,>,<,>=,<=,INNOT IN - Functions: ,
currentUser(),now("-7d")now("-30d") - Example:
title ~ "meeting" AND lastModified > now("-7d") ORDER BY lastModified DESC
Pitfalls:
- fetches up to 300 pages and applies client-side filtering -- not a true full-text search
CONFLUENCE_SEARCH_CONTENT - is the real full-text search; use
CONFLUENCE_CQL_SEARCHfor content body searchtext ~ "term" - HTTP 429 rate limits can occur; throttle to ~2 requests/second with backoff
- Using body expansions in CQL_SEARCH may reduce max results to 25-50
- Search indexing is not immediate; recently created pages may not appear
适用场景:用户需要在Confluence中查找页面、博客文章或其他内容
工具执行顺序:
- - 带智能相关性排序的关键词搜索 [必要步骤]
CONFLUENCE_SEARCH_CONTENT - - 使用Confluence查询语言(CQL)进行高级搜索 [替代方案]
CONFLUENCE_CQL_SEARCH - - 为选定的搜索结果获取完整内容 [可选步骤]
CONFLUENCE_GET_PAGE_BY_ID - - 当搜索相关性较差时,按日期浏览页面 [备选方案]
CONFLUENCE_GET_PAGES
SEARCH_CONTENT的关键参数:
- : 与页面标题匹配的搜索文本,带智能排序
query - : 将搜索范围限制到指定空间
spaceKey - : 最大结果数(默认25,最大250)
limit - : 分页偏移量(从0开始)
start
CQL_SEARCH的关键参数:
- : CQL查询字符串(例如:
cql)text ~ "API docs" AND space = DOCS AND type = page - : 逗号分隔的属性列表(例如:
expand,content.space)content.body.storage - : 可选值为
excerpt、highlight或indexednone - : 最大结果数(最大250;当使用内容扩展时会减少至25-50)
limit
CQL运算符与字段:
- 字段:、
text、title、label、space、type、creator、lastModified、createdancestor - 运算符:、
=、!=(包含)、~、!~、>、<、>=、<=、INNOT IN - 函数:、
currentUser()、now("-7d")now("-30d") - 示例:
title ~ "meeting" AND lastModified > now("-7d") ORDER BY lastModified DESC
注意事项:
- 最多获取300个页面并在客户端进行筛选 —— 并非真正的全文搜索
CONFLUENCE_SEARCH_CONTENT - 是真正的全文搜索;使用
CONFLUENCE_CQL_SEARCH搜索内容正文text ~ "term" - 可能会触发HTTP 429速率限制;请将请求频率限制在约2次/秒,并使用退避策略
- 在CQL_SEARCH中使用内容扩展可能会将最大结果数减少至25-50
- 搜索索引并非即时生效;最近创建的页面可能不会立即出现在搜索结果中
3. Manage Spaces
3. 管理空间
When to use: User wants to list, create, or inspect Confluence spaces
Tool sequence:
- - List all spaces with optional filtering [Required]
CONFLUENCE_GET_SPACES - - Get detailed metadata for a specific space [Optional]
CONFLUENCE_GET_SPACE_BY_ID - - Create a new space with key and name [Optional]
CONFLUENCE_CREATE_SPACE - - Retrieve custom metadata stored as space properties [Optional]
CONFLUENCE_GET_SPACE_PROPERTIES - - List pages, blog posts, or attachments in a space [Optional]
CONFLUENCE_GET_SPACE_CONTENTS - - List labels on a space [Optional]
CONFLUENCE_GET_LABELS_FOR_SPACE
Key parameters:
- : Space key -- alphanumeric only, no underscores or hyphens (e.g.,
key,DOCS)PROJECT1 - : Human-readable space name
name - :
typeorglobalpersonal - :
status(active) orcurrentarchived - : For GET_SPACE_CONTENTS, filters by space key
spaceKey - : Numeric space ID for GET_SPACE_BY_ID (NOT the space key)
id
Pitfalls:
- Space keys must be alphanumeric only (no underscores, hyphens, or special characters)
- requires numeric space ID, not the space key; use
GET_SPACE_BY_IDto find numeric IDsGET_SPACES - Clickable space URLs may need assembly: join (relative) with
_links.webui_links.base - Default pagination is 25; set explicitly (max 200 for spaces)
limit
适用场景:用户需要列出、创建或查看Confluence空间信息
工具执行顺序:
- - 列出所有空间,支持可选筛选 [必要步骤]
CONFLUENCE_GET_SPACES - - 获取指定空间的详细元数据 [可选步骤]
CONFLUENCE_GET_SPACE_BY_ID - - 使用空间键和名称创建新空间 [可选步骤]
CONFLUENCE_CREATE_SPACE - - 检索存储为空间属性的自定义元数据 [可选步骤]
CONFLUENCE_GET_SPACE_PROPERTIES - - 列出空间中的页面、博客文章或附件 [可选步骤]
CONFLUENCE_GET_SPACE_CONTENTS - - 列出空间中的标签 [可选步骤]
CONFLUENCE_GET_LABELS_FOR_SPACE
关键参数:
- : 空间键 —— 仅允许字母数字,不支持下划线、连字符(例如:
key,DOCS)PROJECT1 - : 易读的空间名称
name - :
type(全局)或global(个人)personal - :
status(活跃)或current(已归档)archived - : 用于GET_SPACE_CONTENTS,按空间键筛选
spaceKey - : GET_SPACE_BY_ID所需的数值型空间ID(而非空间键)
id
注意事项:
- 空间键必须仅包含字母数字(不支持下划线、连字符或特殊字符)
- 需要数值型空间ID,而非空间键;使用
GET_SPACE_BY_ID查找数值型IDsGET_SPACES - 可点击的空间URL可能需要拼接:将(相对路径)与
_links.webui拼接_links.base - 默认分页为25条;请显式设置(空间最大为200)
limit
4. Navigate Page Hierarchy and Labels
4. 页面层级导航与标签管理
When to use: User wants to explore page trees, child pages, ancestors, or manage labels
Tool sequence:
- - Find the target page ID [Prerequisite]
CONFLUENCE_SEARCH_CONTENT - - List direct children of a parent page [Required]
CONFLUENCE_GET_CHILD_PAGES - - Get the full ancestor chain for a page [Optional]
CONFLUENCE_GET_PAGE_ANCESTORS - - List labels on a specific page [Optional]
CONFLUENCE_GET_LABELS_FOR_PAGE - - Add labels to a page [Optional]
CONFLUENCE_ADD_CONTENT_LABEL - - List labels across all content in a space [Optional]
CONFLUENCE_GET_LABELS_FOR_SPACE_CONTENT - - Audit edit history for a page [Optional]
CONFLUENCE_GET_PAGE_VERSIONS
Key parameters:
- : Page ID for child pages, ancestors, labels, and versions
id - : Opaque pagination cursor for GET_CHILD_PAGES (from
cursor)_links.next - : Items per page (max 250 for child pages)
limit - : Child page sort options:
sort,id,-id,created-date,-created-date,modified-date,-modified-date,child-position-child-position
Pitfalls:
- only returns direct children, not nested descendants; recurse for full tree
GET_CHILD_PAGES - Pagination for GET_CHILD_PAGES uses cursor-based pagination (not start/limit)
- Verify the correct page ID from search before using as parent; search can return similar titles
- requires the page ID, not a version number
GET_PAGE_VERSIONS
适用场景:用户需要浏览页面树、子页面、父页面链或管理标签
工具执行顺序:
- - 查找目标页面ID [前提步骤]
CONFLUENCE_SEARCH_CONTENT - - 列出父页面的直接子页面 [必要步骤]
CONFLUENCE_GET_CHILD_PAGES - - 获取页面的完整父页面链 [可选步骤]
CONFLUENCE_GET_PAGE_ANCESTORS - - 列出指定页面的标签 [可选步骤]
CONFLUENCE_GET_LABELS_FOR_PAGE - - 为页面添加标签 [可选步骤]
CONFLUENCE_ADD_CONTENT_LABEL - - 列出空间内所有内容的标签 [可选步骤]
CONFLUENCE_GET_LABELS_FOR_SPACE_CONTENT - - 审核页面的编辑历史 [可选步骤]
CONFLUENCE_GET_PAGE_VERSIONS
关键参数:
- : 用于获取子页面、父页面链、标签及版本的页面ID
id - : GET_CHILD_PAGES使用的不透明分页游标(来自
cursor)_links.next - : 每页条目数(子页面最大为250)
limit - : 子页面排序选项:
sort,id,-id,created-date,-created-date,modified-date,-modified-date,child-position-child-position
注意事项:
- 仅返回直接子页面,不包含嵌套的后代页面;需递归调用以获取完整树状结构
GET_CHILD_PAGES - GET_CHILD_PAGES使用基于游标的分页(而非start/limit)
- 在将搜索结果用作父页面之前,请验证页面ID是否正确;搜索可能返回标题相似的页面
- 需要页面ID,而非版本号
GET_PAGE_VERSIONS
Common Patterns
通用模式
ID Resolution
ID解析
Always resolve human-readable names to IDs before operations:
- Space key -> Space ID: with
CONFLUENCE_GET_SPACESfilter, orspaceKeyaccepts space keys directlyCREATE_PAGE - Page title -> Page ID: with
CONFLUENCE_SEARCH_CONTENTparam, then extract page IDquery - Space ID from URL: Extract numeric ID from Confluence URLs or use GET_SPACES
在执行操作前,请始终将易读名称解析为ID:
- 空间键 -> 空间ID:使用带筛选条件的
spaceKey,或CONFLUENCE_GET_SPACES直接支持空间键CREATE_PAGE - 页面标题 -> 页面ID:使用带参数的
query,然后提取页面IDCONFLUENCE_SEARCH_CONTENT - 从URL获取空间ID:从Confluence URL中提取数值型ID,或使用GET_SPACES获取
Pagination
分页
Confluence uses two pagination styles:
- Offset-based (most endpoints): (0-based offset) +
start(page size). Incrementlimitbystartuntil fewer results thanlimitare returned.limit - Cursor-based (GET_CHILD_PAGES, GET_PAGES): Use the from
cursorin the response. Continue until no_links.nextlink is present.next
Confluence支持两种分页方式:
- 基于偏移量(大多数端点):(从0开始的偏移量) +
start(每页大小)。每次将limit增加start,直到返回结果数少于limitlimit - 基于游标(GET_CHILD_PAGES、GET_PAGES):使用响应中的
_links.next。持续调用直到没有cursor链接next
Content Formatting
内容格式
- Pages use Confluence storage format (XHTML), not Markdown
- Basic elements: ,
<p>-<h1>,<h6>,<strong>,<em>,<code>,<ul>,<ol><li> - Tables: /
<table><tbody><tr><th>structure<td> - Macros: for code blocks, etc.
<ac:structured-macro ac:name="code"> - Always wrap content in proper XHTML tags
- 页面使用Confluence存储格式(XHTML),而非Markdown
- 基础元素:,
<p>-<h1>,<h6>,<strong>,<em>,<code>,<ul>,<ol><li> - 表格:/
<table><tbody><tr><th>结构<td> - 宏:使用表示代码块等
<ac:structured-macro ac:name="code"> - 请始终将内容包裹在正确的XHTML标签中
Known Pitfalls
常见注意事项
ID Formats
ID格式
- Space IDs are numeric (e.g., ); space keys are short strings (e.g.,
557060)DOCS - Page IDs are numeric long values for GET_PAGE_BY_ID; some tools accept UUID format
- requires numeric ID, not the space key
GET_SPACE_BY_ID - takes an integer, not a string
GET_PAGE_BY_ID
- 空间ID为数值型(例如:);空间键为短字符串(例如:
557060)DOCS - GET_PAGE_BY_ID所需的页面ID为数值型长值;部分工具支持UUID格式
- 需要数值型空间ID,而非空间键
GET_SPACE_BY_ID - 接受整数,而非字符串
GET_PAGE_BY_ID
Rate Limits
速率限制
- HTTP 429 can occur on search endpoints; honor Retry-After header
- Throttle to ~2 requests/second with exponential backoff and jitter
- Body expansion in CQL_SEARCH reduces result limits to 25-50
- 搜索端点可能会触发HTTP 429错误;请遵守Retry-After响应头
- 将请求频率限制在约2次/秒,并使用指数退避和抖动策略
- 在CQL_SEARCH中使用内容扩展会将结果限制减少至25-50
Content Format
内容格式
- Content must be Confluence storage format (XHTML), not Markdown or plain text
- Invalid XHTML will cause page creation/update to fail
- nests body under
CREATE_PAGE;body.storage.valueusesUPDATE_PAGE+body.valuebody.representation
- 内容必须采用Confluence存储格式(XHTML),而非Markdown或纯文本
- 无效的XHTML会导致页面创建/更新失败
- 将内容嵌套在
CREATE_PAGE下;body.storage.value使用UPDATE_PAGE+body.valuebody.representation
Version Conflicts
版本冲突
- Updates require exact next version number (current + 1)
- Concurrent edits can cause version conflicts; always fetch current version immediately before updating
- Title changes during update must still be unique within the space
- 更新操作需要准确的下一个版本号(当前版本+1)
- 并发编辑可能导致版本冲突;请在更新前立即获取当前版本
- 更新时修改的标题仍需在空间内唯一
Quick Reference
快速参考
| Task | Tool Slug | Key Params |
|---|---|---|
| List spaces | | |
| Get space by ID | | |
| Create space | | |
| Space contents | | |
| Space properties | | |
| Search content | | |
| CQL search | | |
| List pages | | |
| Get page by ID | | |
| Create page | | |
| Update page | | |
| Delete page | | |
| Child pages | | |
| Page ancestors | | |
| Page labels | | |
| Add label | | content ID, label |
| Page versions | | |
| Space labels | | space ID |
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 列出空间 | | |
| 通过ID获取空间 | | |
| 创建空间 | | |
| 空间内容 | | |
| 空间属性 | | |
| 搜索内容 | | |
| CQL搜索 | | |
| 列出页面 | | |
| 通过ID获取页面 | | |
| 创建页面 | | |
| 更新页面 | | |
| 删除页面 | | |
| 子页面 | | |
| 页面父链 | | |
| 页面标签 | | |
| 添加标签 | | 内容ID, 标签 |
| 页面版本 | | |
| 空间标签 | | 空间ID |