Confluence

✨ Recursos

🚀 Novo na v0.3.0 - Arquitetura Otimizada

• 9 Ferramentas MCP Estratégicas - Otimizadas a partir de 8 ferramentas com capacidades de workflow aprimoradas
• Arquitetura Baseada em Domínios - Separação clara em 3 domínios: Espaços, Páginas e Busca
• Navegação Aprimorada - Novas ferramentas para consulta de espaços, hierarquia de páginas e descoberta de conteúdo
• Performance Melhorada - 1871 testes passando com processo de build otimizado

📚 Acesse o Confluence Diretamente do Seu Editor

• Navegue pelos espaços do Confluence sem sair do seu IDE
• Obtenha informações detalhadas de páginas com conteúdo formatado
• Navegue pelas hierarquias de páginas com descoberta de páginas filhas
• Crie, atualize e gerencie conteúdo do Confluence diretamente

🔍 Recursos Poderosos de Busca

• Busque páginas usando consultas de texto ou CQL avançado (Confluence Query Language)
• Suporte para filtragem por espaço, filtragem por tipo de conteúdo e ordenação de resultados
• Formatação markdown rica com pré-visualizações de páginas e links diretos
• confluence_search_pages renomeado para confluence_search para simplificar

📝 Processamento Inteligente de Conteúdo

• Conversão automática do formato de armazenamento do Confluence para markdown legível
• Suporte para texto formatado, tabelas, macros e anexos
• Operações CRUD completas para gerenciamento de páginas
• Ferramentas estratégicas de workflow para melhor experiência do usuário

🚀 Início Rápido

Instalação

A maneira mais fácil de usar este servidor MCP é instalá-lo diretamente via npm/bunx. Nenhuma configuração local é necessária!

Para Claude Desktop

Adicione esta configuração às configurações MCP do seu 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

Adicione esta configuração às configurações MCP do seu 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 Qualquer Cliente MCP

Use este padrão de configuração para qualquer cliente compatível com 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"
      }
    }
  }
}

🔑 Obtendo Seu Token de API do Confluence

1. Acesse Tokens de API do Atlassian
2. Clique em "Create API token"
3. Dê um nome a ele (ex.: "MCP Confluence")
4. Copie o token e use-o na sua configuração
5. Importante: Use o token exatamente como fornecido (sem aspas na seção de variáveis de ambiente)

Alternativa: Usando npx em vez de bunx

Se você preferir npx em vez de bunx, também pode 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"
      }
    }
  }
}

Testando Sua Configuração

Após adicionar a configuração:

1. Reinicie seu cliente MCP (Claude Desktop, Cursor, etc.)
2. Tente este comando para testar a conexão:

   Show me my Confluence spaces.
   

Pronto! Você está pronto para usar o Confluence diretamente do seu cliente MCP.

🛠️ Configuração de Desenvolvimento

# 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

🧰 Ferramentas Disponíveis

🌟 Ferramentas Estratégicas de Workflow

Parâmetros de Espaço

A ferramenta confluence_get_spaces suporta estes parâmetros:

Opções Básicas:

• type: String ("global" ou "personal", opcional) - Filtrar por tipo de espaço
• limit: Número (1-100, padrão: 25) - Número máximo de espaços a retornar
• start: Número (padrão: 0) - Offset de paginação para grandes conjuntos de resultados

Exemplos:

# 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

A ferramenta confluence_get_page suporta estes parâmetros:

Obrigatórios:

• pageId: String - O ID da página a ser recuperada

Opções de Conteúdo:

• includeContent: Booleano (padrão: true) - Incluir conteúdo completo da página
• includeComments: Booleano (padrão: false) - Incluir contagem de comentários
• expand: String (opcional) - Campos adicionais para expandir (separados por vírgula)

Exemplos:

# 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 Busca

A ferramenta confluence_search suporta busca simples e avançada:

Busca Básica:

