MCP Confluence Server

# MCP Server Confluence TypeScript 服务快速开始指南 <cite> **本文档引用的文件** - [README.md](file://README.md) - [Dockerfile](file://Dockerfile) - [package.json](file://package.json) - [smithery.yaml](file://smithery.yaml) - [src/index.ts](file://src/index.ts) - [src/services/config.service.ts](file://src/services/config.service.ts) - [src/services/confluence.service.ts](file://src/services/confluence.service.ts) </cite> ## 目录 1. [简介](#简介) 2. [环境准备](#环境准备) 3. [项目安装](#项目安装) 4. [配置环境变量](#配置环境变量) 5. [启动服务](#启动服务) 6. [使用Docker部署](#使用docker部署) 7. [Smithery集成](#smithery集成) 8. [首次MCP请求测试](#首次mcp请求测试) 9. [常见问题排查](#常见问题排查) 10. [总结](#总结) ## 简介 MCP Server Confluence TypeScript是一个基于Model Context Protocol (MCP)的Confluence API服务实现。它提供了与Confluence进行交互的能力，支持获取空间信息、页面内容、评论管理、搜索功能以及Markdown导出等核心功能。 本指南将帮助您从零开始部署和运行这个服务，无论是本地开发还是容器化部署，都能轻松上手。 ## 环境准备 ### Node.js环境要求 在开始之前，请确保您的系统满足以下环境要求： - **Node.js版本**: ≥ 14.0.0 - **TypeScript版本**: ≥ 4.0.0 - **操作系统**: Windows、macOS或Linux ### 检查Node.js版本 打开终端或命令提示符，运行以下命令检查Node.js版本： ```bash node --version npm --version ``` 如果版本低于要求，请前往[Node.js官网](https://nodejs.org/)下载并安装最新稳定版本。 ### Docker环境（可选） 如果您计划使用Docker部署，还需要安装Docker： - **Docker Desktop**: 支持Windows和macOS - **Docker Engine**: 支持Linux服务器 检查Docker是否正确安装： ```bash docker --version docker-compose --version # 如果使用Docker Compose ``` ## 项目安装 ### 下载项目代码 首先，克隆项目仓库到本地： ```bash # 使用HTTPS git clone https://github.com/enjoyzl/mcp-server-confluence-ts.git # 或使用SSH（需要配置SSH密钥） git clone git@github.com:enjoyzl/mcp-server-confluence-ts.git ``` 进入项目目录： ```bash cd mcp-server-confluence-ts ``` ### 安装依赖包 项目使用npm作为包管理器。运行以下命令安装所有依赖： ```bash npm install ``` 这将安装项目所需的所有依赖包，包括： - **@modelcontextprotocol/sdk**: MCP协议SDK - **axios**: HTTP客户端库 - **express**: Web服务器框架 - **zod**: 类型验证库 - **其他开发依赖**: TypeScript、Jest测试框架等 **重要提示**: 确保网络连接正常，因为npm需要从远程仓库下载包。如果遇到网络问题，可以考虑使用国内镜像源： ```bash npm config set registry https://registry.npmmirror.com ``` ## 配置环境变量 ### 创建.env文件 项目根目录下需要创建一个`.env`文件来配置Confluence连接信息和其他服务设置。 #### 方法1：Access Token认证（推荐） ```env # Confluence连接配置 CONFLUENCE_URL=https://your-confluence-domain.atlassian.net/wiki/rest/api CONFLUENCE_ACCESS_TOKEN=your-personal-access-token # 服务器配置 PORT=3000 NODE_ENV=development SERVER_TIMEOUT=10000 # 评论API策略配置 COMMENT_API_STRATEGY=standard COMMENT_ENABLE_FALLBACK=true COMMENT_TIMEOUT=15000 # SSL证书验证（生产环境建议设为true） REJECT_UNAUTHORIZED=true ``` #### 方法2：用户名密码认证 ```env # Confluence连接配置 CONFLUENCE_URL=https://your-confluence-domain.atlassian.net/wiki/rest/api CONFLUENCE_USERNAME=your-username CONFLUENCE_PASSWORD=your-app-password # 服务器配置 PORT=3000 NODE_ENV=development SERVER_TIMEOUT=10000 # 评论API策略配置 COMMENT_API_STRATEGY=standard COMMENT_ENABLE_FALLBACK=true COMMENT_TIMEOUT=15000 # SSL证书验证 REJECT_UNAUTHORIZED=true ``` ### 环境变量说明 | 变量名 | 描述 | 默认值 | 必需 | |--------|------|--------|------| | `CONFLUENCE_URL` | Confluence API基础URL | - | 是 | | `CONFLUENCE_ACCESS_TOKEN` | Confluence个人访问令牌 | - | 二选一 | | `CONFLUENCE_USERNAME` | Confluence用户名 | - | 二选一 | | `CONFLUENCE_PASSWORD` | Confluence密码或应用密码 | - | 二选一 | | `PORT` | 服务监听端口 | 3000 | 否 | | `NODE_ENV` | 运行环境 | development | 否 | | `SERVER_TIMEOUT` | 服务器超时时间(ms) | 10000 | 否 | | `COMMENT_API_STRATEGY` | 评论API策略 | standard | 否 | | `COMMENT_ENABLE_FALLBACK` | 启用回退机制 | true | 否 | | `COMMENT_TIMEOUT` | 评论超时时间(ms) | 15000 | 否 | | `REJECT_UNAUTHORIZED` | SSL证书验证 | true | 否 | ### 安全建议 1. **优先使用Access Token**: 更安全且权限可控 2. **定期轮换Token**: 保持安全性 3. **保护.env文件**: 不要提交到版本控制系统 4. **使用环境变量**: 生产环境使用系统环境变量而非.env文件 ## 启动服务 ### 开发模式启动 开发模式下，您可以使用热重载功能，代码修改后自动重新编译和启动： ```bash # 启动开发服务器（自动重启） npm run dev:start ``` 或者分开执行： ```bash # 监听文件变化并自动编译 npm run dev # 在另一个终端中启动服务 npm start ``` ### 生产模式启动 生产环境下，先构建项目再启动： ```bash # 清理并构建项目 npm run build:clean # 启动生产服务 npm start ``` ### 验证服务启动 启动成功后，您应该看到类似以下的日志输出： ``` [INFO] MCP服务器启动中[abc123]... [DEBUG] MCP服务器已创建[abc123] [INFO] MCP服务器已成功连接并启动 ``` 此时，服务已经在`localhost:3000`上运行，等待接收MCP客户端的连接请求。 ## 使用Docker部署 ### 构建Docker镜像 项目提供了完整的Dockerfile，支持容器化部署： ```bash # 构建Docker镜像 docker build -t mcp-server-confluence . # 查看构建的镜像 docker images | grep mcp-server-confluence ``` ### 运行Docker容器 使用以下命令运行容器，并挂载必要的配置文件： ```bash # 基本运行命令 docker run -d \ --name mcp-confluence \ -p 3000:3000 \ -v $(pwd)/.env:/app/.env \ mcp-server-confluence ``` ### Docker Compose部署 创建`docker-compose.yml`文件： ```yaml version: '3.8' services: mcp-confluence: build: . ports: - "3000:3000" volumes: - ./env/.env:/app/.env restart: unless-stopped environment: - NODE_ENV=production ``` 然后运行： ```bash docker-compose up -d ``` ### 容器配置说明 - **端口映射**: 容器内的3000端口映射到主机的3000端口 - **卷挂载**: 将本地的.env文件挂载到容器内 - **环境变量**: 可以通过环境变量覆盖Dockerfile中的默认配置 - **重启策略**: 设置为unless-stopped，确保服务异常退出时自动重启 ## Smithery集成 ### 什么是Smithery？ Smithery是一个现代化的MCP服务器管理工具，可以简化MCP服务器的部署和配置。它提供了图形界面和命令行工具来管理MCP服务器。 ### 安装Smithery ```bash # 全局安装Smithery CLI npm install -g @smithery/cli ``` ### 使用Smithery启动服务 ```bash # 使用Smithery启动Confluence MCP服务器 npx @smithery/cli@latest run @enjoyzl/mcp-server-confluence-ts ``` ### 配置Smithery Smithery使用`smithery.yaml`配置文件来定义服务器的启动参数： ```yaml startCommand: type: stdio configSchema: { "type": "object", "properties": { "confluenceUrl": { "type": "string", "description": "Confluence API URL" }, "confluenceUsername": { "type": "string", "description": "Confluence username" }, "confluencePassword": { "type": "string", "description": "Confluence password" }, "confluenceAccessToken": { "type": "string", "description": "Confluence access token" } }, "anyOf": [ { "required": ["confluenceUrl", "confluenceAccessToken"] }, { "required": ["confluenceUrl", "confluenceUsername", "confluencePassword"] } ] } commandFunction: |- (config) => ({ "command": "node", "args": ["dist/index.js"], "env": { "CONFLUENCE_URL": config.confluenceUrl, "CONFLUENCE_USERNAME": config.confluenceUsername, "CONFLUENCE_PASSWORD": config.confluencePassword, "CONFLUENCE_ACCESS_TOKEN": config.confluenceAccessToken } }) ``` ### CI/CD流程中的作用 Smithery在CI/CD流程中扮演重要角色： 1. **自动化部署**: 支持持续集成和持续部署 2. **配置管理**: 集中管理MCP服务器配置 3. **版本控制**: 跟踪配置变更历史 4. **多环境支持**: 支持开发、测试、生产环境的配置分离 ## 首次MCP请求测试 ### 准备测试环境 确保服务已经成功启动，然后准备一个简单的MCP客户端来测试连接。 ### 测试工具：getSpace `getSpace`是验证服务连通性的最佳起点。它是最简单、最常用的工具之一。 #### 请求示例 ```json { "name": "getSpace", "arguments": { "spaceKey": "YOUR_SPACE_KEY" } } ``` #### 替换参数 将`YOUR_SPACE_KEY`替换为实际的Confluence空间Key。例如： ```json { "name": "getSpace", "arguments": { "spaceKey": "DEV" } } ``` ### 使用cURL测试 ```bash curl -X POST http://localhost:3000/api/tools \ -H "Content-Type: application/json" \ -d '{ "name": "getSpace", "arguments": { "spaceKey": "DEV" } }' ``` ### 使用JavaScript测试 ```javascript const axios = require('axios'); async function testGetSpace() { try { const response = await axios.post('http://localhost:3000/api/tools', { name: 'getSpace', arguments: { spaceKey: 'DEV' } }); console.log('测试结果:', JSON.stringify(response.data, null, 2)); } catch (error) { console.error('测试失败:', error.response ? error.response.data : error.message); } } testGetSpace(); ``` ### 预期响应 成功的响应应该包含类似以下内容： ```json { "content": [ { "type": "text", "text": "{\n \"id\": 12345,\n \"key\": \"DEV\",\n \"name\": \"开发团队\",\n \"description\": {\n \"plain\": {\n \"value\": \"开发团队的工作空间\"\n }\n },\n \"homepage\": {\n \"id\": \"123456789\",\n \"type\": \"page\",\n \"title\": \"首页\"\n }\n}" } ] } ``` ### 常见测试场景 1. **验证空间存在**: 使用已知的空间Key测试 2. **检查认证**: 确认Confluence凭据正确 3. **网络连通性**: 验证服务能够访问Confluence API 4. **权限测试**: 确认有足够的权限访问目标空间 ## 常见问题排查 ### 网络连接问题 #### 问题症状 - 服务启动后无法连接到Confluence - 请求超时错误 - SSL证书验证失败 #### 排查步骤 1. **检查Confluence URL** ```bash # 测试URL连通性 ping your-confluence-domain.atlassian.net # 测试API端点 curl -I https://your-confluence-domain.atlassian.net/wiki/rest/api/space ``` 2. **验证网络代理设置** ```bash # 检查代理设置 echo $HTTP_PROXY echo $HTTPS_PROXY # 如果需要，设置代理 export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 ``` 3. **调整SSL设置** ```env # 在.env文件中添加 REJECT_UNAUTHORIZED=false # 仅在开发环境使用 ``` ### 认证错误 #### 问题症状 - 401 Unauthorized错误 - 403 Forbidden错误 - 认证凭据无效 #### 排查步骤 1. **验证Access Token** ```bash # 测试Token有效性 curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-confluence-domain.atlassian.net/wiki/rest/api/space ``` 2. **检查用户名密码** ```bash # 确认用户名和密码正确 curl -u username:password \ https://your-confluence-domain.atlassian.net/wiki/rest/api/space ``` 3. **应用密码设置** - Confluence Cloud: 需要为每个应用生成独立的应用密码 - Confluence Server: 直接使用账户密码 ### 环境变量未加载 #### 问题症状 - 服务启动但报错缺少必要配置 - 环境变量值为空 #### 解决方案 1. **检查.env文件位置** ```bash # 确认.env文件在项目根目录 ls -la .env ``` 2. **验证文件格式** ```bash # 检查文件编码 file .env # 确保没有BOM头 cat -A .env ``` 3. **手动设置环境变量** ```bash # 临时设置环境变量 export CONFLUENCE_URL="https://your-confluence-domain.atlassian.net/wiki/rest/api" export CONFLUENCE_ACCESS_TOKEN="your-token-here" # 或者永久设置 echo "CONFLUENCE_URL=https://your-confluence-domain.atlassian.net/wiki/rest/api" >> ~/.bashrc ``` ### 服务启动失败 #### 问题症状 - 服务启动后立即退出 - 启动过程中出现错误 #### 排查步骤 1. **查看详细日志** ```bash # 开启调试模式 npm run inspector:dev # 或查看完整错误信息 DEBUG=* npm start ``` 2. **检查端口占用** ```bash # 检查端口3000是否被占用 netstat -an | grep 3000 # 或使用lsof（Linux/macOS） lsof -i :3000 ``` 3. **清理缓存重新构建** ```bash # 清理构建缓存 npm run clean # 重新构建项目 npm run build ``` ### 性能问题 #### 问题症状 - 响应时间过长 - 请求超时 - 内存使用过高 #### 优化建议 1. **调整超时设置** ```env # 增加超时时间 SERVER_TIMEOUT=30000 COMMENT_TIMEOUT=20000 ``` 2. **监控资源使用** ```bash # 监控内存使用 top -p $(pgrep node) # 或使用Node.js内置工具 node --inspect dist/index.js ``` 3. **启用性能监控** ```bash # 启用性能指标 export NODE_ENV=production ``` ## 总结 通过本指南，您已经完成了MCP Server Confluence TypeScript服务的完整部署过程： ### 关键步骤回顾 1. **环境准备**: 确保Node.js版本符合要求 2. **项目安装**: 使用npm安装依赖包 3. **配置设置**: 正确配置环境变量 4. **服务启动**: 选择合适的启动方式 5. **功能测试**: 使用getSpace工具验证连通性 6. **问题排查**: 掌握常见问题的解决方法 ### 下一步建议 1. **深入学习**: 探索更多MCP工具的功能 2. **集成应用**: 将服务集成到您的工作流中 3. **监控维护**: 设置日志监控和健康检查 4. **安全加固**: 实施更严格的安全措施 ### 资源链接 - **项目主页**: [GitHub仓库](https://github.com/enjoyzl/mcp-server-confluence-ts) - **官方文档**: [README.md](README.md) - **MCP协议**: [Model Context Protocol](https://modelcontextprotocol.io/) - **Confluence API**: [Atlassian开发者文档](https://developer.atlassian.com/cloud/confluence/rest/api-group-pages/) ### 技术支持 遇到问题时，您可以： - 查阅项目文档和README - 搜索GitHub Issues - 提交新的Issue寻求帮助 - 考虑贡献代码改进项目 祝您使用愉快，充分发挥MCP Server Confluence TypeScript的强大功能！