使用说明

超汇流mcp

一种用于Confluence Cloud的模型上下文协议（MCP）服务器，围绕一个问题： Confluence调用代理的上下文窗口的多少真的需要消费吗？

大多数Confluence MCP服务器通过或多或少逐字逐句地融合REST API。偶尔也可以使用，但单一 getPage 在长文档上，可以将40KB的ADF JSON转储到对话，25页的列表响应超过500KB。代理人支付这笔费用每次通话的成本都很高，而且会挤占实际工作。

此服务器采取了不同的立场。

为什么要使用它而不是其他Confluence/Atlassian MCP

1.每次呼叫的响应平均减少约20倍

内置投影层下降 _links, _expandable、格式化器噪声，其他字段代理从不读取并将ADF/存储体转换为出去的路上标记。基准中的具体数字 docs/BENCHMARK.md:

调用	原始	修剪	缩减
25页列表（含正文）	526694 B	9753 B	54×
巨大的页面（约39 KB ADF正文）	54624 B	479 B	114×
CQL文本搜索（“自述”）	35341 B	15239 B	2.3×
11种混合情景组合	756483 B	37935 B	20×

2.大型实体卸载到磁盘，而不是上下文

当页面正文超过内联限制时，修剪层会写入原始API对临时文件的响应，并返回一个微小的 bodyPath 参考（~500字节）。需要内容调用的代理 confluence_render_body 从磁盘读取-- 并且可以通过 outputPath 到将渲染的markdown直接写入文件，这样正文字节就永远不会完全进入对话。 恢复五个10 KB页面的成本为零具有此路径的上下文字节；嵌入主体的MCP支付约50KB。

3.每次对话的工具界面小且可调

MCP工具列表响应本身需要上下文——每次对话都会付出代价在任何工作发生之前，提前做好准备。随着 CONFLUENCE_ENABLED_CATEGORIES 您可以根据代理的实际需求来定义表面：

筛选器	工具	字节	~令牌
默认值（所有类别）	63	49629	12407
`page,search,body`	15	18,483	4,621
3个类别减去破坏性行动	12	15691	3923

相比之下，许多组合的Atlassian MCP服务器在Jira上公开了70多个工具和 Confluence——如果你想要两种产品，那很好，但需要很多模式只需要读写Confluence页面的代理。如果你也需要 Jira或Bitbucket，配套服务器超级吉拉mcp 和超比特桶mcp 应用相同的修剪哲学——只连接你需要的那些而不是为一个整体的Atlassian表面付费。

4.对于喜欢支付费用的代理，有一个CLI

confluence-cli 是一个直接调用Confluence的独立二进制文件——否需要MCP主机。相同的修剪输出形状，加上 ref: /path 线指向磁盘上未修剪的完整响应。每次对话开销是单个2.3 KB SKILL.md 由Claude Code线束按需装载，而工具模式约为50KB。这两条路径共享所有修剪逻辑，因此你可以混合或切换，而不会出现行为漂移。

5.没有Docker，没有Python，没有运行时安装

这是一个Node包。如果你已经有了Node（你可能已经有了——Claude Code 船与它）， npx -y https://github.com/scottlepp/ultra-confluence-mcp 是整个安装。没有要拉取的容器，没有要管理的Python virtualenv，没有 uv/pipx/poetry 先学习，不 docker run 7号线 -e MCP配置中的标志。放下 npx 命令进入克劳德桌面/ 克劳德代码/光标，你就完成了。

6.自我修复——人类不是瓶颈（而不是安全责任）

仓库由机器人维护，因此更新不会在等待人类时停滞审阅者——但每个涉及LLM的代码修改步骤都是封闭的，因此恶意问题或PR不能将自动化变成渗透渠道：

依赖关系保持最新。 Dependabot每周打开分组PR 节奏。CI变为绿色后，补丁和小凸起会自动合并。主要颠簸使工作流失败并需要人工审阅者——这是以前的行为在PR代码上自动运行LLM“迁移代理”已禁用，因为在特权上下文中执行PR提供的代码是RCE模式。
当维护人员批准时，错误报告会自动进行分类。 预定的 bug-fix 代理仅处理带有 auto-fix-approved 标签，仅限于维护人员。问题正文被视为不可信文本（在提示中标记边界，截断、扫描外壳元字符和秘密形状）。代理人打开PR，但从不自动合并它们；一个人仍然在评论和点击合并。
PR无需等待人工即可获得第一次通过审查。 PR审查代理将diff作为数据运行——它从不将PR代码签入特权令牌包所在的工作区。代理代码始终为加载自 main.
代理的工具是沙盒的。 文件读取和写入通过拒绝绝对路径的共享路径策略， .. 遍历，符号链接指向工作目录外，以及一个涵盖以下内容的denylist .env*, .github/, scripts/agents/ 本身、锁文件、密钥文件和类似文件高爆炸半径路径。Git和npm命令使用 execFile 使用argv 数组——没有shell插值，因此模型提供了分支名称和提交消息无法注入 $() 或回溯。看 scripts/agents/src/验证/ 为了策略模块及其测试覆盖率。

