Confluence

✨ Características

🚀 Novedades en v0.3.0 - Arquitectura optimizada

• 9 herramientas estratégicas de MCP - Optimizadas desde 8 herramientas con capacidades mejoradas de flujo de trabajo
• Arquitectura basada en dominios - Separación clara en 3 dominios: Espacios, Páginas y Búsqueda
• Navegación mejorada - Nuevas herramientas para búsqueda de espacios, jerarquía de páginas y descubrimiento de contenido
• Rendimiento mejorado - 1871 pruebas superadas con un proceso de compilación optimizado

📚 Accede a Confluence directamente desde tu editor

• Explora tus espacios de Confluence sin salir de tu IDE
• Obtén información detallada de páginas con contenido formateado
• Navega por jerarquías de páginas con descubrimiento de páginas hijas
• Crea, actualiza y gestiona contenido de Confluence directamente

🔍 Potentes capacidades de búsqueda

• Busca páginas mediante consultas de texto o CQL avanzado (Confluence Query Language)
• Soporte para filtrado por espacio, filtrado por tipo de contenido y ordenación de resultados
• Formato Markdown enriquecido con vistas previas de páginas y enlaces directos
• Se renombró confluence_search_pages a confluence_search para simplificar

📝 Procesamiento inteligente de contenido

• Conversión automática del formato de almacenamiento de Confluence a Markdown legible
• Soporte para texto formateado, tablas, macros y archivos adjuntos
• Operaciones CRUD completas para la gestión de páginas
• Herramientas estratégicas de flujo de trabajo para una mejor experiencia de usuario

🚀 Inicio rápido

Instalación

La forma más sencilla de usar este servidor MCP es instalarlo directamente con npm/bunx. ¡No requiere configuración local!

Para Claude Desktop

Añade esta configuración a los ajustes de MCP de Claude Desktop:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Para Cursor IDE

Añade esta configuración a los ajustes de MCP de Cursor IDE:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Para cualquier cliente MCP

Usa este patrón de configuración para cualquier cliente compatible con MCP:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

🔑 Cómo obtener tu token de API de Confluence

1. Ve a Tokens de API de Atlassian
2. Haz clic en "Create API token"
3. Asígnale un nombre (por ejemplo, "MCP Confluence")
4. Copia el token y úsalo en tu configuración
5. Importante: Usa el token exactamente como se proporciona (no se necesitan comillas en la sección de entorno)

Alternativa: usar npx en lugar de bunx

Si prefieres npx en lugar de bunx, también puedes usar:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "npx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Probar tu configuración

Después de añadir la configuración:

1. Reinicia tu cliente MCP (Claude Desktop, Cursor, etc.)
2. Prueba este comando para verificar la conexión:

   Show me my Confluence spaces.
   

¡Eso es todo! Ya estás listo para usar Confluence directamente desde tu cliente MCP.

🛠️ Configuración de desarrollo

# Clone the repository
git clone https://github.com/Dsazz/mcp-confluence.git
cd mcp-confluence

# Install dependencies
bun install

# Build the project
bun run build

# Set up environment variables
cp .env.example .env
# Edit .env with your Confluence credentials

CONFLUENCE_HOST_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token
NODE_ENV=development

# Format code
bun format

# Check code for issues
bun check

# Type check
bun typecheck

# Run the inspector (no separate build step needed)
bun run inspect

🧰 Herramientas disponibles

🌟 Herramientas estratégicas de flujo de trabajo

Parámetros de espacio

La herramienta confluence_get_spaces admite estos parámetros:

Opciones básicas:

• type: String ("global" o "personal", opcional) - Filtrar por tipo de espacio
• limit: Number (1-100, predeterminado: 25) - Número máximo de espacios a devolver
• start: Number (predeterminado: 0) - Desplazamiento de paginación para conjuntos de resultados grandes

Ejemplos:

# Basic usage - get all accessible spaces
confluence_get_spaces

# Get only global spaces
confluence_get_spaces type:"global" limit:10

# Pagination example
confluence_get_spaces start:25 limit:25

Parámetros de página

La herramienta confluence_get_page admite estos parámetros:

Obligatorios:

• pageId: String - El ID de la página a recuperar

Opciones de contenido:

• includeContent: Boolean (predeterminado: true) - Incluir el contenido completo de la página
• includeComments: Boolean (predeterminado: false) - Incluir el número de comentarios
• expand: String (opcional) - Campos adicionales a expandir (separados por comas)

Ejemplos:

# Basic usage with content
confluence_get_page 12345

# Get page without content
confluence_get_page 12345 includeContent:false

# Get page with comments and extra data
confluence_get_page 12345 includeComments:true expand:"version,space"

Parámetros de búsqueda

La herramienta confluence_search admite tanto búsqueda simple como avanzada:

Búsqueda básica:

• query: String - Consulta de búsqueda por texto (busca en títulos y contenido)
• spaceKey: String (opcional) - Limitar la búsqueda a un espacio específico
• type: String ("page" o "blogpost", opcional) - Filtro por tipo de contenido

Búsqueda avanzada (CQL):

• query: String - Consulta CQL completa para búsquedas avanzadas
• Ejemplos: text~"specific phrase", type=page AND space.key="DEV"

Opciones de resultados:

• limit: Number (1-100, predeterminado: 25) - Número máximo de resultados
• start: Number (predeterminado: 0) - Desplazamiento de paginación
• orderBy: String ("relevance", "created", "modified", "title") - Orden de clasificación

Ejemplos:

# Simple text search
confluence_search query:"project documentation"

# Search in specific space
confluence_search query:"API guide" spaceKey:"DEV"

# Advanced CQL search
confluence_search query:'text~"user guide" AND type=page'

# Search with custom ordering
confluence_search query:"meeting notes" orderBy:"modified" limit:10

Parámetros de gestión de páginas

Creación de páginas (confluence_create_page):

• spaceId: String - El ID del espacio donde se creará la página
• title: String - El título de la nueva página
• content: String - El contenido de la página (admite el formato de almacenamiento de Confluence)
• parentPageId: String (opcional) - El ID de la página principal
• status: String ("current" o "draft", predeterminado: "current") - Estado de la página

Actualización de páginas (confluence_update_page):

• pageId: String - El ID de la página a actualizar
• title: String (opcional) - Nuevo título para la página
• content: String (opcional) - Nuevo contenido para la página
• versionNumber: Number - Número de versión actual de la página
• versionMessage: String (opcional) - Mensaje que describe los cambios

Ejemplos:

# Create a new page
confluence_create_page spaceId:"123456" title:"New Documentation" content:"<p>Initial content</p>"

# Update an existing page
confluence_update_page pageId:"789012" title:"Updated Title" content:"<p>Updated content</p>" versionNumber:2

# Get child pages for navigation
confluence_get_child_pages pageId:"123456" limit:10

📁 Estructura del proyecto (v0.3.0 - Arquitectura optimizada)

 src/
  ├── core/                    # Core functionality and configurations
  │   ├── errors/              # Error handling utilities
  │   ├── logging/             # Logging infrastructure
  │   ├── responses/           # Response formatting
  │   ├── server/              # MCP server setup
  │   ├── tools/               # Base tool patterns
  │   └── utils/               # General utilities
  ├── features/                # Feature implementations
  │   └── confluence/          # Confluence integration
  │       ├── client/          # HTTP client infrastructure
  │       │   ├── config/      # Client configuration
  │       │   ├── errors/      # Client-specific errors
  │       │   ├── http/        # HTTP client implementations
  │       │   │   ├── utils/   # HTTP utilities
  │       │   │   ├── v1/      # V1 API client (search)
  │       │   │   └── v2/      # V2 API client (CRUD)
  │       │   └── responses/   # Response models
  │       ├── domains/         # Domain-based architecture (NEW)
  │       │   ├── spaces/      # Space management domain
  │       │   │   ├── handlers/     # Space operation handlers
  │       │   │   ├── models/       # Space data models
  │       │   │   ├── use-cases/    # Space business logic
  │       │   │   ├── validators/   # Space validation
  │       │   │   └── formatters/   # Space response formatting
  │       │   ├── pages/       # Page management domain
  │       │   │   ├── handlers/     # Page operation handlers
  │       │   │   ├── models/       # Page data models
  │       │   │   ├── use-cases/    # Page business logic
  │       │   │   ├── validators/   # Page validation
  │       │   │   └── formatters/   # Page response formatting
  │       │   └── search/      # Search domain
  │       │       ├── handlers/     # Search operation handlers
  │       │       ├── models/       # Search data models
  │       │       ├── use-cases/    # Search business logic
  │       │       ├── validators/   # Search validation
  │       │       └── formatters/   # Search response formatting
  │       ├── shared/          # Shared utilities across domains
  │       │   ├── formatters/  # Common formatters
  │       │   └── validators/  # Common validators
  │       └── tools/           # MCP tool orchestration
  │           ├── handlers.ts  # Unified tool handlers
  │           ├── mcp.ts       # MCP tool definitions
  │           └── routing.ts   # Tool routing logic
  └── test/                    # Test suite (1871 tests)
      ├── integration/         # Integration tests
      ├── unit/               # Unit tests (domain-organized)
      │   ├── core/           # Core functionality tests
      │   └── features/       # Feature tests (by domain)
      │       └── confluence/
      │           └── domains/ # Domain-specific tests
      │               ├── spaces/   # Space domain tests
      │               ├── pages/    # Page domain tests
      │               └── search/   # Search domain tests
      └── utils/              # Test utilities