• query: String - Consulta de busca por texto (pesquisa títulos e conteúdo)
• spaceKey: String (opcional) - Limitar busca a um espaço específico
• type: String ("page" ou "blogpost", opcional) - Filtro por tipo de conteúdo

Busca Avançada (CQL):

• query: String - Consulta CQL completa para buscas avançadas
• Exemplos: text~"specific phrase", type=page AND space.key="DEV"

Opções de Resultado:

• limit: Número (1-100, padrão: 25) - Número máximo de resultados
• start: Número (padrão: 0) - Offset de paginação
• orderBy: String ("relevance", "created", "modified", "title") - Ordem de classificação

Exemplos:

# 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 Gerenciamento de Páginas

Criação de Página (confluence_create_page):

• spaceId: String - O ID do espaço onde a página será criada
• title: String - O título da nova página
• content: String - O conteúdo da página (suporta o formato de armazenamento do Confluence)
• parentPageId: String (opcional) - O ID da página pai
• status: String ("current" ou "draft", padrão: "current") - Status da página

Atualização de Página (confluence_update_page):

• pageId: String - O ID da página a ser atualizada
• title: String (opcional) - Novo título para a página
• content: String (opcional) - Novo conteúdo para a página
• versionNumber: Número - Número da versão atual da página
• versionMessage: String (opcional) - Mensagem descrevendo as alterações

Exemplos:

# 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

📁 Estrutura do Projeto (v0.3.0 - Arquitetura Otimizada)

 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

Visão Geral da Arquitetura

O Confluence MCP Server usa uma arquitetura de cliente duplo para gerenciamento otimizado de versões de API:

• Cliente V1 (http-client-v1.impl.ts): Lida com operações de busca e consultas CQL
• Cliente V2 (http-client-v2.impl.ts): Gerencia operações CRUD para espaços e páginas
• Roteador de Operações (operation.router.ts): Roteia inteligentemente as solicitações para a versão de API apropriada
• Padrão Factory (http-client.factory.ts): Fornece injeção de dependência limpa para os clientes

Esta arquitetura garante:

• Performance Ótima: Cada operação usa a versão de API mais adequada
• Compatibilidade Futura: Fácil adicionar novas versões de API ou descontinuar as antigas
• Separação Limpa: Limites claros entre diferentes capacidades de API
• Segurança de Tipos: Suporte completo a TypeScript em todas as implementações de clientes

Scripts NPM

🔧 Solução de Problemas

Problemas de Instalação via NPM

Pacote Não Encontrado

Se você receber um erro de "package not found":

# 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

Variáveis de Ambiente Não Encontradas

Se o servidor falhar ao iniciar com erros de variáveis de ambiente:

1. Para uso com bunx: Crie um arquivo .env no seu diretório de trabalho:

   # 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 configuração MCP: Defina variáveis de ambiente na sua configuração 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 Conexão com a API

Credenciais Inválidas

• Verifique se o seu token de API do Confluence está correto
• Certifique-se de que seu email corresponde à sua conta Atlassian
• Verifique se a URL do seu Confluence está correta (inclua https://)

Problemas de Rede/Firewall

• Certifique-se de que sua rede permite conexões à sua instância do Confluence
• Verifique se sua organização exige acesso via VPN
• Verifique se as configurações do firewall permitem conexões HTTPS de saída

Problemas de Desenvolvimento

Falhas de Compilação

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

# Clean build
rm -rf dist
bun run build

Erros de TypeScript

# Run type checking
bun run typecheck

# Check for linting issues
bun run check

📝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes sobre:

• Fluxo de trabalho de desenvolvimento
• Estratégia de branches
• Formato de mensagens de commit
• Processo de pull request
• Diretrizes de estilo de código

📘 Recursos

• Documentação do Model Context Protocol
• MCP TypeScript SDK
• Especificação MCP
• MCP Inspector
• API REST do Confluence

📄 Licença

MIT © Stanislav Stepanenko