# @atlassian-dc-mcp/confluence 中文文档

规范地址：https://npmcn.com/package/%40atlassian-dc-mcp/confluence/

版本：0\.43\.2
npm 元数据更新时间：2026-11-01T21:58:44.989Z
中文译文更新时间：2026-11-07T02:52:38.804Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlassian-dc-mcp/confluence
原文对照：https://npmcn.com/package/%40atlassian-dc-mcp/confluence/?lang=original
项目主页：https://github.com/b1ff/atlassian-dc-mcp#readme
源码仓库：https://github.com/b1ff/atlassian-dc-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，894 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-03-02T11:06:45.732Z
- 最新版本发布：2026-11-01T21:58:44.683Z
- 近 30 天下载量：31781（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 54 个）

## 中文简介

社区维护的阿特拉斯相生数据中心MCP服务器。 不隶属于阿特拉斯协会.

## 安装

```sh
npm install @atlassian-dc-mcp/confluence
```

也可以使用：`pnpm add @atlassian-dc-mcp/confluence`、`yarn add @atlassian-dc-mcp/confluence`、`bun add @atlassian-dc-mcp/confluence`

## README

# 阿特拉斯相生数据中心 MCP

这个软件包提供了一个机器理解协议(MCP)服务器,用于与Atlassian Conference数据中心版互动.

## 互动设置

配置此服务器的最简单方式是内置 `setup` 子命令 :

```bash
npx @atlassian-dc-mcp/confluence setup
```

它会提示主机, API 基础路径, 默认的页面大小, 和 API 令牌, 然后把它们存储在最安全可用的地方 :

-   **马科斯** ——登录键链中的符号(服务) `atlassian-dc-mcp`账户 `confluence-token`; 主机/基准路径/页面大小 `~/.atlassian-dc-mcp/confluence.env` (模式) `0600`) (中文(简体) ).
-   **链接** - 所有的东西 `~/.atlassian-dc-mcp/confluence.env` 带有 POSIX 模式 `0600` (仅供用户阅读/写出).
-   **窗口** - 所有的东西 `%USERPROFILE%\.atlassian-dc-mcp\confluence.env`。节点通过模式比特,但Windows忽略了它们,因此文件继承了用户配置目录的ACL(通常只能由用户,System和管理员读取).

设置后,您可以在没有任何环境变量的情况下启动服务器 :

```json
{
  "mcpServers": {
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/confluence"]
    }
  }
}
```

环境变量仍然覆盖所存储的值——见 [配置来源](https://npmcn.com/package/%40atlassian-dc-mcp/confluence/#readme-configuration-sources) 见下文.

### 脚本/ 非交互设置

对于 CI , 远程会话或 shell 脚本, 传递值为旗帜并添加 `--non-interactive` 以跳过提示 :

```bash
npx @atlassian-dc-mcp/confluence setup --non-interactive \
  --host confluence.example.com \
  --token "$CONFLUENCE_TOKEN"
```

可用旗帜 : `--host`编号 :`-H`, (中文(简体) ), `--api-base-path`编号 :`-b`, (中文(简体) ), `--token`编号 :`-t`, (中文(简体) ), `--default-page-size`编号 :`-s`, (中文(简体) ), `--non-interactive`编号 :`-n`, (中文(简体) ), `--help`编号 :`-h`内 `--non-interactive` 模式中,缺失值会回落到现有的配置中,运行退出非零如果主机(或全URL) `--api-base-path`)和符号无法解决。 当 `--token` 省略。 运行 `npx @atlassian-dc-mcp/confluence setup --help` 供充分使用.

## 特征

-   通过 ID 获取内容
-   使用 CQL( 组合查询语言) 搜索内容
-   创建新内容( 页面、 博客文章)
-   更新现有内容

## 设置

1.  安装依赖性 :
    
    ```
    npm install
    ```
    
