MCP Confluence 服务

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

目录

• 功能特性
• 快速开始
• 配置说明
• 开发指南
• API使用
• 性能优化
• 调试指南
• 错误处理

功能特性

• 支持多种认证方式
  • Access Token 认证（推荐）
  • 用户名密码认证
• 支持基本的 Confluence API 操作
  • 获取空间信息
  • 获取页面内容
  • 搜索内容
  • 获取页面详细信息
  • 通过 Pretty URL 获取页面信息
  • 创建和更新页面
• 内置性能优化
  • HTTP 连接复用
  • 响应压缩
  • 请求超时控制
• 完善的错误处理和日志记录
  • 结构化日志输出
  • 请求耗时统计
  • 详细的错误信息

快速开始

环境要求

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

*Configuration content*

2. 本地服务方式
   在 %USERPROFILE%\.cursor\mcp.json 中添加：

*Configuration content*

Windows 配置说明：

• /k: 执行命令后保持命令窗口，便于查看日志
• /d: 切换到指定驱动器
• 使用 & 连接多个命令
• 路径使用双反斜杠 \\ 转义
• 环境变量可以在项目的 .env 文件中配置

Mac/Linux 配置

1. 使用 Smithery（推荐）
   在 ~/.cursor/mcp.json 中添加：

*Configuration content*

2. 本地服务方式
   在 ~/.cursor/mcp.json 中添加：

*Configuration content*

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

API使用

基础API

1. 获取空间信息

const space = await confluenceService.getSpace('SPACE_KEY');

2. 获取页面信息

const page = await confluenceService.getPage('PAGE_ID');

3. 通过 Pretty URL 获取页面

const page = await confluenceService.getPageByPrettyUrl('SPACE_KEY', 'PAGE_TITLE');

4. 创建页面

const newPage = await confluenceService.createPage({
  spaceKey: 'SPACE_KEY',
  title: 'Page Title',
  content: 'Page Content',
  parentId: 'PARENT_PAGE_ID', // 可选
  representation: 'storage' // 可选，默认为 'storage'
});

5. 更新页面

const updatedPage = await confluenceService.updatePage({
  id: 'PAGE_ID',
  title: 'Updated Title', // 可选
  content: 'Updated Content', // 可选
  version: 2, // 页面版本号
  representation: 'storage' // 可选，默认为 'storage'
});

6. 搜索内容

const results = await confluenceService.searchContent('search query');

7. 获取页面详细内容

const content = await confluenceService.getPageContent('PAGE_ID');

安全建议

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. 错误处理

   • 自动重试机制
   • 详细的错误信息
   • 请求耗时统计

调试指南

日志输出

服务使用结构化日志输出，包含以下信息：

*Configuration content*

错误处理

错误响应格式：

interface ErrorResponse {
  message: string;
  statusCode?: number;
  error?: any;
  config?: {
    url?: string;
    method?: string;
    params?: any;
  };
}

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT License