Confluence

Interactúa con la API de Confluence para gestionar espacios, páginas y contenido. Permite buscar, crear y actualizar páginas.

GitHub
4

Documentación

Servicio MCP Confluence

Esta es una implementación del servicio de API de Confluence basada en MCP (Model Context Protocol). Este servicio proporciona la capacidad de interactuar con Confluence, con soporte para obtener información de espacios, contenido de páginas, búsqueda y más funciones.

Índice

Características

🔐 Autenticación

  • Autenticación con Access Token (recomendado)
  • Autenticación con nombre de usuario y contraseña
  • Compatibilidad con configuración multi-entorno

🔧 Arquitectura de herramientas MCP (optimizada)

  • Optimización de consolidación de herramientas: de 12 herramientas a 8 (reducción del 33%)
  • Diseño de API unificado: distingue los tipos de operación mediante el parámetro action
  • Validación inteligente de parámetros: valida automáticamente los parámetros requeridos según la operación
  • Comentarios completos de parámetros: se pueden ver las descripciones detalladas en MCP Inspector

📄 Gestión de páginas

  • managePages: herramienta unificada de gestión de páginas ⭐️
    • Crear página (compatible con página principal y formato de contenido)
    • Actualizar página (compatible con actualización incremental)
    • Eliminar página ⭐️ Nueva funcionalidad
    • Obtener información básica de la página
    • Obtener contenido detallado de la página
    • Compatibilidad con Markdown 🆕 Conversión automática a HTML
  • getPageByPrettyUrl: obtener página con precisión por título
  • getSpace: obtener información del espacio

💬 Gestión de comentarios

  • manageComments: herramienta unificada de gestión de comentarios ⭐️
    • Comentarios normales: crear, actualizar, eliminar, responder
    • Comentarios en línea: crear, actualizar, eliminar, responder
    • Compatibilidad con control de versiones y seguimiento de comentarios
    • Compatibilidad con Markdown 🆕 Detección y conversión inteligente
  • getPageComments: obtener todos los comentarios de una página (compatible con paginación)
  • getComment: obtener detalles de un comentario individual

🔍 Búsqueda

  • searchContent: búsqueda de contenido de texto completo (compatible con sintaxis CQL)
  • searchComments: búsqueda de comentarios (compatible con limitación por espacio)
  • Mecanismo de respaldo ante errores: intenta automáticamente búsqueda básica cuando falla la sintaxis CQL

⚡ Optimización de rendimiento

  • Reutilización de conexiones HTTP: compatibilidad con Keep-Alive
  • Compresión de respuestas: compresión automática de transmisión
  • Control de tiempo de espera de solicitudes: tiempo de espera configurable
  • Mecanismo de reintento de errores: reintento automático de solicitudes fallidas

📊 Registro y monitoreo

  • Salida de registros estructurados: registros en formato JSON
  • Estadísticas de tiempo de solicitudes: monitoreo de rendimiento
  • Información de errores detallada: facilita la depuración
  • Seguimiento de registros de operaciones: registro completo de operaciones

Inicio rápido

Requisitos del entorno

  • Node.js >= 14.0.0
  • TypeScript >= 4.0.0

Instalación

# 安装依赖
npm install

Compilación

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

Iniciar el servicio

# 启动服务
npm start

Configuración

Configuración de autenticación

El servicio admite dos métodos de autenticación, puedes elegir uno de ellos:

1. Autenticación con Access Token (recomendado)

Configurar en el archivo .env:

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

2. Autenticación con nombre de usuario y contraseña

Configurar en el archivo .env:

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

Otros elementos de configuración

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

Configuración en Cursor IDE

Configuración en Windows

  1. Usar Smithery (recomendado) Agregar en %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\"}"
      ]
    }
  }
}
  1. Modo de servicio local Agregar en %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"
      ]
    }
  }
}

Notas de configuración para Windows:

  • /k: mantener la ventana de comandos abierta después de ejecutar el comando, para facilitar la visualización de registros
  • /d: cambiar a la unidad especificada
  • Usar & para conectar múltiples comandos
  • Las rutas usan doble barra invertida \\ para escape
  • Las variables de entorno se pueden configurar en el archivo .env del proyecto

