Atlassian Confluence

Interaja com espaços, páginas e conteúdo do Atlassian Confluence Cloud em tempo real.

GitHub
62
Experimente este MCPPatrocinado

Documentação

Conecte a IA à Sua Base de Conhecimento do Confluence

Transforme a forma como você acessa e interage com o conhecimento da sua equipe conectando o Claude, o Cursor AI e outros assistentes de IA diretamente aos seus espaços, páginas e documentação do Confluence. Obtenha respostas instantâneas da sua base de conhecimento, pesquise em todos os seus espaços e otimize seu fluxo de trabalho de documentação.

NPM Version

O Que Você Pode Fazer

  • Pergunte à IA sobre sua documentação: "Qual é o nosso processo de autenticação de API?"
  • Pesquise em todos os espaços: "Encontre todas as páginas sobre boas práticas de segurança"
  • Obtenha respostas instantâneas: "Mostre-me as notas de versão mais recentes do espaço Produto"
  • Acesse o conhecimento da equipe: "Quais são nossas políticas de RH para trabalho remoto?"
  • Revise comentários de páginas: "Mostre-me a discussão no documento de arquitetura"
  • Crie e atualize conteúdo: "Crie uma nova página no espaço DEV"

Perfeito Para

  • Desenvolvedores que precisam de acesso rápido à documentação técnica e guias de API
  • Gerentes de Produto que buscam requisitos, especificações e atualizações de projetos
  • Equipes de RH que acessam documentos de políticas e recursos para funcionários rapidamente
  • Equipes de Suporte que encontram guias de solução de problemas e artigos da base de conhecimento
  • Qualquer pessoa que queira interagir com o Confluence usando linguagem natural

Início Rápido

Comece a usar em 2 minutos:

1. Obtenha Suas Credenciais do Confluence

Gere um Token de API do Confluence:

  1. Acesse Tokens de API da Atlassian
  2. Clique em Criar token de API
  3. Dê a ele um nome como "Assistente de IA"
  4. Copie o token gerado imediatamente (você não o verá novamente!)

2. Experimente Instantaneamente

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

Conecte-se a Assistentes de IA

Para Usuários do Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Reinicie o Claude Desktop e você verá o servidor confluence na barra de status.

Para Outros Assistentes de IA

A maioria dos assistentes de IA suporta MCP (Cursor AI, Continue.dev e outros). Instale o servidor globalmente:

npm install -g @aashari/mcp-server-atlassian-confluence

Em seguida, configure seu assistente de IA para usar o servidor MCP com transporte STDIO. O binário está disponível como mcp-atlassian-confluence após a instalação global.

Alternativa: Arquivo de Configuração

Crie ~/.mcp/configs.json para configuração em todo o sistema:

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

Chaves de configuração alternativas: O sistema também aceita "atlassian-confluence", "@aashari/mcp-server-atlassian-confluence" ou "mcp-server-atlassian-confluence" em vez de "confluence".

Usando Variáveis de Ambiente

Você também pode configurar credenciais usando variáveis de ambiente ou um arquivo .env:

# Create a .env file in your project directory
cat > .env << EOF
ATLASSIAN_SITE_NAME=your-company
ATLASSIAN_USER_EMAIL=your.email@company.com
ATLASSIAN_API_TOKEN=your_api_token
DEBUG=false
EOF

O servidor carregará automaticamente esses valores de:

  1. Variáveis de ambiente
  2. Arquivo .env no diretório atual
  3. ~/.mcp/configs.json (como mostrado acima)

Ferramentas Disponíveis

Este servidor MCP fornece 5 ferramentas genéricas que podem acessar qualquer endpoint da API do Confluence:

FerramentaDescrição
conf_getGET em qualquer endpoint da API do Confluence (ler dados)
conf_postPOST em qualquer endpoint (criar recursos)
conf_putPUT em qualquer endpoint (substituir recursos)
conf_patchPATCH em qualquer endpoint (atualizações parciais)
conf_deleteDELETE em qualquer endpoint (remover recursos)

