MCP Confluence Server

# Confluence 7.4 兼容性报告 ## 📋 概述 本文档详细说明了 MCP Confluence 服务器与 Confluence 7.4 版本的兼容性状况，包括发现的问题和相应的解决方案。 ## 🔧 已修复的兼容性问题 ### 1. 评论创建API兼容性 **问题描述：** - 原代码使用简单的 `container: { id: pageId }` 结构 - Confluence 7.4 对 `container` 字段要求更严格，需要指定 `type` 属性 **解决方案：** ```typescript // 修复前 container: { id: pageId } // 修复后 container: { type: 'page', id: pageId } ``` ### 2. 错误处理和回退机制 **问题描述：** - 原代码缺少对Confluence 7.4特定错误的处理 - 没有提供API调用失败时的回退方案 **解决方案：** ```typescript // 添加了双重回退机制 try { // 标准方式 const response = await this.client.post('/rest/api/content', data); return response.data; } catch (error) { // 回退到页面特定端点 const fallbackResponse = await this.client.post(`/rest/api/content/${pageId}/child/comment`, fallbackData); return fallbackResponse.data; } ``` ### 3. 版本冲突处理 **问题描述：** - 更新评论时缺少版本冲突的友好错误提示 **解决方案：** ```typescript if (error.response?.status === 409) { throw new Error(`Comment version conflict. Expected version ${version}, but comment may have been updated by another user.`); } ``` ## 📊 API兼容性矩阵 | 功能 | API路径 | Confluence 7.4 支持 | 修复状态 | |------|---------|---------------------|----------| | 获取页面评论 | `/rest/api/content/{pageId}/child/comment` | ✅ 完全支持 | ✅ 无需修复 | | 获取评论详情 | `/rest/api/content/{commentId}` | ✅ 完全支持 | ✅ 无需修复 | | 创建评论 | `/rest/api/content` | ⚠️ 需要特定格式 | ✅ 已修复 | | 创建评论(备选) | `/rest/api/content/{pageId}/child/comment` | ✅ 支持 | ✅ 已实现 | | 更新评论 | `/rest/api/content/{commentId}` | ✅ 完全支持 | ✅ 已优化 | | 删除评论 | `/rest/api/content/{commentId}` | ✅ 完全支持 | ✅ 无需修复 | | 搜索评论 | `/rest/api/content/search` | ✅ 完全支持 | ✅ 无需修复 | ## 🔍 已知兼容性要求 ### 1. 认证要求 - Confluence 7.4 推荐使用 Personal Access Token (Bearer Token) - 基本认证仍然支持但不建议使用 ### 2. 请求格式要求 - `Content-Type: application/json` 必须设置 - `Accept: application/json` 建议设置 - 所有请求体必须是有效的JSON格式 ### 3. 容器字段要求 - 创建评论时，`container` 字段必须包含 `type` 属性 - 支持的容器类型：`page`, `blogpost` ### 4. 扩展字段支持 - `expand` 参数支持：`body.storage`, `version`, `history`, `container` - 建议使用 `body.storage` 获取完整的评论内容 ## 🚀 测试建议 ### 1. 使用提供的测试脚本 ```bash node test-confluence-7.4-compatibility.js ``` ### 2. 手动测试步骤 1. **获取评论测试**：调用 `getPageComments` 工具 2. **创建评论测试**：调用 `createComment` 工具 3. **更新评论测试**：调用 `updateComment` 工具 4. **删除评论测试**：调用 `deleteComment` 工具 ### 3. 权限验证 确保使用的认证令牌具有以下权限： - 查看页面和评论 - 创建评论 - 编辑评论（如果是评论作者或管理员） - 删除评论（如果是评论作者或管理员） ## 📝 使用建议 ### 1. 错误处理 ```typescript try { const comments = await confluenceService.getPageComments('pageId'); // 处理成功结果 } catch (error) { if (error.message.includes('version conflict')) { // 处理版本冲突 } else if (error.response?.status === 403) { // 处理权限错误 } // 其他错误处理 } ``` ### 2. 最佳实践 - 使用 `representation: 'storage'` 作为默认格式 - 创建评论前检查页面是否存在 - 更新评论时先获取最新版本号 - 定期清理测试创建的评论 ## 🔧 故障排除 ### 常见问题及解决方案 1. **500内部服务器错误** - 检查容器字段格式是否正确 - 验证认证令牌是否有效 - 确认页面ID是否存在 2. **403权限错误** - 检查用户是否有评论权限 - 验证空间权限设置 - 确认是否为匿名用户 3. **409版本冲突** - 获取评论的最新版本号 - 重新提交更新请求 - 处理并发编辑情况 ## 📞 支持信息 - **Confluence版本**：7.4.x - **API版本**：REST API v1 - **测试环境**：`http://dms.intelnal.howbuy.com` - **维护状态**：✅ 积极维护 ## 🗂️ 相关文档 - [Confluence 7.4 REST API 文档](https://docs.atlassian.com/atlassian-confluence/REST/7.4.0/) - [评论API参考](https://docs.atlassian.com/atlassian-confluence/REST/7.4.0/#content-comment) - [认证方式文档](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) --- *最后更新：2025年1月20日*