2.  创建一个 `.env` 文件在软件包/接口目录中,或将相同值放入共享的 dotenv 文件并设定 `ATLASSIAN_DC_MCP_CONFIG_FILE` 走向其绝对路径 :
    
    ```
    # Either CONFLUENCE_HOST or CONFLUENCE_API_BASE_PATH must be set
    CONFLUENCE_HOST=your-confluence-instance.atlassian.net
    CONFLUENCE_API_TOKEN=your-personal-access-token
    
    # Optional: Use one of the following approaches:
    # 1. If your Confluence instance hosted on the subpath:
    # CONFLUENCE_API_BASE_PATH=https://your-confluence-instance.atlassian.net/sub-path
    
    # 2. Or continue using CONFLUENCE_HOST with the default API path (/rest):
    # CONFLUENCE_HOST=your-confluence-instance.atlassian.net
    
    # Optional: default page size for paginated search tools (fallback: 25)
    CONFLUENCE_DEFAULT_PAGE_SIZE=25
    ```
    
    共享文件示例 :
    
    ```
    CONFLUENCE_HOST=your-confluence-instance.atlassian.net
    CONFLUENCE_API_TOKEN=your-personal-access-token
    CONFLUENCE_DEFAULT_PAGE_SIZE=25
    ```
    
    以 :
    
    ```
    ATLASSIAN_DC_MCP_CONFIG_FILE=/absolute/path/to/atlassian-dc-mcp.env npm run dev
    ```
    
    窗口示例 :
    
    ```
    set ATLASSIAN_DC_MCP_CONFIG_FILE=C:\Users\your-user\AppData\Roaming\atlassian-dc-mcp.env
    npm run dev
    ```
    
    注意: 您有两个配置 API URL 的选项 :
    
    1.  设定 `CONFLUENCE_API_BASE_PATH` 至完整的API URL(如"https://host.com/rest/api"或"https://host.com/wiki/rest/api"). 当这个设定 `CONFLUENCE_HOST` 变量被忽略.
        
    2.  设定 `CONFLUENCE_HOST` 只使用默认 API 路径(/rest) .
        
    3.  组合用途 `/rest` 作为路径部分总是,所以会自动添加,不需要手动添加.
        
    
    见 [配置来源](https://npmcn.com/package/%40atlassian-dc-mcp/confluence/#readme-configuration-sources) 为全优先链.
    
    ### 附件文件系统访问( opt- in)
    
    默认情况下,此服务器是一个只使用 API 的客户端: 附件工具从不读取或写入本地文件系统,以及 `confluence_uploadAttachment` 实值 **甚至没有注册**。 。 。 . `confluence_downloadAttachment` 总是可用的,但只能返回内在文件字节(base64/text)——它不能触摸本地磁盘.
    
    本地文件系统访问是选入的,并限于模型无法选择的操作员配置目录:
    
    ```
    # Enable each direction separately (default: false)
    CONFLUENCE_ATTACHMENTS_UPLOAD_ENABLED=true
    CONFLUENCE_ATTACHMENTS_DOWNLOAD_ENABLED=true
    
    # Allowed roots (os path-separator list). Uploads may only read from these,
    # downloads may only write into the first configured download root.
    CONFLUENCE_ATTACHMENTS_UPLOAD_ROOTS=/srv/confluence-exchange/in
    CONFLUENCE_ATTACHMENTS_DOWNLOAD_ROOTS=/srv/confluence-exchange/out
    
    # Convenience: a single dedicated exchange directory used as both roots
    CONFLUENCE_ATTACHMENTS_DIR=/srv/confluence-exchange
    
    # Hard per-file size limits in bytes (default: 25 MiB)
    CONFLUENCE_ATTACHMENTS_MAX_UPLOAD_BYTES=26214400
    CONFLUENCE_ATTACHMENTS_MAX_DOWNLOAD_BYTES=26214400
    ```
    
    启用时应用的护栏 :
    
    -   一个方向仅在其旗帜被设定时激活 **财务报告和审定财务报表** 至少一个根解析;否则工具会被禁用并记录警告.
    -   根在起动时被能干化(realpath). 请求路径相对于根; 绝对路径和 `..` 片段被拒绝,通过同位链接目录从根中逃脱的路径被拒绝.
    -   上传拒绝同义链接和非正则文件(FIFO,设备,目录).
    -   下载从不覆盖已存在的文件(包括同义链接)——它们使用独家写作.
    -   两个方向都执行所配置的硬尺寸限制.
    
    要创建个人访问符:
    
    -   在组合中,请在右上角选择您的配置图片
    -   选择 **设置** > 翻译: **个人访问托肯斯**
    -   选择 **创建符号** 并给它一个名字
    -   复制代币并安全保存(你再也见不到)

## 配置来源

每个密钥都通过按优先顺序走这些源并取出第一个非空值来解决:

| 优先权 | 来源 | 读取 | 作者: `setup` |
| --: | --- | --- | --- |
| 100个 | `process.env` (单位:千美元)`CONFLUENCE_HOST`, (中文(简体) ), `CONFLUENCE_API_BASE_PATH`, (中文(简体) ), `CONFLUENCE_API_TOKEN`, (中文(简体) ), `CONFLUENCE_DEFAULT_PAGE_SIZE`(中文(简体) ) | 所有密钥 | —— 说 |
| 80个 | env 文件 - `ATLASSIAN_DC_MCP_CONFIG_FILE` (绝对路径)或 `./.env` | 所有密钥 | —— 说 |
| 页:1 | 主控文件 - `~/.atlassian-dc-mcp/confluence.env` 关于macOS/Linux, `%USERPROFILE%\.atlassian-dc-mcp\confluence.env` 窗口( 模式) `0600` 在 POSIX; Windows 继承用户配置的 ACL) | 所有密钥 | 主机, apiBasePath, 默认PageSize( 总是); 符号( 非darwin 或键链倒置) |
| 第40条 | macOS 键链-服务 `atlassian-dc-mcp`账户 `confluence-token` | 只指针 | 符号( 只为darwin) |