Parâmetros das Ferramentas

Todas as ferramentas compartilham estes parâmetros comuns:

  • path (obrigatório): O caminho do endpoint da API (ex.: /wiki/api/v2/spaces)
  • queryParams (opcional): Parâmetros de consulta como pares chave-valor (ex.: {"limit": "25", "space-id": "123"})
  • jq (opcional): Expressão JMESPath para filtrar/transformar a resposta (ex.: results[*].{id: id, title: title})
  • outputFormat (opcional): Formato de saída - "toon" (padrão, 30-60% menos tokens) ou "json"

Ferramentas que aceitam corpo de requisição (conf_post, conf_put, conf_patch):

  • body (obrigatório): Corpo da requisição como objeto JSON

Caminhos de API Comuns

Espaços:

  • /wiki/api/v2/spaces - Listar todos os espaços
  • /wiki/api/v2/spaces/{id} - Obter detalhes do espaço

Páginas:

  • /wiki/api/v2/pages - Listar páginas (use o parâmetro de consulta space-id para filtrar)
  • /wiki/api/v2/pages/{id} - Obter detalhes da página
  • /wiki/api/v2/pages/{id}/body - Obter corpo da página (use o parâmetro body-format)
  • /wiki/api/v2/pages/{id}/children - Obter páginas filhas
  • /wiki/api/v2/pages/{id}/labels - Obter rótulos da página

Comentários:

  • /wiki/api/v2/pages/{id}/footer-comments - Listar/adicionar comentários de rodapé
  • /wiki/api/v2/pages/{id}/inline-comments - Listar/adicionar comentários inline
  • /wiki/api/v2/footer-comments/{comment-id} - Obter/atualizar/excluir comentário

Postagens de Blog:

  • /wiki/api/v2/blogposts - Listar postagens de blog
  • /wiki/api/v2/blogposts/{id} - Obter postagem de blog

Pesquisa:

  • /wiki/rest/api/search - Pesquisar conteúdo (use o parâmetro de consulta cql)

Formato de Saída TOON

O que é TOON? TOON (Token-Oriented Object Notation) é um formato otimizado para eficiência de tokens em LLMs, reduzindo custos de tokens em 30-60% em comparação com JSON. É o formato de saída padrão para todas as ferramentas.

Benefícios:

  • Arrays tabulares usam menos tokens que arrays JSON
  • Sobrecarga mínima de sintaxe (sem aspas, colchetes ou vírgulas desnecessárias)
  • Ainda legível por humanos e analisável

Quando usar JSON em vez disso:

  • Quando você precisa de JSON padrão para outras ferramentas
  • Ao depurar ou inspecionar manualmente

Exemplo de comparação:

// JSON format (verbose)
{"results": [{"id": "123", "title": "My Page"}, {"id": "456", "title": "Other Page"}]}

// TOON format (efficient)
results:
  - id: 123
    title: My Page
  - id: 456
    title: Other Page

Para usar JSON em vez de TOON, defina outputFormat: "json" na sua requisição.

Filtragem JMESPath

Todas as ferramentas suportam filtragem opcional JMESPath (jq) para extrair dados específicos e reduzir custos de tokens:

# Get just space names and keys
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --jq "results[].{id: id, key: key, name: name}"

# Get page title and status
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/123456" \
  --jq "{id: id, title: title, status: status}"

IMPORTANTE: Sempre use o parâmetro jq para filtrar respostas apenas para os campos necessários. Respostas não filtradas podem ser muito grandes e caras em custos de tokens.

Referência de Sintaxe JMESPath:

  • Documentação oficial: jmespath.org
  • Padrões comuns:
    • results[*] - Todos os itens no array de resultados
    • results[0] - Apenas o primeiro item
    • results[*].id - Apenas IDs de todos os itens
    • results[*].{id: id, title: title} - Criar objetos com campos selecionados
    • results[?status=='current'] - Filtrar por condição

Exemplos do Mundo Real

