用途
mcp-server-atlassian-confluence 是一个 Node.js/TypeScript 实现的 MCP（Model Context Protocol）服务器，用于将 AI 助手（如 Claude、Cursor AI 等）连接到 Atlassian Confluence Cloud 知识库。通过标准 MCP 接口，AI 系统可以列出和获取空间与页面（内容格式化为 Markdown），并通过 CQL 进行搜索，从而让用户以自然语言方式访问团队文档、技术指南、政策文件等。
主要能力
- 列出与获取空间和页面：支持列出所有空间、获取空间详情、列出页面（可按 space-id 过滤）、获取页面详情、页面正文（可指定 body-format）、子页面、标签、页脚评论、行内评论等。
- 搜索：通过 CQL 查询参数在 Confluence 中搜索内容，支持跨空间搜索。
- 内容创建与更新：支持创建新页面、添加评论、更新页面内容等操作。
- ADF 到 Markdown 转换：页面内容自动转换为 Markdown 格式，便于 AI 处理。
- TOON 输出格式：默认使用 TOON（Token-Oriented Object Notation）格式，相比 JSON 可减少 30-60% 的 token 消耗，同时保持人类可读和可解析。也可通过 outputFormat 参数切换为 JSON。
- JMESPath 过滤：所有工具支持可选的 JMESPath（jq）表达式，用于提取特定字段、减少 token 成本。
- 响应截断处理：当 API 响应超过约 40,000 字符（约 10,000 token）时，服务器自动截断，并在响应末尾显示截断通知，完整原始响应保存到 /tmp/mcp/ 临时文件。
- CLI 直接访问：提供与 MCP 工具对应的命令行接口，支持 get、post、put、patch、delete 命令，可直接在终端测试和操作。
- 双传输模式：支持 STDIO（用于 Claude Desktop）和 HTTP（用于 Web 集成）两种传输方式。
- 调试日志：可启用详细请求/响应日志，日志写入 ~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log。
使用方式
获取凭据
- 访问 Atlassian API Tokens 页面，点击 Create API token，命名后立即复制生成的 token。
- 站点名称（site name）为 Confluence URL 的第一部分，例如 https://mycompany.atlassian.net 的站点名称为 mycompany。
连接 AI 助手
- Claude Desktop：在配置文件 ~/.claude/claude_desktop_config.json 中添加服务器配置，重启 Claude Desktop 后状态栏会显示 confluence 服务器。
- 其他 AI 助手：全局安装服务器（npm install -g @aashari/mcp-server-atlassian-confluence），然后配置 AI 助手使用 STDIO 传输，二进制文件名为 mcp-atlassian-confluence。
- 配置文件方式：创建 ~/.mcp/configs.json 进行系统级配置，配置键可使用 "confluence"、"atlassian-confluence"、"@aashari/mcp-server-atlassian-confluence" 或 "mcp-server-atlassian-confluence"。
- 环境变量：可通过环境变量或 .env 文件配置凭据，服务器会自动从环境变量、当前目录的 .env 文件或 ~/.mcp/configs.json 加载。
可用工具
提供 5 个通用工具，可访问任意 Confluence API 端点：
- conf_get、conf_post、conf_put、conf_patch、conf_delete
通用参数：
- path（必填）：API 端点路径，如 /wiki/api/v2/spaces
- queryParams（可选）：查询参数键值对，如 {"limit": "25", "space-id": "123"}
- jq（可选）：JMESPath 表达式，用于过滤/转换响应
- outputFormat（可选）：输出格式，"toon"（默认）或 "json"
带请求体的工具（conf_post、conf_put、conf_patch）额外需要：
- body（必填）：JSON 对象格式的请求体
常用 API 路径
- /wiki/api/v2/spaces - 列出所有空间
- /wiki/api/v2/spaces/{id} - 获取空间详情
- /wiki/api/v2/pages - 列出页面（使用 space-id 查询参数过滤）
- /wiki/api/v2/pages/{id} - 获取页面详情
- /wiki/api/v2/pages/{id}/body - 获取页面正文（使用 body-format 参数）
- /wiki/api/v2/pages/{id}/children - 获取子页面
- /wiki/api/v2/pages/{id}/labels - 获取页面标签
- /wiki/api/v2/pages/{id}/footer-comments - 列出/添加页脚评论
- /wiki/api/v2/pages/{id}/inline-comments - 列出/添加行内评论
- /wiki/api/v2/footer-comments/{comment-id} - 获取/更新/删除评论
- /wiki/api/v2/blogposts - 列出博客文章
- /wiki/api/v2/blogposts/{id} - 获取博客文章
- /wiki/rest/api/search - 搜索内容（使用 cql 查询参数）
CLI 命令
- get - GET 任意 Confluence 端点
- post - POST 到任意端点
- put - PUT 到任意端点
- patch - PATCH 任意端点
- delete - DELETE 任意端点
参数：
- -p, --path <path>（必填）：API 端点路径
- -q, --query-params <json>（可选）：查询参数 JSON
- --jq <expression>（可选）：JMESPath 过滤表达式
- -o, --output-format <format>（可选）：输出格式 toon（默认）或 json
- 带请求体的命令（post、put、patch）：-b, --body <json>（必填）
测试与开发
- 使用 MCP Inspector 提供可视化测试界面
- 可运行 HTTP 模式，默认监听 http://localhost:3000/mcp，响应为 Server-Sent Events (SSE) 格式
适用场景
- 开发者快速访问技术文档和 API 指南
- 产品经理搜索需求、规格和项目更新
- HR 团队快速访问政策文档和员工资源
- 支持团队查找故障排除指南和知识库文章
- 任何希望通过自然语言与 Confluence 交互的用户
限制
- 仅支持 Confluence Cloud，不支持 Confluence Server/Data Center（未来版本可能添加）。
- 需要 Node.js 18.0.0 或更高版本。
- 需要 Atlassian 账户具有相应空间权限，API token 需有效。
- 使用 JMESPath 过滤时需注意语法，未过滤的响应可能很大且 token 成本高。
- 大响应会被自动截断，完整数据需从 /tmp/mcp/ 临时文件获取。
- 搜索需使用 CQL 语法，建议先在 Confluence 高级搜索中验证。
- 路径区分大小写，空间和页面需使用数字 ID（而非 key）。
版本说明
- v3.2.1（当前）：添加原始响应日志与截断处理，改进依赖兼容性，升级 MCP SDK 至 v1.23.0，添加 TOON 输出格式。
- v3.0.0（破坏性变更）：用 5 个通用 HTTP 方法工具替换 8+ 个领域特定工具。迁移示例：conf_ls_spaces -> conf_get 路径 /wiki/api/v2/spaces；conf_get_space -> conf_get 路径 /wiki/api/v2/spaces/{id}；conf_ls_pages -> conf_get 路径 /wiki/api/v2/pages?space-id={id}；conf_get_page -> conf_get 路径 /wiki/api/v2/pages/{id}；conf_search -> conf_get 路径 /wiki/rest/api/search?cql=...；conf_add_comment -> conf_post 路径 /wiki/api/v2/pages/{id}/footer-comments。