Resumen de la arquitectura

El servidor MCP de Confluence utiliza una arquitectura de doble cliente para una gestión óptima de las versiones de API:

• Cliente V1 (http-client-v1.impl.ts): Gestiona las operaciones de búsqueda y las consultas CQL
• Cliente V2 (http-client-v2.impl.ts): Gestiona las operaciones CRUD de espacios y páginas
• Enrutador de operaciones (operation.router.ts): Enruta las solicitudes de forma inteligente a la versión de API adecuada
• Patrón Factory (http-client.factory.ts): Proporciona una inyección de dependencias limpia para los clientes

Esta arquitectura garantiza:

• Rendimiento óptimo: Cada operación utiliza la versión de API más adecuada
• Compatibilidad futura: Fácil añadir nuevas versiones de API o retirar las antiguas
• Separación limpia: Límites claros entre las diferentes capacidades de la API
• Seguridad de tipos: Soporte completo de TypeScript en todas las implementaciones de clientes

Scripts de NPM

🔧 Solución de problemas

Problemas de instalación de NPM

Paquete no encontrado

Si recibes un error de "paquete no encontrado":

# Make sure you're using the correct scoped package name
bunx @dsazz/mcp-confluence@latest

# Or try with explicit npm registry
npm install -g @dsazz/mcp-confluence --registry https://registry.npmjs.org

Variables de entorno no encontradas

Si el servidor no se inicia con errores de variables de entorno:

1. Para uso con bunx: Crea un archivo .env en tu directorio de trabajo:

   # Create .env file in your current directory
   echo "CONFLUENCE_HOST_URL=https://your-domain.atlassian.net" > .env
   echo "CONFLUENCE_USER_EMAIL=your-email@example.com" >> .env
   echo "CONFLUENCE_API_TOKEN=your-api-token" >> .env
   

2. Para la configuración de MCP: Establece las variables de entorno en tu configuración de MCP:

   {
     "mcpServers": {
       "Confluence Tools": {
         "command": "bunx",
         "args": ["-y", "@dsazz/mcp-confluence@latest"],
         "env": {
           "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
           "CONFLUENCE_USER_EMAIL": "your-email@example.com",
           "CONFLUENCE_API_TOKEN": "your-api-token"
         }
       }
     }
   }
   

Problemas de conexión con la API

Credenciales no válidas

• Verifica que tu token de API de Confluence sea correcto
• Asegúrate de que tu correo electrónico coincida con tu cuenta de Atlassian
• Comprueba que la URL de tu Confluence sea correcta (incluye https://)

Problemas de red/firewall

• Asegúrate de que tu red permita conexiones a tu instancia de Confluence
• Comprueba si tu organización requiere acceso VPN
• Verifica que la configuración del firewall permita conexiones HTTPS salientes

Problemas de desarrollo

Errores de compilación

# Clear dependencies and reinstall
rm -rf node_modules bun.lockb
bun install

# Clean build
rm -rf dist
bun run build

Errores de TypeScript

# Run type checking
bun run typecheck

# Check for linting issues
bun run check

📝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de contribución para obtener detalles sobre:

• Flujo de trabajo de desarrollo
• Estrategia de ramas
• Formato de mensajes de commit
• Proceso de pull request
• Directrices de estilo de código

📘 Recursos

• Documentación del Model Context Protocol
• SDK de TypeScript de MCP
• Especificación de MCP
• MCP Inspector
• API REST de Confluence

📄 Licencia

MIT © Stanislav Stepanenko