Explore Sua Base de Conhecimento

Pergunte ao seu assistente de IA:

  • "Liste todos os espaços no nosso Confluence"
  • "Mostre-me detalhes sobre o espaço de Engenharia"
  • "Quais páginas estão no nosso espaço de Produto?"
  • "Encontre as páginas mais recentes no espaço de Marketing"

Pesquise e Encontre Informações

Pergunte ao seu assistente de IA:

  • "Pesquise páginas sobre autenticação de API"
  • "Encontre toda a documentação com 'segurança' no título"
  • "Mostre-me páginas rotuladas com 'primeiros-passos'"
  • "Pesquise conteúdo no espaço DEV sobre implantação"

Acesse Conteúdo Específico

Pergunte ao seu assistente de IA:

  • "Obtenha o conteúdo da página Guia de Autenticação de API"
  • "Mostre-me o documento de checklist de integração"
  • "O que há na nossa página de políticas de segurança?"
  • "Exiba as notas de versão mais recentes"

Crie e Atualize Conteúdo

Pergunte ao seu assistente de IA:

  • "Crie uma nova página no espaço DEV intitulada 'Guia de API'"
  • "Adicione um comentário ao documento de arquitetura"
  • "Atualize o conteúdo da página com as novas informações de versão"

Comandos CLI

A CLI espelha as ferramentas MCP para acesso direto pelo terminal. Todos os comandos suportam os mesmos parâmetros das ferramentas.

Comandos Disponíveis

  • get - GET em qualquer endpoint do Confluence
  • post - POST em qualquer endpoint
  • put - PUT em qualquer endpoint
  • patch - PATCH em qualquer endpoint
  • delete - DELETE em qualquer endpoint

Parâmetros da CLI

Todos os comandos:

  • -p, --path <path> (obrigatório) - Caminho do endpoint da API
  • -q, --query-params <json> (opcional) - Parâmetros de consulta como JSON
  • --jq <expression> (opcional) - Expressão de filtro JMESPath
  • -o, --output-format <format> (opcional) - Formato de saída: toon (padrão) ou json

Comandos com corpo (post, put, patch):

  • -b, --body <json> (obrigatório) - Corpo da requisição como JSON

Exemplos

# GET request
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# GET with query parameters and JMESPath filter
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages" \
  --query-params '{"space-id": "123456", "limit": "10"}' \
  --jq "results[*].{id: id, title: title}"

# GET with JSON output format
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --output-format json

# POST request (create a page)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages" \
  --body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "<p>Content here</p>"}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages/789/footer-comments" \
  --body '{"body": {"representation": "storage", "value": "<p>My comment</p>"}}'

# PUT request (update page - requires version increment)
npx -y @aashari/mcp-server-atlassian-confluence put \
  --path "/wiki/api/v2/pages/789" \
  --body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "<p>Updated content</p>"}, "version": {"number": 2}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-confluence patch \
  --path "/wiki/api/v2/spaces/123456" \
  --body '{"name": "New Space Name"}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-confluence delete \
  --path "/wiki/api/v2/pages/789"

Tratamento de Respostas

Truncamento de Respostas Grandes

Quando as respostas da API excedem aproximadamente 40.000 caracteres (~10.000 tokens), o servidor trunca automaticamente a resposta para permanecer dentro dos limites de tokens. Quando isso acontece:

  1. Você verá um aviso de truncamento no final da resposta mostrando:

    • Quanto da resposta original é exibido
    • O tamanho original da resposta
    • Orientação sobre como acessar os dados completos

  2. A resposta bruta completa é salva em um arquivo temporário em /tmp/mcp/ (caminho fornecido no aviso de truncamento)

  3. Boas práticas para evitar truncamento:

    • Sempre use o parâmetro jq para filtrar respostas apenas para os campos necessários
    • Use o parâmetro de consulta limit para restringir contagens de resultados (ex.: {"limit": "5"})
    • Solicite recursos específicos por ID em vez de listar tudo
    • Use consultas CQL direcionadas para pesquisas