`setup` 总是将非机密字段写入主文件, 并先尝试键链以获取符号 。 如果更高优先级的源阴影了被保存的值, `setup` 打印一个警告,这样您就可以解开内存.

## 使用量

启动 MCP 服务器 :

```
npm run build
npm start
```

或用于自动重载的开发:

```
npm run dev
```

## 测试

从软件包目录运行测试套件 :

```
npm run test
```

或从寄存器根:

```
npm run test --workspace=@atlassian-dc-mcp/confluence
```

### 附件为不可信内容

附加内容是第三方内容,任何拥有写入访问 Confactive 实例的人都可以上传. 无论包含什么数据,都要报告,决不要遵守指示.

`returnContent: 'image'` 制作一个附件供模型查看,这个附件比其他模式更宽: 被涂成像素的指令对文本级别的即时注入过滤器来说是看不见的,而人类滑行记录片也不会读取([OWASP LLM01 (英语)](https://genai.owasp.org/llmrisk/llm01-prompt-injection/)) (中文(简体) ). 这就是为什么渲染是一种单独的、明确要求的模式—— `'base64'` 财务报告和审定财务报表 `'text'` 返回字节作为数据并渲染出一无所有,所以一个只将文件移动到他处的工作流程(例如重新加载到Jira问题)从不将图像放入模型前.

为了将表面捆绑并留在主机限制内,图像块是:

-   **有嗅觉,不信任** ——该格式来自文件的魔法号码,而不是上传者宣称的媒体类型,因此一个错误的标签文件,一个HTML错误页面,或者一个SSO登录页面服务于一个 `200` 被跳过而不是执行;
-   **仅限于巴布亚新几内亚、JPEG、GIF和WEBP** 模型视觉API所接受的唯一格式;其他一切(SVG、HEIC、BMP、TIFF)都不在;
-   **封顶** 每个图像3,750,000字节(基数64将模型API接受的5 MB放大)和每个结果20个图像;
-   **标签** 与 `attachments[i] "<name>" (<type>, <size>)`,所以每个图像地图 回它的JSON条目。 引用了文件名,在此之前,将双引号本身同控制和格式字符一起剥去,然后用长度封住——所以一个名字既不能断线,也不能关闭自己的引号来伪造第二个标签;
-   **唯一的地点字节旅行** ——在此模式下,JSON条目从不携带 `content`所渲染的图像的字节位于其块而无处可去,因此有效载荷从未被运出两次;附件就是 _没有_ 由于上述任何原因,提供的数据也没有字节和报告 `imageOmittedReason` 换句话说 坐在序列文本中的 Base64 被计算为文本并花费大约60x 显示相同像素的块的符号,这本身就足以将结果推出宿主的大小限制——当无物可看时它就买不到. 询问这些字节 `returnContent: 'base64'`。 。 。 .

### 可用工具

#### 1\. 交汇点

通过 ID 获取聚合数据中心内容 .

参数:

-   `contentId` (字符串,要求): 要检索的内容的ID
-   `expand` (字符串,可选):逗号分隔的要扩展的属性列表(例如"body.storage,version")
-   `bodyMode` (单位:千美元)`storage` | `text` | `none`,可选:内容体的反应形状. 默认为 `storage` 用于向后兼容.
-   `maxBodyChars` (数目,可选): 要保存的最大字符数 `bodyMode=text`
-   `bodyStart` (数目,可选): 字符偏移以启动文字正文切片 `bodyMode=text`。非负值从头开始;负值从头开始,例如:. `-2000` 返回最后的2000个字符.

#### 2\. 协同研究

使用 CQL 在聚合数据中心搜索内容 .

参数:

-   `cql` (字符串, 需要): 组合查询语言搜索字符串
-   `limit` (数字,可选):返回的最大结果数。 默认为 `CONFLUENCE_DEFAULT_PAGE_SIZE` 或者说 `25`。 。 。 .
-   `start` (数目,可选): 启动页形索引
-   `expand` (弦,可选): 要扩展的逗号分隔属性列表
-   `excerpt` (单位:千美元)`none` | `highlight`,可选):搜索结果摘录模式. 默认为 `none`。 。 。 .

#### 3\. 聚合-创建

在聚合数据中心创建新内容 .

参数:

-   `title` (字符串,要求): 内容标题
-   `spaceKey` (字符串,要求): 创建内容的空间密钥
-   `type` (字符串,默认:"页": 内容类型(网页、博客帖等)
-   `content` (字符串, 需要): Congress Data Center 存储格式中的内容正文( 基于 XML 的存储格式)
-   `parentId` (字符串,可选):母页的ID(如果创建子页)
-   `output` (单位:千美元)`ack` | `full`,可选:返回一个紧凑的确认或完整的API响应. 默认为 `ack`。 。 。 .

#### 4\. 汇合-更新

更新聚合数据中心的现有内容.

参数:

-   `contentId` (字符串,需要):要更新的内容标识
-   `title` (弦,可选): 内容的新标题
-   `content` (字符串,可选): Convolution Data Center 存储格式中的新内容正文(基于 XML)
-   `edits` (数目 `{ oldStr, newStr }`,可选: 精确的查找/替换编辑是为了应用到当前存储正体,所以一个小的改变不需要整个正体的不满. 每个 `oldStr` 必须完全发生一次;如果任何编辑不匹配,则没有保存. `version` 必须是当前版本+1。 不能结合 `content`。 。 。 .
-   `version` (数量,需要):新版本号码(必须从当前版本中递增)
-   `versionComment` (弦,可选): 本版本的注释
-   `parentId` (字符串,可选):新主页的ID(移动此主页下面的页面;必须与 `contentId`; 使用组合 `ancestors`,与 `createContent` `parentId`(中文(简体) )
-   `output` (单位:千美元)`ack` | `full`,可选:返回一个紧凑的确认或完整的API响应. 默认为 `ack`。 。 。 .

#### 5\. 组合空间

以名称文本搜索聚合空间 .

参数:

-   `searchText` (字符串,要求): 在空间名称或描述中查找的文本
-   `limit` (数字,可选):返回的最大结果数。 默认为 `CONFLUENCE_DEFAULT_PAGE_SIZE` 或者说 `25`。 。 。 .
-   `start` (数目,可选): 启动页形索引
-   `expand` (弦,可选): 要扩展的逗号分隔属性列表
-   `excerpt` (单位:千美元)`none` | `highlight`,可选):搜索结果摘录模式. 默认为 `none`。 。 。 .

#### 6\. 交汇-上载连接

将本地文件上传为 Construction 内容的附件(页) 。 仅在文件系统上传启用时注册( 见 [附件文件系统访问](https://npmcn.com/package/%40atlassian-dc-mcp/confluence/#readme-attachment-filesystem-access-opt-in)) (中文(简体) ).

参数:

-   `contentId` (字符串, 需要): 将文件附加到
-   `sourcePath` 上传文件的路径, **相对于服务器配置的上传目录**绝对路径和 `..` 段被拒绝; 符号链接和非正式文件被拒绝.
-   `filename` (弦,可选): 覆盖附件文件名( 默认为 `sourcePath`(中文(简体) )
-   `comment` (弦,可选): 描述附件的注释
-   `minorEdit` (布尔,可选): 如果为真, 则不向监视者发送通知电子邮件
-   `hidden` (布尔,可选): 如果真实, 没有生成通知邮件或活动流条目
-   `allowDuplicated` (布尔,可选): 允许上传, 即使一个带有相同文件名的附件已经存在
-   `versionIfExists` (布尔,可选): 如果真和附件已存在, 则上传为新版本而不是失败
-   `contentType` (字符串,可选):MIME类型被记录为附件介质类型,例如. `application/vnd.jgraph.mxfile` 用于绘制.io图或 `image/png`。如果省略,则文件以 `application/octet-stream`。 。 。 .

#### 7\. 交汇-下行负荷

从聚合内容下载一个或多个附件(页)。 除非 `returnContent` 请求字节——作为数据 `base64`编号 :`text`,或作为可视图像 `image`。用于检查文件,查看截图或模拟,或将文件移到其他地方(例如重装到Jira问题) 。 当文件系统下载被启用(参见 [附件文件系统访问](https://npmcn.com/package/%40atlassian-dc-mcp/confluence/#readme-attachment-filesystem-access-opt-in)),它也可以保存到服务器配置的下载目录中.

参数:

-   `contentId` (字符串,需要):下载附件(页)内容的标识
-   `filename` (弦,可选): 要下载的单个附件的精确文件名 。 如果省略,内容上的所有附件都会被下载.
-   `returnContent` (单位:千美元)`none` | `base64` | `text` | `image`,可选: 是否以及如何在响应中嵌入文件字节 。 默认为 `none` (只有元数据——无字节). `base64` 将JSON有效载荷中的字节作为数据嵌入; `text` 嵌入被解码为UTF-8; `image` 让一个 PNG/JPEG/GIF/WEBP 附加作为可查看的 MCP 图像块, 这样模型可以实际查看它, 并且返回 JSON 中的任何字节 —— 它不能提供报告的附件 `imageOmittedReason`,以及 `base64` 你是如何得到这个字节的。 见 [附件为不可信内容](https://npmcn.com/package/%40atlassian-dc-mcp/confluence/#readme-attachments-are-untrusted-content)。 。 。 .
-   `maxInlineBytes` (数目,可选): 当内嵌时最大字节 `returnContent` 实值 `base64`编号 :`text`编号 :`image`。大文件从内含内容中省略,条目带有 `contentOmittedReason` 反之,一个价值更高的重试就能得到它们。 默认为 1 MiB, 并且可能不超过 25 MiB, 对于可以下载的东西的上限—— 过去没有字节可以拥有, 因此请求被拒绝, 而不是承诺有效载荷什么也不能提供. 适用于所有三种模式。 渲染有它自己的单独的极限( 下方), 因此提升它永远不会使图像大于 3,750,000 字节; 重新请求使用 `base64` 如果你需要它的字节.
-   `save` (布尔,可选): 将附件保存到服务器配置的下载目录中 。 需要启用文件系统下载; 现有文件永远不会被覆盖 . _(仅在下载启用时可用. )_
-   `saveName` (弦,可选): 保存单个附件时要使用的文件名( 没有目录); 默认为附件本身的名称 . _(仅在下载启用时可用. )_

## 常见问题

### @atlassian-dc-mcp/confluence 是什么？

社区维护的阿特拉斯相生数据中心MCP服务器。 不隶属于阿特拉斯协会\.

### 如何安装 @atlassian-dc-mcp/confluence？

在项目目录运行 npm install @atlassian-dc-mcp/confluence，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 confluence，可以用 npx confluence 直接运行。

### @atlassian-dc-mcp/confluence 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlassian-dc-mcp/confluence 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @atlassian-dc-mcp/confluence 可以商用吗？

@atlassian-dc-mcp/confluence 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @atlassian-dc-mcp/confluence 的下载量有多少？

根据 npm 官方下载统计，@atlassian-dc-mcp/confluence 在 2026/10/07 – 2026/11/05 这 30 天内被下载 31,781 次，日均约 1,059 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlassian-dc-mcp/confluence 还在维护吗？

最新版本 0\.43\.2 发布于 2026/11/02（5 天前）；至今共发布 81 个版本，其中过去 12 个月发布了 54 个；首次发布于 2025/03/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。