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.
Toolkit docs: composio.dev/toolkits/confluence
通过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)
- 通过工具并指定toolkit为
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 - 调用并指定toolkit为
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")——空间标识会自动转换为ID"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查找数字IDGET_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是否正确;搜索可能返回标题相似的页面
- 需要页面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 |
Powered by Composio
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 列出空间 | | |
| 通过ID获取空间 | | |
| 创建空间 | | |
| 空间内容 | | |
| 空间属性 | | |
| 内容搜索 | | |
| CQL搜索 | | |
| 列出页面 | | |
| 通过ID获取页面 | | |
| 创建页面 | | |
| 更新页面 | | |
| 删除页面 | | |
| 子页面 | | |
| 页面父链 | | |
| 页面标签 | | |
| 添加标签 | | 内容ID, 标签 |
| 页面版本 | | |
| 空间标签 | | 空间ID |
由Composio提供支持