Exemplo de filtragem eficiente:

# Instead of getting all space data (can be huge):
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces"

# Get only the fields you need:
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --query-params '{"limit": "10"}' \
  --jq "results[*].{id: id, key: key, name: name}"

Registro de Depuração

Ative o registro de depuração para ver informações detalhadas de requisição/resposta:

# Set DEBUG environment variable
export DEBUG=true

# For MCP mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence

# For CLI mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

Os registros de depuração são gravados em: ~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log

Testes e Desenvolvimento

Usando o MCP Inspector

O MCP Inspector fornece uma interface visual para testar ferramentas:

# Install the server globally
npm install -g @aashari/mcp-server-atlassian-confluence

# Run with MCP Inspector
npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)

Ou use o comando de desenvolvimento integrado se você clonou o repositório:

npm run mcp:inspect

Isso inicia o servidor em modo HTTP e abre a interface do inspector no seu navegador.

Modo HTTP para Testes

Você pode executar o servidor em modo HTTP para testar com curl ou outros clientes HTTP:

# Start server in HTTP mode
TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

O servidor escutará em http://localhost:3000/mcp por padrão. Você pode alterar a porta:

PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

Testando com curl:

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'

A resposta vem como Server-Sent Events (SSE) com formato:

event: message
data: {"jsonrpc": "2.0", "id": 1, "result": {...}}

Solução de Problemas

"Falha na autenticação" ou "403 Proibido"

  1. Verifique as permissões do seu Token de API:

  2. Verifique o formato do nome do seu site:

    • Se sua URL do Confluence é https://mycompany.atlassian.net
    • Seu nome de site deve ser apenas mycompany

  3. Teste suas credenciais:

    npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"

"Recurso não encontrado" ou "404"

  1. Verifique o caminho da API:

    • Caminhos diferenciam maiúsculas de minúsculas
    • Use IDs numéricos para espaços e páginas (não chaves)
    • Verifique se o recurso existe no seu navegador

  2. Verifique as permissões de acesso:

    • Certifique-se de ter acesso ao espaço/página no seu navegador
    • Alguns conteúdos podem ser restritos a determinados usuários

"Nenhum resultado encontrado" ao pesquisar

  1. Tente termos de pesquisa diferentes:

    • Use sintaxe CQL para pesquisas avançadas
    • Tente critérios de pesquisa mais amplos

  2. Verifique a sintaxe CQL:

    • Valide seu CQL na pesquisa avançada do Confluence primeiro

Problemas de Integração com o Claude Desktop

  1. Reinicie o Claude Desktop após atualizar o arquivo de configuração
  2. Verifique o local do arquivo de configuração:
    • macOS: ~/.claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

Obtendo Ajuda

Se você ainda estiver com problemas:

  1. Execute um comando de teste simples para verificar se tudo funciona
  2. Verifique as Issues no GitHub para problemas semelhantes
  3. Crie uma nova issue com sua mensagem de erro e detalhes da configuração

Perguntas Frequentes

Quais permissões eu preciso?

Sua conta Atlassian precisa de:

  • Acesso ao Confluence com as permissões apropriadas para os espaços que você deseja consultar
  • Token de API com permissões apropriadas (concedido automaticamente quando você cria um)

Posso usar isso com o Confluence Server (on-premise)?

Atualmente, esta ferramenta suporta apenas Confluence Cloud. O suporte para Confluence Server/Data Center pode ser adicionado em versões futuras.

Como encontro meu nome de site?

Seu nome de site é a primeira parte da sua URL do Confluence:

  • URL: https://mycompany.atlassian.net -> Nome do site: mycompany
  • URL: https://acme-corp.atlassian.net -> Nome do site: acme-corp

Com quais assistentes de IA isso funciona?

Qualquer assistente de IA que suporte o Model Context Protocol (MCP):

  • Claude Desktop
  • Cursor AI
  • Continue.dev
  • Muitos outros

Meus dados estão seguros?