Configuración en Mac/Linux

  1. Usar Smithery (recomendado) Agregar en ~/.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\"}'"
      ]
    }
  }
}
  1. Modo de servicio local Agregar en ~/.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",
      }
    }
  }
}

Notas de configuración para Mac/Linux:

  • -c: ejecutar la cadena de comandos
  • Usar && para conectar múltiples comandos
  • Las rutas usan barra diagonal /
  • Las variables de entorno se pueden configurar en el archivo .env del proyecto
  • El directorio principal del usuario en Mac suele estar en /Users/your-username/
  • El directorio principal del usuario en Linux suele estar en /home/your-username/

Modo de desarrollo

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

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

Comando de compilación

# 仅构建项目
npm run build

# 清理构建目录
npm run clean

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

Herramientas de depuración

# 基本调试模式
npm run inspector

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

Guía de uso de herramientas MCP

🚀 Optimización de la arquitectura de herramientas

Este servicio ha completado la optimización de la arquitectura de herramientas, reorganizadas según funcionalidad y frecuencia de uso:

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

🔧 Lista de herramientas MCP

1. Herramientas de información básica - las funciones de consulta más utilizadas

getSpace - obtener información del espacio

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

getPageByPrettyUrl - obtener página con precisión según el título

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

2. Herramientas de gestión de páginas - funcionalidad principal

managePages - gestión unificada de páginas ⭐️ Optimización por consolidación

Crear página:

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

Actualizar página:

{
  "name": "managePages",
  "arguments": {
    "action": "update",
    "pageId": "123456789",
    "title": "更新的标题",
    "content": "<p>更新的内容</p>",
    "version": 2,
    "representation": "storage"
  }
}

Eliminar página: ⭐️ Nueva funcionalidad

{
  "name": "managePages",
  "arguments": {
    "action": "delete",
    "pageId": "123456789"
  }
}

Obtener información básica de la página:

{
  "name": "managePages",
  "arguments": {
    "action": "get",
    "pageId": "123456789"
  }
}

Obtener contenido detallado de la página:

{
  "name": "managePages",
  "arguments": {
    "action": "getContent",
    "pageId": "123456789",
    "expand": "body.storage,version,space"
  }
}

3. Herramientas de gestión de comentarios - funcionalidad extendida

manageComments - gestión unificada de comentarios ⭐️ Optimización por consolidación

Crear comentario normal (formato HTML):

{
  "name": "manageComments",
  "arguments": {
    "action": "create",
    "commentType": "regular",
    "pageId": "123456789",
    "content": "这是一条普通评论",
    "representation": "storage"
  }
}

Crear comentario normal (formato Markdown): 🆕

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

Crear comentario en línea:

{
  "name": "manageComments",
  "arguments": {
    "action": "create",
    "commentType": "inline",
    "pageId": "123456789",
    "content": "这里需要注意性能问题",
    "originalSelection": "QueryHoldingsService.setHoldingData()",
    "matchIndex": 0,
    "numMatches": 1
  }
}

Actualizar comentario:

{
  "name": "manageComments",
  "arguments": {
    "action": "update",
    "commentType": "regular",
    "commentId": "98765432",
    "content": "更新后的评论内容",
    "version": 2
  }
}

Eliminar comentario:

{
  "name": "manageComments",
  "arguments": {
    "action": "delete",
    "commentType": "regular",
    "commentId": "98765432"
  }
}

Responder a comentario normal:

{
  "name": "manageComments",
  "arguments": {
    "action": "reply",
    "commentType": "regular",
    "pageId": "123456789",
    "parentCommentId": "98765432",
    "content": "这是一条回复",
    "watch": false
  }
}

Responder a comentario en línea:

{
  "name": "manageComments",
  "arguments": {
    "action": "reply",
    "commentType": "inline",
    "commentId": "98765432",
    "pageId": "123456789",
    "content": "这是对行内评论的回复"
  }
}

getPageComments - obtener todos los comentarios de una página

{
  "name": "getPageComments",
  "arguments": {
    "pageId": "123456789",
    "start": 0,
    "limit": 25
  }
}

getComment - obtener detalles de un comentario individual

{
  "name": "getComment",
  "arguments": {
    "commentId": "98765432"
  }
}

4. Herramientas de búsqueda - funciones de búsqueda especializadas

searchContent - búsqueda de contenido de páginas (compatible con CQL)

{
  "name": "searchContent",
  "arguments": {
    "query": "API 开发"
  }
}