这对上下文效率工具来说尤其重要：价值如果修剪层落在Confluence API后面，则命题衰减得很快更改或依赖关系中的CVE。自我修复使表面保持新鲜循环中没有维护者，也没有给循环一种方法变成后门。

这个服务器不是什么

不是多产品。 Jira住在超级吉拉mcp Bitbucket在超比特桶mcp；此服务器仅适用于Confluence Cloud，旨在保持工具轻便。
不是服务器/数据中心。 仅限云REST API v2。
不适用于人类可读的对话。 修剪很激进因为代理读取JSON，而不是文档——如果你想要漂亮的浏览器风格输出，使用Atlassian web UI。

如果你需要在一台服务器上使用Jira+Confluence+Bitbucket+服务器/DC+OAuth，有MCP服务器，但你要付出代价。如果你的代理人正在浏览Confluence上的上下文窗口，使用这个搭配超级吉拉mcp 或超比特桶mcp 当你也需要这些的时候。

安装

直接从GitHub运行：

npx -y https://github.com/scottlepp/ultra-confluence-mcp

或者克隆并在本地构建：

git clone https://github.com/scottlepp/ultra-confluence-mcp.git
cd ultra-confluence-mcp
npm install
npm run build
node build/index.js

独立CLI（无MCP服务器）

A. confluence-cli 二进制文件与MCP服务器一起发货。上面写着相同的环境变量(CONFLUENCE_HOST, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN)，在进程中构建Confluence客户端，以及直接调用Confluence——不需要MCP主机。

export CONFLUENCE_HOST=https://yourcompany.atlassian.net
export CONFLUENCE_EMAIL=you@example.com
export CONFLUENCE_API_TOKEN=...

npx -y -p github:scottlepp/ultra-confluence-mcp confluence-cli confluence_get_page --pageId=12345

发现：

confluence-cli --help                       # list every tool
confluence-cli <tool> --help                # show flags for one tool

标志形式： --key=value, --key value, --key=@/path/to/file （读从文件）， --key=- （从stdin读取），重复 --key=a --key=b 到构建一个数组（或逗号分隔 --key=a,b).

成功后，CLI将修剪后的JSON摘要打印到stdout，然后最终 ref: /tmp/.../...json 指向完全未修剪的线条磁盘上的响应-- cat 当摘要遗漏了你的细节时需要。通过 --full=true 跳过修剪并转储原始响应取而代之的是内联。

Claude代码技能

使Claude Code代理能够独立发现CLI 会话，安装捆绑技能：

npx -y -p github:scottlepp/ultra-confluence-mcp confluence-cli install-skill

这写道 ~/.claude/skills/confluence/SKILL.md.使用 --force 到覆盖，或 --print 将技能内容转储到stdout，而无需写作。

MCP与CLI——我应该使用哪一种？

有一种流行的说法是，CLIs绝对更上下文效率高于MCP。基准在 docs/BENCHMARK.md 不同意：使用激进的工具过滤 (CONFLUENCE_ENABLED_CATEGORIES)，每次对话的MCP路径开销在CLI的几KB以内 SKILL.md.每次通话输出两条路径完全相同（同一路径的修剪形状相同 applyTrim 投影）。如果不进行过滤，CLI的占用空间将减小约22倍而不是完整的MCP工具列表——但任何正在过滤的人都已经在同一个球场。

CLI的真正优势在于 人体工学的：可脚本化、可管道化、不可需要MCP主机，可以从任何shell运行。使用适合您的工作流程；在代币成本方面，这主要是对合理过滤器的清洗配置。

配置

设置以下环境变量：

变量	描述	必填
CONFLUENCE_HOST	您的CONFLUENCE实例URL（例如。，https://yourcompany.atlassian.net)	是
CONFLUENCE_EMAIL	您的Atlassian帐户电子邮件	是
CONFLUENCE_API_TOKEN	来自的API令牌 Atlassian帐户设置	是的
CONFLUENCE_CLOUD_ID	作用域令牌的云ID（如果未提供，则自动获取）	否
CONFLUENCE_ENABLED_CATEGORIES	要启用的工具类别的逗号分隔列表（默认：全部）	否
CONFLUENCE_DISABLED_TOOLS	要禁用的特定工具的逗号分隔列表	否

工具筛选

您可以使用环境变量限制哪些工具暴露在AI模型中：

仅启用特定类别：

CONFLUENCE_ENABLED_CATEGORIES=page,space,search

禁用特定工具（例如破坏性操作）：