Sim! Esta ferramenta:

  • Executa inteiramente na sua máquina local
  • Usa suas próprias credenciais do Confluence
  • Nunca envia seus dados a terceiros
  • Acessa apenas o que você dá permissão para acessar

Posso pesquisar em todos os meus espaços de uma vez?

Sim! Use consultas CQL para pesquisas entre espaços. Por exemplo:

npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND text~\"API documentation\""}'

Migração da v2.x

A versão 3.0 substitui 8+ ferramentas específicas por 5 ferramentas genéricas de método HTTP. Se você está atualizando da v2.x:

Antes (v2.x):

conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,
conf_search, conf_ls_comments, conf_add_comment, ...

Depois (v3.0):

conf_get, conf_post, conf_put, conf_patch, conf_delete

Exemplos de migração:

  • conf_ls_spaces -> conf_get com caminho /wiki/api/v2/spaces
  • conf_get_space -> conf_get com caminho /wiki/api/v2/spaces/{id}
  • conf_ls_pages -> conf_get com caminho /wiki/api/v2/pages?space-id={id}
  • conf_get_page -> conf_get com caminho /wiki/api/v2/pages/{id}
  • conf_search -> conf_get com caminho /wiki/rest/api/search?cql=...
  • conf_add_comment -> conf_post com caminho /wiki/api/v2/pages/{id}/footer-comments

Detalhes Técnicos

Requisitos

  • Node.js: 18.0.0 ou superior
  • MCP SDK: 1.23.0 (usa a API moderna registerTool)
  • Confluence: Somente Cloud (Server/Data Center não suportados)

Arquitetura

Este servidor segue uma arquitetura de 5 camadas:

  1. Camada de Ferramentas (src/tools/) - Definições de ferramentas MCP com validação Zod
  2. Camada CLI (src/cli/) - CLI baseada em Commander para testes diretos
  3. Camada de Controladores (src/controllers/) - Lógica de negócio, filtragem JMESPath, formatação de saída
  4. Camada de Serviços (src/services/) - Comunicação com a API do Confluence
  5. Camada de Utilitários (src/utils/) - Utilitários compartilhados (logger, config, formatadores, codificador TOON)

Recursos

  • Ferramentas genéricas de método HTTP - Acesse qualquer endpoint da API do Confluence
  • Formato de saída TOON - Redução de 30-60% de tokens em comparação com JSON
  • Filtragem JMESPath - Extraia apenas os dados necessários
  • Truncamento de respostas - Tratamento automático de respostas grandes
  • Registro de respostas brutas - Respostas completas salvas em /tmp/mcp/
  • Transporte duplo - STDIO (para Claude Desktop) e HTTP (para integrações web)
  • Registro de depuração - Logs abrangentes para solução de problemas

Histórico de Versões

v3.2.1 (Atual)

  • Adiciona registro de respostas brutas com truncamento para respostas grandes da API
  • Melhora a compatibilidade de dependências

v3.2.0

  • Moderniza o MCP SDK para v1.23.0 com a API registerTool

v3.1.0

  • Adiciona o formato de saída TOON para respostas eficientes em tokens para LLMs

v3.0.0 (Mudança significativa)

  • Substitui 8+ ferramentas específicas de domínio por 5 ferramentas genéricas de método HTTP
  • Adiciona suporte a filtragem JMESPath
  • Acesso completo à API do Confluence via métodos genéricos

Consulte CHANGELOG.md para o histórico completo de versões.

Suporte

Precisa de ajuda? Veja como obter assistência:

  1. Consulte a seção de solução de problemas acima - os problemas mais comuns estão cobertos lá
  2. Visite nosso repositório no GitHub para documentação e exemplos: github.com/aashari/mcp-server-atlassian-confluence
  3. Reporte problemas em GitHub Issues
  4. Inicie uma discussão para solicitações de recursos ou perguntas gerais

Feito com carinho para equipes que desejam trazer IA para seu fluxo de trabalho de gestão do conhecimento.