Confluence MCP Server

MCP Confluence 服务

这是一个基于 MCP (Model Context Protocol) 的 Confluence API 服务实现。该服务提供了与 Confluence 进行交互的能力，支持获取空间信息、页面内容、搜索等功能。

目录

• 功能特性
• 快速开始
• 配置说明
• 开发指南
• 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

安装

# 安装依赖
npm install

构建

# 清理并构建项目
npm run build:clean

启动服务

# 启动服务
npm start

配置说明

认证配置

服务支持两种认证方式，你可以选择其中一种：

1. Access Token 认证（推荐）

在 .env 文件中配置：

CONFLUENCE_URL=https://your-confluence-url
CONFLUENCE_ACCESS_TOKEN=your-access-token

2. 用户名密码认证

在 .env 文件中配置：

CONFLUENCE_URL=https://your-confluence-url
CONFLUENCE_USERNAME=your-username
CONFLUENCE_PASSWORD=your-password

其他配置项

# 服务器配置
PORT=3000
NODE_ENV=development
TIMEOUT=10000
REJECT_UNAUTHORIZED=true

Cursor IDE 配置

Windows 配置

1. 使用 Smithery（推荐） 在 %USERPROFILE%\.cursor\mcp.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 中添加：

{
  "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 中添加：

{
  "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 中添加：

{
  "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/

开发模式

# 监听文件变化并自动编译
npm run dev

# 监听文件变化并自动重启服务
npm run dev:start

构建命令

# 仅构建项目
npm run build

# 清理构建目录
npm run clean

# 清理并重新构建
npm run build:clean

调试工具

# 基本调试模式
npm run inspector

# 开发调试模式（带详细日志）
npm run inspector:dev

MCP 工具使用指南

🚀 工具架构优化

本服务已完成工具架构优化，按功能和使用频率重新组织：

📁 1. 基础信息工具（最常用）
📁 2. 页面管理工具（核心功能）  
📁 3. 评论管理工具（扩展功能）
📁 4. 搜索工具（专用搜索）

🔧 MCP 工具列表

1. 基础信息工具 - 最常用的查询功能

getSpace - 获取空间信息

{
  "name": "getSpace",
  "arguments": {
    "spaceKey": "DEV"
  }
}

getPageByPrettyUrl - 根据标题精确获取页面

{
  "name": "getPageByPrettyUrl",
  "arguments": {
    "spaceKey": "DEV",
    "title": "API 开发指南"
  }
}

2. 页面管理工具 - 核心功能

managePages - 统一页面管理 ⭐️ 合并优化

创建页面：

{
  "name": "managePages",
  "arguments": {
    "action": "create",
    "spaceKey": "DEV",
    "title": "新页面标题",
    "content": "页面内容",
    "parentId": "123456789",
    "representation": "storage"
  }
}

更新页面：

{
  "name": "managePages",
  "arg