searchComments - búsqueda de contenido de comentarios

{
  "name": "searchComments",
  "arguments": {
    "query": "性能优化",
    "spaceKey": "DEV",
    "start": 0,
    "limit": 25
  }
}

📝 Descripción de parámetros

Opciones del parámetro action:

  • Gestión de páginas: create, update, delete, get, getContent
  • Gestión de comentarios: create, update, delete, reply

Opciones del parámetro commentType:

  • regular (predeterminado): comentario normal
  • inline: comentario en línea

Opciones del parámetro representation:

  • storage (recomendado): formato de almacenamiento HTML
  • wiki: sintaxis de marcado Wiki
  • editor2: formato de editor
  • view: formato de vista
  • markdown 🆕: formato Markdown (conversión automática a HTML)

🎯 Puntos destacados de la optimización

✅ Optimización de cantidad de herramientas: de 12 herramientas consolidadas a 8 (reducción del 33%)
✅ Diseño de API unificado: distingue tipos de operación mediante el parámetro action
✅ Validación inteligente de parámetros: valida automáticamente los parámetros requeridos según el tipo de operación
✅ Comentarios completos de parámetros: se pueden ver las descripciones detalladas de los parámetros en MCP Inspector
✅ Nueva funcionalidad de eliminación: soporte para operaciones de eliminación de páginas
✅ Doble tipo de comentario: gestión unificada de comentarios normales y en línea

🚀 Nueva funcionalidad: Exportación Markdown

Resumen de la funcionalidad de exportación

Ahora puedes exportar páginas de Confluence como archivos Markdown al espacio de trabajo actual.

🎯 Métodos de exportación compatibles

  1. Exportación de página individual (exportPage)

    • Exporta la página especificada como archivo Markdown
    • Compatible con división de documentos grandes por secciones
    • Metadatos YAML frontmatter opcionales

  2. Exportación de estructura jerárquica (exportPageHierarchy)

    • Exporta recursivamente la página y todas sus subpáginas
    • Mantiene la estructura jerárquica de directorios original
    • Profundidad de recursión controlable

  3. Exportación por lotes (batchExportPages)

    • Exporta múltiples páginas específicas simultáneamente
    • Control inteligente de concurrencia y manejo de errores
    • Optimización de rendimiento y seguimiento de progreso

🌟 Características principales

  • ✅ Conversión inteligente de contenido: conversión de alta calidad de HTML a Markdown
  • ✅ División por secciones: división automática de documentos grandes según el nivel de encabezado
  • ✅ Preservación de metadatos: información completa de la página como YAML frontmatter
  • ✅ Gestión de archivos: nomenclatura inteligente de archivos y manejo de conflictos
  • ✅ Optimización de rendimiento: control de concurrencia, mecanismo de reintentos, optimización de memoria
  • ✅ Seguimiento de progreso: estado de exportación en tiempo real e informes de errores

📖 Inicio rápido

# 导出单个页面
{
  "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
}

📁 Ejemplo de salida

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

Para la guía de uso detallada, consulta: Guía de funcionalidad de exportación

Recomendaciones de seguridad

  1. Prioriza el uso del método de autenticación con Access Token, ya que es más seguro
  2. Rota periódicamente el Access Token
  3. No codifiques información de autenticación directamente en el código
  4. Asegúrate de que el archivo .env se haya agregado al .gitignore
  5. En entornos de producción, usa variables de entorno o un sistema seguro de gestión de configuración
  6. Si se configuran ambos métodos de autenticación, el sistema priorizará el Access Token

Notas importantes

  1. Solo se puede elegir uno de los métodos de autenticación: Access Token o nombre de usuario y contraseña
  2. Si se configuran ambos métodos de autenticación, el sistema priorizará el Access Token
  3. Asegúrate de que la URL configurada sea la dirección correcta de la API de Confluence
  4. En entornos de producción, se recomienda usar HTTPS

Optimización de rendimiento

  1. Optimización de conexiones

    • Habilitar HTTP Keep-Alive
    • Limitar el número máximo de conexiones concurrentes
    • Controlar el número de conexiones inactivas

  2. Optimización de solicitudes

    • Compresión de respuestas
    • Control de tiempo de espera
    • Limitación de redirecciones

  3. Manejo de errores

    • Mecanismo de reintento automático
    • Información de errores detallada
    • Estadísticas de tiempo de solicitudes

