MCP Confluence Server

# MCP Confluence 服务 这是一个基于 MCP (Model Context Protocol) 的 Confluence API 服务实现。该服务提供了与 Confluence 进行交互的能力，支持获取空间信息、页面内容、搜索等功能。 ## 目录 - [功能特性](#功能特性) - [快速开始](#快速开始) - [配置说明](#配置说明) - [开发指南](#开发指南) - [MCP 工具使用指南](#mcp-工具使用指南) - [工具概览](#工具概览) - [性能优化](#性能优化) - [调试指南](#调试指南) - [错误处理](#错误处理) ## 功能特性 ### 🔐 认证方式 - **Access Token 认证**（推荐） - **用户名密码认证** - 支持多环境配置 ### 🔧 MCP 工具架构（已优化） - **工具合并优化**: 从12个工具精简为8个（减少33%） - **统一API设计**: 通过action参数区分操作类型 - **智能参数验证**: 根据操作自动验证必需参数 - **完整参数注释**: MCP Inspector中可查看详细说明 ### 📄 页面管理功能 - **`managePages`**: 统一页面管理工具 ⭐️ - 创建页面（支持父页面和内容格式） - 更新页面（增量更新支持） - **删除页面** ⭐️ **新增功能** - 获取页面基本信息 - 获取页面详细内容 - **Markdown支持** 🆕 **自动转换为HTML** - **`getPageByPrettyUrl`**: 通过标题精确获取页面 - **`getSpace`**: 获取空间信息 ### 💬 评论管理功能 - **`manageComments`**: 统一评论管理工具 ⭐️ - **普通评论**: 创建、更新、删除、回复 - **行内评论**: 创建、更新、删除、回复 - 支持评论版本控制和监视 - **Markdown支持** 🆕 **智能检测与转换** - **`getPageComments`**: 获取页面所有评论（支持分页） - **`getComment`**: 获取单个评论详情 ### 🔍 搜索功能 - **`searchContent`**: 全文搜索内容（支持CQL语法） - **`searchComments`**: 搜索评论内容（支持空间限定） - **错误回退机制**: CQL语法错误时自动尝试基本搜索 ### ⚡ 性能优化 - **HTTP 连接复用**: Keep-Alive支持 - **响应压缩**: 自动压缩传输 - **请求超时控制**: 可配置超时时间 - **错误重试机制**: 自动重试失败请求 ### 📊 日志和监控 - **结构化日志输出**: JSON格式日志 - **请求耗时统计**: 性能监控 - **详细错误信息**: 便于调试 - **操作记录追踪**: 完整的操作日志 ## 快速开始 ### 环境要求 - Node.js >= 14.0.0 - TypeScript >= 4.0.0 ### 安装 ```bash # 安装依赖 npm install ``` ### 构建 ```bash # 清理并构建项目 npm run build:clean ``` ### 启动服务 ```bash # 启动服务 npm start ``` ## 配置说明 ### 认证配置 服务支持两种认证方式，你可以选择其中一种： #### 1. Access Token 认证（推荐） 在 `.env` 文件中配置： ```env CONFLUENCE_URL=https://your-confluence-url CONFLUENCE_ACCESS_TOKEN=your-access-token ``` #### 2. 用户名密码认证 在 `.env` 文件中配置： ```env CONFLUENCE_URL=https://your-confluence-url CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-password ``` ### 其他配置项 ```env # 服务器配置 PORT=3000 NODE_ENV=development TIMEOUT=10000 REJECT_UNAUTHORIZED=true ``` ### Cursor IDE 配置 #### Windows 配置 1. 使用 Smithery（推荐） 在 `%USERPROFILE%\.cursor\mcp.json` 中添加： ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "cmd", "args": [ "/c", "npx", "-y", "@smithery/cli@latest", "run", "@enjoyzl/mcp-server-confluence-ts", "--config", "{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}" ] } } } ``` 2. 本地服务方式 在 `%USERPROFILE%\.cursor\mcp.json` 中添加： ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "cmd", "args": [ "/k", "cd", "/d", "D:\\workspace\\code\\mcp\\mcp-server-confluence-ts", "&", "node", "dist/index.js" ] } } } ``` > **Windows 配置说明：** > - `/k`: 执行命令后保持命令窗口，便于查看日志 > - `/d`: 切换到指定驱动器 > - 使用 `&` 连接多个命令 > - 路径使用双反斜杠 `\\` 转义 > - 环境变量可以在项目的 `.env` 文件中配置 #### Mac/Linux 配置 1. 使用 Smithery（推荐） 在 `~/.cursor/mcp.json` 中添加： ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "bash", "args": [ "-c", "npx -y @smithery/cli@latest run @enjoyzl/mcp-server-confluence-ts --config '{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}'" ] } } } ``` 2. 本地服务方式 在 `~/.cursor/mcp.json` 中添加： ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "node", "args": ["/Users/your-username/workspace/code/mcp/mcp-server-confluence-ts/dist/index.js"], "env": { "CONFLUENCE_URL": "your-confluence-url", "CONFLUENCE_USERNAME": "youraccount", "CONFLUENCE_PASSWORD": "yourpwd", } } } } ``` > **Mac/Linux 配置说明：** > - `-c`: 执行命令字符串 > - 使用 `&&` 连接多个命令 > - 路径使用正斜杠 `/` > - 环境变量可以在项目的 `.env` 文件中配置 > - Mac 用户主目录通常在 `/Users/your-username/` > - Linux 用户主目录通常在 `/home/your-username/` ### 开发模式 ```bash # 监听文件变化并自动编译 npm run dev # 监听文件变化并自动重启服务 npm run dev:start ``` ### 构建命令 ```bash # 仅构建项目 npm run build # 清理构建目录 npm run clean # 清理并重新构建 npm run build:clean ``` ### 调试工具 ```bash # 基本调试模式 npm run inspector # 开发调试模式（带详细日志） npm run inspector:dev ``` ## MCP 工具使用指南 ### 🚀 工具架构优化 本服务已完成工具架构优化，按功能和使用频率重新组织： ``` 📁 1. 基础信息工具（最常用） 📁 2. 页面管理工具（核心功能） 📁 3. 评论管理工具（扩展功能） 📁 4. 搜索工具（专用搜索） ``` ### 🔧 MCP 工具列表 #### 1. 基础信息工具 - 最常用的查询功能 **`getSpace`** - 获取空间信息 ```json { "name": "getSpace", "arguments": { "spaceKey": "DEV" } } ``` **`getPageByPrettyUrl`** - 根据标题精确获取页面 ```json { "name": "getPageByPrettyUrl", "arguments": { "spaceKey": "DEV", "title": "API 开发指南" } } ``` #### 2. 页面管理工具 - 核心功能 **`managePages`** - 统一页面管理 ⭐️ **合并优化** **创建页面：** ```json { "name": "managePages", "arguments": { "action": "create", "spaceKey": "DEV", "title": "新页面标题", "content": "<p>页面内容</p>", "parentId": "123456789", "representation": "storage" } } ``` **更新页面：** ```json { "name": "managePages", "arguments": { "action": "update", "pageId": "123456789", "title": "更新的标题", "content": "<p>更新的内容</p>", "version": 2, "representation": "storage" } } ``` **删除页面：** ⭐️ **新增功能** ```json { "name": "managePages", "arguments": { "action": "delete", "pageId": "123456789" } } ``` **获取页面基本信息：** ```json { "name": "managePages", "arguments": { "action": "get", "pageId": "123456789" } } ``` **获取页面详细内容：** ```json { "name": "managePages", "arguments": { "action": "getContent", "pageId": "123456789", "expand": "body.storage,version,space" } } ``` #### 3. 评论管理工具 - 扩展功能 **`manageComments`** - 统一评论管理 ⭐️ **合并优化** **创建普通评论（HTML格式）：** ```json { "name": "manageComments", "arguments": { "action": "create", "commentType": "regular", "pageId": "123456789", "content": "这是一条普通评论", "representation": "storage" } } ``` **创建普通评论（Markdown格式）：** 🆕 ```json { "name": "manageComments", "arguments": { "action": "create", "commentType": "regular", "pageId": "123456789", "content": "## 代码审查意见\n\n这段代码需要优化：\n\n- **性能问题**: 数据库查询未优化\n- **安全问题**: 缺少输入验证\n\n建议修改：\n\n``javascript\n// 使用索引查询\nconst user = await User.findById(id).lean();\n```", "representation": "markdown" } } ``` **创建行内评论：** ```json { "name": "manageComments", "arguments": { "action": "create", "commentType": "inline", "pageId": "123456789", "content": "这里需要注意性能问题", "originalSelection": "QueryHoldingsService.setHoldingData()", "matchIndex": 0, "numMatches": 1 } } ``` **更新评论：** ```json { "name": "manageComments", "arguments": { "action": "update", "commentType": "regular", "commentId": "98765432", "content": "更新后的评论内容", "version": 2 } } ``` **删除评论：** ```json { "name": "manageComments", "arguments": { "action": "delete", "commentType": "regular", "commentId": "98765432" } } ``` **回复普通评论：** ```json { "name": "manageComments", "arguments": { "action": "reply", "commentType": "regular", "pageId": "123456789", "parentCommentId": "98765432", "content": "这是一条回复", "watch": false } } ``` **回复行内评论：** ```json { "name": "manageComments", "arguments": { "action": "reply", "commentType": "inline", "commentId": "98765432", "pageId": "123456789", "content": "这是对行内评论的回复" } } ``` **`getPageComments`** - 获取页面所有评论 ```json { "name": "getPageComments", "arguments": { "pageId": "123456789", "start": 0, "limit": 25 } } ``` **`getComment`** - 获取单个评论详情 ```json { "name": "getComment", "arguments": { "commentId": "98765432" } } ``` #### 4. 搜索工具 - 专用搜索功能 **`searchContent`** - 搜索页面内容（支持CQL） ```json { "name": "searchContent", "arguments": { "query": "API 开发" } } ``` **`searchComments`** - 搜索评论内容 ```json { "name": "searchComments", "arguments": { "query": "性能优化", "spaceKey": "DEV", "start": 0, "limit": 25 } } ``` ### 📝 参数说明 #### action 参数选项： - **页面管理**: `create`, `update`, `delete`, `get`, `getContent` - **评论管理**: `create`, `update`, `delete`, `reply` #### commentType 参数选项： - **`regular`** (默认): 普通评论 - **`inline`**: 行内评论 #### representation 参数选项： - **`storage`** (推荐): HTML存储格式 - **`wiki`**: Wiki标记语法 - **`editor2`**: 编辑器格式 - **`view`**: 查看格式 - **`markdown`** 🆕: Markdown格式（自动转换为HTML） ### 🎯 优化亮点 ✅ **工具数量优化**: 从12个工具合并为8个（减少33%） ✅ **统一API设计**: 通过action参数区分操作类型 ✅ **智能参数验证**: 根据操作类型自动验证必需参数 ✅ **完整参数注释**: MCP Inspector中可查看详细参数说明 ✅ **新增删除功能**: 支持删除页面操作 ✅ **双评论类型**: 统一管理普通评论和行内评论 ## 🚀 新功能：Markdown 导出 ### 导出功能概览 现在支持将 Confluence 页面导出为 Markdown 文件到当前工作空间！ #### 🎯 支持的导出方式 1. **单页面导出** (`exportPage`) - 导出指定页面为 Markdown 文件 - 支持按章节拆分大文档 - 可选的 YAML frontmatter 元数据 2. **层次结构导出** (`exportPageHierarchy`) - 递归导出页面及其所有子页面 - 保持原有的目录层次结构 - 可控制递归深度 3. **批量导出** (`batchExportPages`) - 同时导出多个指定页面 - 智能并发控制和错误处理 - 性能优化和进度跟踪 #### 🌟 核心特性 - ✅ **智能内容转换**: 高质量的 HTML 到 Markdown 转换 - ✅ **章节拆分**: 根据标题级别自动拆分大文档 - ✅ **元数据保留**: 完整的页面信息作为 YAML frontmatter - ✅ **文件管理**: 智能文件命名和冲突处理 - ✅ **性能优化**: 并发控制、重试机制、内存优化 - ✅ **进度跟踪**: 实时导出状态和错误报告 #### 📖 快速开始 ``` # 导出单个页面 { "pageId": "123456789", "outputDir": "my-docs", "includeMetadata": true } # 按章节拆分导出 { "pageId": "123456789", "splitByChapters": true, "splitLevel": "2" } # 导出页面层次结构 { "pageId": "123456789", "maxDepth": 3, "includeChildren": true } # 批量导出多个页面 { "pageIds": ["123", "456", "789"], "concurrency": 3 } ``` #### 📁 输出示例 ``` confluence-export/ ├── API_Documentation.md # 单页面导出 ├── User_Guide/ # 层次结构导出 │ ├── User_Guide.md │ ├── Getting_Started/ │ │ └── Installation.md │ └── Advanced_Topics/ │ └── Configuration.md └── Large_Document/ # 章节拆分导出 ├── README.md # 章节索引 ├── 01_introduction.md ├── 02_setup.md └── 03_usage.md ``` 详细使用指南请参考：[导出功能指南](docs/export-functionality-guide.md) ## 安全建议 1. 优先使用 Access Token 认证方式，这样更安全 2. 定期轮换 Access Token 3. 不要在代码中硬编码认证信息 4. 确保 `.env` 文件已添加到 `.gitignore` 中 5. 在生产环境中使用环境变量或安全的配置管理系统 6. 如果同时配置了两种认证方式，系统会优先使用 Access Token ## 注意事项 1. Access Token 和用户名密码认证方式只能选择其中一种 2. 如果同时配置了两种认证方式，系统会优先使用 Access Token 3. 确保配置的 URL 是正确的 Confluence API 地址 4. 在生产环境中建议使用 HTTPS ## 性能优化 1. 连接优化 - 启用 HTTP Keep-Alive - 限制最大并发连接数 - 控制空闲连接数 2. 请求优化 - 响应压缩 - 超时控制 - 重定向限制 3. 错误处理 - 自动重试机制 - 详细的错误信息 - 请求耗时统计 ## 调试指南 ### 日志输出 服务使用结构化日志输出，包含以下信息： ```json { "jsonrpc": "2.0", "method": "log", "params": { "level": "info", "message": "请求信息", "timestamp": "2024-04-16T12:00:44.000Z" } } ``` ## 错误处理 错误响应格式： ```typescript interface ErrorResponse { message: string; statusCode?: number; error?: any; config?: { url?: string; method?: string; params?: any; }; } ``` ## 工具概览 ### 🎯 架构优化后的工具分组 经过架构优化，工具按使用频率和逻辑分组重新组织： #### 📁 1. 基础信息工具（最常用） - `getSpace` - 获取空间信息 - `getPageByPrettyUrl` - 根据标题精确获取页面 #### 📁 2. 页面管理工具（核心功能） - `managePages` ⭐️ - 统一页面管理（create/update/delete/get/getContent） #### 📁 3. 评论管理工具（扩展功能） - `manageComments` ⭐️ - 统一评论管理（create/update/delete/reply，支持普通+行内评论） - `getPageComments` - 获取页面所有评论 - `getComment` - 获取单个评论详情 #### 📁 4. 搜索工具（专用搜索） - `searchContent` - 搜索页面内容（支持CQL语法） - `searchComments` - 搜索评论内容 ### 📊 优化成果 - **工具数量**: 从12个优化为8个（减少33%） - **API统一**: 合并同类功能，通过action参数区分操作 - **功能增强**: 新增页面删除、完善参数注释 - **体验提升**: 按使用频率排序，提高查找效率 ## 文档 - [MCP Inspector 调试参数指南](docs/DEBUG-PARAMETER-GUIDE.md) ⭐️ **新增** - [页面管理功能使用指南](docs/pages-management-example.md) - [评论功能使用指南](docs/comments-merged-example.md) - [搜索功能故障排除](docs/SEARCH-TROUBLESHOOTING.md) - [行内评论示例](docs/inline-comments-example.md) - [Confluence 7.4 兼容性](docs/CONFLUENCE-7.4-COMPATIBILITY.md) - [故障排除](docs/CONFLUENCE-7.4-TROUBLESHOOTING.md) ## 贡献 欢迎提交 Issue 和 Pull Request。 ## 许可证 [MIT License](LICENSE) ## 配置 ### 环境变量配置 在项目根目录创建 `.env` 文件，配置以下参数： ```env # Confluence 连接配置 CONFLUENCE_URL=https://your-confluence.com CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-password # 或者使用访问令牌 CONFLUENCE_ACCESS_TOKEN=your-access-token # 服务器配置 PORT=3000 NODE_ENV=development SERVER_TIMEOUT=10000 # 评论 API 策略配置 COMMENT_API_STRATEGY=standard COMMENT_ENABLE_FALLBACK=true COMMENT_TIMEOUT=15000 ``` ### 评论策略配置说明 评论功能支持三种API实现策略，可通过环境变量 `COMMENT_API_STRATEGY` 配置： #### 1. `standard` (默认，推荐) - 使用标准 REST API - 兼容性好，适合 Confluence 7.4+ - 稳定性高，适合生产环境 #### 2. `tinymce` - 使用 TinyMCE 端点 - 功能更丰富，模拟浏览器行为 - 支持更复杂的评论功能 #### 3. `auto` - 自动选择策略 - 优先使用 TinyMCE，失败时回退到标准 API - 平衡功能性和兼容性 #### 其他评论配置 - `COMMENT_ENABLE_FALLBACK`: 是否启用回退机制 (默认: true) - `true`: 当首选API失败时，自动尝试备用API - `false`: 只使用指定的API，失败时直接抛出错误 - `COMMENT_TIMEOUT`: 评论请求超时时间，单位毫秒 (默认: 15000) - 建议标准API使用 10-15 秒 - TinyMCE API 由于需要获取token等步骤，建议 15-20 秒 #### Confluence 7.4 特别说明 - 标准API在7.4版本中稳定性更好 - TinyMCE API提供更丰富的功能，但可能有兼容性问题 - 建议在生产环境使用 `standard` 策略，开发环境可根据需要选择 ### 部署到私有 npm 仓库 登录仓库参考: [PRIVATE_DOCUMENTATION_URL] ```bash # 登录并部署 npm login --registry=[PRIVATE_REGISTRY] npm publish @[ORGANIZATION]/mcp-server-confluence-ts ``` #### Claude CLI 安装（推荐） ``shell claude mcp add --transport stdio mcp-server-confluence-ts -- npx --registry=[PRIVATE_REGISTRY] -y @[ORGANIZATION]/mcp-server-confluence-ts ``` #### Cursor 安装 **Cursor MCP 配置文件** (通常位于 `~/.cursor/settings.json` 或项目 `.cursor/mcp.json`): ```json { "mcpServers": { "mcp-server-confluence-ts": { "command": "npx", "args": ["--registry=[PRIVATE_REGISTRY]","-y", "@[ORGANIZATION]/mcp-server-confluence-ts"], "env": { "CONFLUENCE_URL": "your-confluence-url", "CONFLUENCE_USERNAME": "youraccount", "CONFLUENCE_PASSWORD": "yourpwd", } } } } ```