内容
# 旧版 Confluence MCP 服务器
[](https://www.npmjs.com/package/confluence-legacy-mcp-cli)
[](https://www.npmjs.com/package/confluence-legacy-mcp-cli)
[](https://github.com/DevquasarX9/mcp-confluence-legacy/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[](docs/research-summary.md)
适用于 Atlassian Confluence 服务器 6.0.x 的外部 MCP 服务器，作为 Node.js/TypeScript 进程构建，通过其兼容旧版的 REST API 与 Confluence 通信。搜索关键词：Confluence MCP，MCP Confluence，Confluence 服务器 MCP，旧版 Confluence MCP，Atlassian Confluence MCP 服务器。
- npm 包：[confluence-legacy-mcp-cli](https://www.npmjs.com/package/confluence-legacy-mcp-cli)
- 命令行界面：`confluence-legacy-mcp-server`
- 本地身份验证代理命令行界面：`confluence-local-auth-proxy`
- 仓库：[DevquasarX9/mcp-confluence-legacy](https://github.com/DevquasarX9/mcp-confluence-legacy)
- 目标：Atlassian Confluence 服务器 6.0.5
- 兼容：Claude Code、Claude Desktop、Codex、Cursor 等 MCP 客户端
- 项目文档：[贡献](CONTRIBUTING.md)、[安全](SECURITY.md)、[MIT 许可证](LICENSE)、[发布检查清单](docs/release-checklist.md)
## 目的
本项目为 Codex、Claude Desktop、Cursor 等 AI 客户端提供安全、基于权限的 Confluence 工具。
它故意设计为外部 MCP 服务器，而不是 Confluence P2/OSGi 插件。它依赖于 Confluence 的身份验证 REST 调用，并让 Confluence 为配置的身份强制执行空间/页面/内容权限。
## 兼容性
- 主要目标：Confluence 服务器 6.0.5
- API 家族：`/rest/api`
- REST 兼容性基础：Confluence 6.0.x 公共 REST 文档，使用最近发布的 6.0.4/6.0.6 参考
- 传输：MCP stdio
- 正文写入格式：Confluence `storage` XHTML
非目标：
- Confluence 云 REST v2
- Atlassian 文档格式
- 云 `accountId` 假设
- 仅限插件的 Confluence 内部实现
- 破坏性页面/空间删除工具
## 研究摘要
Atlassian 的公共 REST 索引未公开 Confluence 6.0.5 特定的 REST 参考。该实现使用相邻 6.0.x REST 参考中记录的保守端点。
主要发现：
- REST 资源位于 `/rest/api` 下。
- 响应为 JSON。
- 扩展使用 `expand`，包括点表示法，如 `body.storage` 和 `body.view`。
- 分页使用 `start` 和 `limit`，服务器端可能有上限。
- CQL 内容搜索可在 `/rest/api/content/search` 处使用。
- 页面创建/更新使用 `/rest/api/content`。
- 页面更新必须增加 `version.number`。
- 可写页面/评论正文使用 `storage` 表示。
- 附件使用多部分表单数据，需要 `X-Atlassian-Token: nocheck`。
- 标签通过 `/rest/api/content/{id}/label` 读取和添加。
- Confluence 权限由身份验证的 REST 身份强制执行。
- 原生 PAT 不是 Confluence 服务器 6.0.5 的标准功能；Atlassian 文档介绍了来自 Data Center 7.9 的 Confluence PAT 支持。
参见 [docs/research-summary.md](docs/research-summary.md) 以获取完整的研究笔记和链接。
## 架构
```text
MCP 客户端
|
| stdio
v
confluence-legacy-mcp-server
|
| HTTP REST API，无上游凭证
v
confluence-local-auth-proxy (127.0.0.1:4878)
|
| HTTPS REST API，注入上游身份验证
v
Atlassian Confluence 服务器 6.0.5
```
主要源代码布局：
```text
src/
index.ts
server.ts
config/
env.ts
schema.ts
confluence/
auth.ts
client.ts
endpoints.ts
errors.ts
types.ts
security/
audit.ts
guards.ts
limits.ts
redaction.ts
tools/
attachments.ts
comments.ts
helpers.ts
index.ts
labels.ts
pages.ts
search.ts
spaces.ts
utils/
logger.ts
pagination.ts
result.ts
validation.ts
tests/
```
架构决策记录在 [docs/architecture-decision-record.md](docs/architecture-decision-record.md) 中。
## 安装
全局安装：
```bash
npm install -g confluence-legacy-mcp-cli
```
使用 npx 运行：
```bash
npx -y confluence-legacy-mcp-cli
```
本地开发：
```bash
npm install
npm run build
npm test
```
## 配置
推荐的设置将上游 Confluence 凭证排除在 MCP 服务器和 MCP 客户端配置之外。在本地身份验证代理中运行身份验证代理，作为唯一知道真实 Confluence 用户名/密码的进程，然后将 MCP 服务器指向该代理。
本地代理模式下的 MCP 服务器配置：
```env
CONFLUENCE_BASE_URL=http://127.0.0.1:4878
CONFLUENCE_AUTH_MODE=none
CONFLUENCE_READ_ONLY=true
CONFLUENCE_ENABLE_WRITE_TOOLS=false
```
可选设置：
```env
CONFLUENCE_STRICT_SSL=true
CONFLUENCE_CA_CERT_PATH=/absolute/path/to/ca.pem
CONFLUENCE_TIMEOUT_MS=30000
CONFLUENCE_MAX_RESULTS=50
CONFLUENCE_MAX_RESPONSE_BYTES=1048576
CONFLUENCE_MAX_ATTACHMENT_BYTES=10485760
CONFLUENCE_LOG_LEVEL=info
CONFLUENCE_AUDIT_LOG=false
CONFLUENCE_DRY_RUN=false
CONFLUENCE_ALLOWED_SPACES=DEV,OPS
CONFLUENCE_DENIED_SPACES=SECRET
```
## 身份验证
支持的模式：
- `none`：不发送身份验证头。推荐在 MCP 服务器与 `confluence-local-auth-proxy` 通信时使用。
- `basic`：用户名加密码。只有在您明确接受凭证存储在 MCP 服务器进程中时才使用。
- `bearer`：反向代理、SSO 或较新的自定义部署的 bearer 令牌。股票 6.0.5 不提供原生 PAT。
- `header`：静态受信任代理头。
- `cookie`：预先颁发的 cookie 值，作为 `CONFLUENCE_COOKIE` 提供。
无身份验证本地代理模式：
```env
CONFLUENCE_BASE_URL=http://127.0.0.1:4878
CONFLUENCE_AUTH_MODE=none
```
基本身份验证：
```env
CONFLUENCE_AUTH_MODE=basic
CONFLUENCE_USERNAME=alice
CONFLUENCE_PASSWORD=secret
```
Bearer 身份验证：
```env
CONFLUENCE_AUTH_MODE=bearer
CONFLUENCE_TOKEN=token-from-proxy-or-newer-data-center
```
受信任头：
```env
CONFLUENCE_AUTH_MODE=header
CONFLUENCE_AUTH_HEADER_NAME=X-Forwarded-User
CONFLUENCE_AUTH_HEADER_VALUE=service-account
```
Cookie：
```env
CONFLUENCE_AUTH_MODE=cookie
CONFLUENCE_COOKIE=JSESSIONID=...
```
此服务器故意不支持 `os_username` 和 `os_password` URL 查询凭证。
## 本地身份验证代理
`confluence-local-auth-proxy` 是一个本地的 HTTP 身份验证桥，模仿 Jira 本地身份验证代理模式。MCP 服务器调用代理；代理注入上游 Confluence 身份验证并仅转发允许列出的 REST 路由。
代理环境：
```env
CONFLUENCE_UPSTREAM_BASE_URL=https://confluence.example.com/confluence
CONFLUENCE_UPSTREAM_AUTH_MODE=basic
CONFLUENCE_UPSTREAM_USERNAME=confluence-service-user
CONFLUENCE_UPSTREAM_PASSWORD=super-secret-password
CONFLUENCE_PROXY_HOST=127.0.0.1
CONFLUENCE_PROXY_PORT=4878
CONFLUENCE_PROXY_READ_ONLY=true
CONFLUENCE_PROXY_ENABLE_WRITE=false
CONFLUENCE_PROXY_STRICT_SSL=true
```
启动代理：
```bash
confluence-local-auth-proxy
```
可选的本地代理令牌：
```env
CONFLUENCE_LOCAL_PROXY_TOKEN=replace-with-a-random-local-token
```
如果配置了代理令牌，MCP 服务器必须将令牌作为头发送：
```env
CONFLUENCE_BASE_URL=http://127.0.0.1:4878
CONFLUENCE_AUTH_MODE=header
CONFLUENCE_AUTH_HEADER_NAME=X-Confluence-Proxy-Token
CONFLUENCE_AUTH_HEADER_VALUE=replace-with-the-same-local-token
```
代理路由策略：
- 读取路由：内容搜索、内容读取、子页面/评论/附件、标签和空间。
- 默认情况下禁用写入路由：创建内容、更新内容和添加标签。
- 附件上传额外受 `CONFLUENCE_PROXY_ENABLE_ATTACHMENTS=true` 控制。
- 不转发破坏性删除路由。
## MCP 客户端设置
示例客户端配置位于 [`examples/clients/`](examples/clients/) 中：
- [Claude Code 指南](examples/clients/claude_code.md)
- [共享客户端设置指南](examples/clients/README.md)
- [Claude Desktop JSON 配置](examples/clients/claude_desktop_config.json)
- [Codex TOML 配置](examples/clients/codex-config.toml)
- [Cursor MCP JSON 配置](examples/clients/cursor.mcp.json)
通用 MCP 服务器配置：
```json
{
"mcpServers": {
"confluence": {
"command": "confluence-legacy-mcp-server",
"env": {
"CONFLUENCE_BASE_URL": "http://127.0.0.1:4878",
"CONFLUENCE_AUTH_MODE": "none",
"CONFLUENCE_READ_ONLY": "true",
"CONFLUENCE_ENABLE_WRITE_TOOLS": "false"
}
}
}
}
```
## 可用工具
### `confluence_search`
使用 CQL 搜索内容。
```json
{
"cql": "space = DEV and type = page",
"expand": ["space", "body.view", "version"],
"start": 0,
"limit": 25
}
```
### `confluence_get_page`
通过 ID 获取页面。
```json
{
"pageId": "123456",
"expand": ["space", "body.storage", "version", "ancestors"]
}
```
### `confluence_get_page_children`
列出直接子页面。
```json
{
"pageId": "123456",
"expand": ["body.view", "version"],
"start": 0,
"limit": 25
}
```
### `confluence_list_spaces`
列出空间。
```json
{
"type": "global",
"status": "current",
"expand": ["description.plain", "homepage"],
"start": 0,
"limit": 25
}
```
### `confluence_get_space`
获取一个空间。
```json
{
"spaceKey": "DEV",
"expand": ["description.plain", "homepage"]
}
```
### `confluence_create_page`
创建页面。需要 `CONFLUENCE_READ_ONLY=false` 和 `CONFLUENCE_ENABLE_WRITE_TOOLS=true`。
```json
{
"spaceKey": "DEV",
"title": "运行手册",
"body": "<p>运行手册正文</p>",
"parentId": "123456"
}
```
### `confluence_update_page`
更新页面。需要写入模式。
```json
{
"pageId": "123456",
"title": "更新的运行手册",
"body": "<p>更新的正文</p>",
"minorEdit": true,
"versionMessage": "由 MCP 更新"
}
```
### `confluence_get_comments`
列出直接页面评论。
```json
{
"pageId": "123456",
"expand": ["body.storage", "version"],
"start": 0,
"limit": 25
}
```
### `confluence_add_comment`
添加页面评论。需要写入模式。
```json
{
"pageId": "123456",
"body": "<p>看起来不错。</p>"
}
```
### `confluence_list_attachments`
列出页面附件。
```json
{
"pageId": "123456",
"filename": "运行手册.pdf",
"expand": ["version", "container"],
"start": 0,
"limit": 25
}
```
### `confluence_upload_attachment`
上传附件。需要写入模式。
```json
{
"pageId": "123456",
"filePath": "/absolute/path/to/file.txt",
"fileName": "file.txt",
"comment": "由 MCP 上传",
"minorEdit": true,
"mediaType": "text/plain"
}
```
### `confluence_get_labels`
列出内容标签。
```json
{
"contentId": "123456",
"prefix": "global",
"start": 0,
"limit": 25
}
```
### `confluence_add_label`
将标签添加到内容。需要写入模式。
```json
{
"contentId": "123456",
"labels": ["docs", { "name": "运行手册", "prefix": "global" }]
}
```
完整模式在 [docs/tool-schemas.md](docs/tool-schemas.md) 中有详细文档。
## 安全注意事项
- 优先使用 `confluence-local-auth-proxy`，以便上游 Confluence 凭证不进入 MCP 客户端/服务器配置。
- 凭证从不硬编码。
- 日志会编辑令牌、密码、cookie、机密和类似授权字段。
- 默认启用只读模式。
- 写入工具需要 `CONFLUENCE_READ_ONLY=false` 和 `CONFLUENCE_ENABLE_WRITE_TOOLS=true`。
- `CONFLUENCE_DRY_RUN=true` 返回写入有效载荷而不调用写入端点。
- 使用 `CONFLUENCE_TIMEOUT_MS` 强制执行请求超时。
- 使用 `CONFLUENCE_MAX_RESPONSE_BYTES` 限制响应大小。
- 使用 `CONFLUENCE_MAX_ATTACHMENT_BYTES` 限制附件大小。
- 空间允许/拒绝过滤器可以限定服务器行为，但 Confluence 权限仍然是真相来源。
## 开发命令
```bash
npm run dev
npm run typecheck
npm run lint
npm test
npm run build
npm run start
npm run clean
```
## 构建和打包
```bash
npm run clean
npm run build
npm run pack:dry-run
```
软件包发布 `dist`、`README.md`、`LICENSE`、`docs` 和 `examples`。
## 持续集成/持续部署
GitHub Actions 工作流：
- `.github/workflows/ci.yml`：在推送和拉取请求时安装依赖、类型检查、 lint、测试、构建和验证软件包内容。
- `.github/workflows/publish.yml`：在发布 GitHub 版本时发布到 npm。
## npm 发布
1. 在 [docs/release-checklist.md](docs/release-checklist.md) 中运行发布检查清单。
2. 提升 `package.json` 版本。
3. 创建并推送 git 标签。
4. 发布 GitHub 版本，或运行：
```bash
npm publish --access public
```
## 已知限制
- Confluence 6.0.5 特定 REST 文档未公开索引；本项目针对记录的 6.0.x 兼容端点。
- 页面/评论写入需要存储 XHTML。
- 无原生 Confluence 6.0.5 PAT 支持。
- 无云 v2 API。
- 无自动 Markdown 到存储转换。
- 无破坏性页面、附件、标签或空间删除工具。
- 内联评论、嵌套评论创建、限制管理、监视和管理员操作未包含在初始工具集中。
## 参考
- [Confluence REST API 6.0.6](https://docs.atlassian.com/atlassian-confluence/REST/6.0.6/)
- [Confluence 服务器/数据中心 REST API 概述](https://developer.atlassian.com/server/confluence/confluence-server-rest-api/)
- [Atlassian 个人访问令牌](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器