Guía de depuración

Salida de registros

El servicio utiliza salida de registros estructurados, que incluye la siguiente información:

{
  "jsonrpc": "2.0",
  "method": "log",
  "params": {
    "level": "info",
    "message": "请求信息",
    "timestamp": "2024-04-16T12:00:44.000Z"
  }
}

Manejo de errores

Formato de respuesta de error:

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

Resumen de herramientas

🎯 Agrupación de herramientas tras la optimización de arquitectura

Después de la optimización de arquitectura, las herramientas se reorganizaron según la frecuencia de uso y la lógica de agrupación:

📁 1. Herramientas de información básica (las más utilizadas)

  • getSpace - obtener información del espacio
  • getPageByPrettyUrl - obtener página con precisión según el título

📁 2. Herramientas de gestión de páginas (funcionalidad principal)

  • managePages ⭐️ - gestión unificada de páginas (create/update/delete/get/getContent)

📁 3. Herramientas de gestión de comentarios (funcionalidad extendida)

  • manageComments ⭐️ - gestión unificada de comentarios (create/update/delete/reply, compatible con comentarios normales + en línea)
  • getPageComments - obtener todos los comentarios de una página
  • getComment - obtener detalles de un comentario individual

📁 4. Herramientas de búsqueda (búsqueda especializada)

  • searchContent - búsqueda de contenido de páginas (compatible con sintaxis CQL)
  • searchComments - búsqueda de contenido de comentarios

📊 Resultados de la optimización

  • Cantidad de herramientas: de 12 optimizadas a 8 (reducción del 33%)
  • API unificado: consolidación de funciones similares, distinguiendo operaciones mediante el parámetro action
  • Funcionalidad mejorada: nueva eliminación de páginas, comentarios de parámetros completados
  • Experiencia mejorada: ordenadas por frecuencia de uso, mayor eficiencia de búsqueda

Documentación

Contribuciones

Se aceptan Issues y Pull Requests.

Licencia

Licencia MIT

Configuración

Configuración de variables de entorno

Crea el archivo .env en el directorio raíz del proyecto y configura los siguientes parámetros:

# 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

Descripción de la configuración de estrategia de comentarios

La funcionalidad de comentarios admite tres estrategias de implementación de API, configurables mediante la variable de entorno COMMENT_API_STRATEGY:

1. standard (predeterminada, recomendada)

  • Usa la API REST estándar
  • Buena compatibilidad, adecuada para Confluence 7.4+
  • Alta estabilidad, adecuada para entornos de producción

2. tinymce

  • Usa el endpoint de TinyMCE
  • Funcionalidad más rica, simula el comportamiento del navegador
  • Compatible con funciones de comentarios más complejas

3. auto

  • Selección automática de estrategia
  • Prioriza el uso de TinyMCE, con respaldo a la API estándar en caso de fallo
  • Equilibra funcionalidad y compatibilidad

Otras configuraciones de comentarios

  • COMMENT_ENABLE_FALLBACK: si se habilita el mecanismo de respaldo (predeterminado: true)

    • true: cuando falla la API preferida, intenta automáticamente la API de respaldo
    • false: usar solo la API especificada, lanzando error directamente en caso de fallo

  • COMMENT_TIMEOUT: tiempo de espera de solicitudes de comentarios, en milisegundos (predeterminado: 15000)

    • Se recomienda de 10 a 15 segundos para la API estándar
    • Para la API de TinyMCE, se recomienda de 15 a 20 segundos debido a pasos como la obtención de tokens

Notas especiales para Confluence 7.4

  • La API estándar es más estable en la versión 7.4
  • La API de TinyMCE ofrece funcionalidad más rica, pero puede tener problemas de compatibilidad
  • Se recomienda usar la estrategia standard en entornos de producción; en entornos de desarrollo, se puede elegir según sea necesario

Despliegue en un repositorio npm privado

Referencia de inicio de sesión en el repositorio: [PRIVATE_DOCUMENTATION_URL]

# 登录并部署
npm login --registry=[PRIVATE_REGISTRY]
npm publish @[ORGANIZATION]/mcp-server-confluence-ts

Instalación con Claude CLI (recomendado)

``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",
      }
    }
  }
}