CONFLUENCE_DISABLED_TOOLS=confluence_delete_page,confluence_delete_space,confluence_delete_blog_post

可用类别： page, space, blogPost, comment, attachment, label, search, user, version, contentProperty, ancestor, descendant, server

Claude桌面设置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "https://github.com/scottlepp/ultra-confluence-mcp"],
      "env": {
        "CONFLUENCE_HOST": "https://yourcompany.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

使用工具过滤（建议有限访问）：

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "https://github.com/scottlepp/ultra-confluence-mcp"],
      "env": {
        "CONFLUENCE_HOST": "https://yourcompany.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_ENABLED_CATEGORIES": "page,space,search,comment",
        "CONFLUENCE_DISABLED_TOOLS": "confluence_delete_page,confluence_delete_space"
      }
    }
  }
}

可用工具

页面

confluence_get_pages -获取所有带有可选过滤器的页面
confluence_get_page -按ID获取特定页面
confluence_create_page -创建新页面
confluence_update_page -更新现有页面
confluence_delete_page -删除页面
confluence_get_pages_in_space -获取空间中的所有页面
confluence_get_pages_for_label -获取具有特定标签的页面
confluence_render_body -将缓存的页面正文（ADF/磁盘存储）转换为markdown。通过 outputPath 直接写入磁盘，这样渲染体就不会膨胀代理的上下文。看阅读大型物体.

空间

confluence_get_spaces -列出所有可访问的空间
confluence_get_space -获取空间详细信息
confluence_create_space -创建新空间
confluence_update_space -更新空间
confluence_delete_space -删除空格

博客文章

confluence_get_blog_posts -获取所有博客文章
confluence_get_blog_post -获取博客文章详细信息
confluence_create_blog_post -创建新的博客文章
confluence_update_blog_post -更新博客文章
confluence_delete_blog_post -删除博客文章
confluence_get_blog_posts_in_space -在空间中获取博客文章

confluence_get_page_footer_comments -获取页面上的页脚注释
confluence_get_page_inline_comments -在页面上获取内联评论
confluence_get_blog_post_footer_comments -获取博客文章的页脚评论
confluence_get_footer_comment -获取具体评论
confluence_create_page_footer_comment -向页面添加评论
confluence_create_blog_post_footer_comment -在博客文章中添加评论
confluence_update_footer_comment -更新评论
confluence_delete_footer_comment -删除评论

附件

confluence_get_page_attachments -在页面上获取附件
confluence_get_blog_post_attachments -获取博客文章的附件
confluence_get_attachment -获取附件详细信息
confluence_delete_attachment -删除附件

搜索

confluence_cql_search -使用CQL（汇流查询语言）对页面、博客文章、附件、评论进行高级搜索
confluence_search_content -对页面和博客文章进行简单的文本搜索
confluence_search_generic_content -搜索数据库、白板、文件夹或嵌入内容（不适用于页面/博客文章）

用户

confluence_get_current_user -获取经过身份验证的用户
confluence_get_user -按帐户ID获取用户
confluence_get_users -获取所有用户

版本

confluence_get_page_versions -获取页面版本历史记录
confluence_get_page_version -获取特定页面版本
confluence_get_blog_post_versions -获取博客文章版本历史记录
confluence_get_blog_post_version -获取特定的博客文章版本

内容属性

confluence_get_page_properties -获取页面的内容属性
confluence_get_page_property -获取特定房产
confluence_create_page_property -创建属性
confluence_update_page_property -更新属性
confluence_delete_page_property -删除属性

祖先和后代

confluence_get_page_ancestors -获取父页面
confluence_get_page_descendants -获取所有子代页面
confluence_get_page_children -获取直接子页面

服务器

confluence_get_server_info -获取Confluence服务器信息

可用资源

confluence://spaces -所有无障碍空间列表
confluence://myself -当前用户信息
confluence://space/{id} -空间详细信息
confluence://page/{id} -页面详细信息
confluence://blogpost/{id} -博客文章详细信息

阅读大型正文而不涉及上下文膨胀

当单页读取返回太大而无法内联的正文时，修剪层将原始API响应卸载到磁盘，并将 bodyPath 字段上的响应。有两种使用方法：

内联渲染（默认）。 呼叫 confluence_render_body 与just bodyPath 在响应中获取转换后的markdown bodyMarkdown:

{
  "bodyPath": "/var/folders/.../ultra-confluence-mcp/pages/12345-v3.json"
}

直接到磁盘渲染 （当代理已经知道文件应该放在哪里时建议使用，例如将文档拉回到工作树中）。添加 outputPath 并且将呈现的输出写入那里；响应仅包含 { representation, sourceLength, outputPath, bytesWritten } --body字节从不遍历代理的上下文：

{
  "bodyPath": "/var/folders/.../ultra-confluence-mcp/pages/12345-v3.json",
  "outputPath": "/abs/path/to/page.md"
}

在恢复多个页面时，这大大提高了上下文效率。通过内联渲染，每个约10 KB的五个文档的成本约为50 KB，有效地从0到 outputPath。如果缺少父目录，则创建父目录；现有文件被覆盖。

两种形式都适用 format: "raw" 如果你想要原始的ADF JSON/存储XHTML而不是markdown。

主体格式

Confluence支持多种正文格式：

storage -基于XHTML的存储格式（默认）
atlas_doc_format -Atlassian文档格式（ADF）-支持Forge应用程序扩展
view -渲染HTML（只读）

存储格式（默认）

<p>This is a paragraph.</p>
<h1>This is a heading</h1>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

ADF格式

使用 bodyFormat: "atlas_doc_format" 在创建/更新页面以插入Forge应用程序宏（如美人鱼图）时。正文应该是一个JSON字符串化的ADF文档：

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

看插入Forge应用程序宏用于高级使用。

插入Forge应用程序宏（例如美人鱼图）

您可以使用ADF（Atlassian文档格式）主体格式以编程方式插入Forge应用程序宏，如Mermaid图。

美人鱼图示例

要插入美人鱼图，请使用 bodyFormat: "atlas_doc_format" 具有代码块和扩展节点：

{
  "spaceId": "123456",
  "title": "Page with Mermaid Diagram",
  "bodyFormat": "atlas_doc_format",
  "body": "{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"mermaid\"},\"content\":[{\"type\":\"text\",\"text\":\"sequenceDiagram\\n    Alice->>Bob: Hello\\n    Bob-->>Alice: Hi!\"}]},{\"type\":\"extension\",\"attrs\":{\"extensionKey\":\"23392b90-4271-4239-98ca-a3e96c663cbb/63d4d207-ac2f-4273-865c-0240d37f044a/static/mermaid-diagram\",\"extensionType\":\"com.atlassian.ecosystem\",\"parameters\":{\"localId\":\"mermaid-1\"},\"localId\":\"mermaid-1\"}}]}"
}

美人鱼的ADF结构

ADF文档结构（JSON字符串化之前）：

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "codeBlock",
      "attrs": { "language": "mermaid" },
      "content": [
        { "type": "text", "text": "sequenceDiagram\n    Alice->>Bob: Hello" }
      ]
    },
    {
      "type": "extension",
      "attrs": {
        "extensionKey": "23392b90-4271-4239-98ca-a3e96c663cbb/63d4d207-ac2f-4273-865c-0240d37f044a/static/mermaid-diagram",
        "extensionType": "com.atlassian.ecosystem",
        "parameters": { "localId": "mermaid-1" },
        "localId": "mermaid-1"
      }
    }
  ]
}

要点：

这 extensionKey 是给 美人鱼图查看器 Atlassian Labs的应用程序（必须安装在您的Confluence实例上）
这 localId 必须在内两者 parameters.localId 与 attrs.localId
Mermaid宏按位置自动检测代码块（第一个扩展名→ 1第二个代码块→ 2nd等）
使用 "parameters": { "index": N } 明确选择哪个代码块（基于0的索引）

为其他Forge应用程序查找扩展密钥

要查找其他Forge应用程序的扩展密钥：

在Confluence页面上手动插入宏
使用以下命令获取页面 bodyFormat: "atlas_doc_format"
寻找 extensionKey 在扩展节点中

CQL搜索示例

这 confluence_cql_search 该工具使用Confluence查询语言（CQL）：

# Search by content type
type=page AND space=DEV

# Full-text search
text~"search term"

# Search by creator
creator=currentUser()

# Search by date
created>=now("-7d")

# Combined search
type=page AND space=DEV AND text~"api" AND created>=now("-30d")

发展

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run with inspector
npm run inspector

自愈剂

该存储库包括用于自动维护的AI代理 scripts/agents/:

BugFixAgent：读取错误问题，验证它们，实施修复，并创建PR
PRReviewAgent：审查拉取请求，发现问题，并提出改进建议

运行代理

cd scripts/agents
npm install

# Run bug fix agent
GITHUB_TOKEN=xxx ISSUE_NUMBER=123 npm run bug-fix

# Run PR review agent
GITHUB_TOKEN=xxx PR_NUMBER=123 PR_DIFF_FILE=diff.txt npm run pr-review

支持的AI提供商

代理通过自动回退支持多个AI提供商：

谷歌人工智能（双子座）
OpenAI（GPT-4）
人类学（克劳德）
格罗克
米斯特拉尔
困惑度
深度求索
开放路由

至少设置一个API密钥：

GOOGLE_API_KEY=xxx
OPENAI_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
# etc.

许可证

麻省理工学院