kahbernardo/mcp-confluence

🚀 MCP Confluence

Model Context Protocol (MCP) Server para integração completa com o Confluence da Atlassian

📖 Sobre o Projeto

Este é um servidor MCP (Model Context Protocol) que permite integração direta entre o Cursor IDE e o Confluence. Com ele, você pode gerenciar páginas, espaços e conteúdo do Confluence diretamente através de comandos naturais no Cursor.

🎯 Por que usar?

• 🔗 Integração Nativa com o Cursor IDE
• 📝 Gerenciamento Completo de páginas do Confluence
• 🔍 Busca Inteligente de conteúdo
• 🚀 Automação de tarefas de documentação
• 💬 Comandos Naturais em português
• 🔒 Segurança com autenticação via API Token

🛠️ Tecnologias Utilizadas

• TypeScript - Linguagem principal
• Node.js - Runtime JavaScript
• MCP SDK - Protocolo de comunicação
• Axios - Cliente HTTP para API do Confluence
• Confluence REST API - Integração com Atlassian

🚀 Funcionalidades

📋 Ferramentas Disponíveis

💡 Exemplos de Comandos Naturais

# Listar espaços
"Liste todos os espaços disponíveis no Confluence"

# Buscar páginas
"Busque páginas sobre documentação de APIs"

# Criar página
"Crie uma nova página sobre onboarding de desenvolvedores"

# Pesquisar conteúdo
"Pesquise páginas que mencionem Docker ou Kubernetes"

# Atualizar página
"Atualize a página de documentação com as novas informações"

⚡ Instalação Rápida

📋 Pré-requisitos

• Node.js (versão 18 ou superior)
• npm ou yarn
• Acesso ao Confluence
• Token de API do Confluence

🚀 Instalação

1. Clone o repositório

git clone https://github.com/SEU_USERNAME/mcp-confluence.git
cd mcp-confluence

2. Instale as dependências

npm install

3. Configure as variáveis de ambiente

cp env.example .env

4. Edite o arquivo .env

CONFLUENCE_DOMAIN=https://your-domain.atlassian.net
CONFLUENCE_API_TOKEN=SEU_TOKEN_AQUI
CONFLUENCE_EMAIL=seu-email@your-domain.com

5. Compile o projeto

npm run build

🔑 Como obter o Token de API

1. Acesse Atlassian Account Settings
2. Clique em "Create API token"
3. Dê um nome ao token (ex: "MCP Confluence")
4. Copie o token gerado
5. Cole no arquivo .env

🔧 Configuração no Cursor

📝 Passo a Passo

1. Abra as configurações do Cursor

   • Mac: Cmd + ,
   • Windows/Linux: Ctrl + ,

2. Localize as configurações MCP

   • Na barra de pesquisa, digite "MCP" ou "Model Context Protocol"
   • Procure por uma seção chamada "MCP Servers"

3. Adicione a configuração

   {
     "mcpServers": {
       "confluence": {
         "command": "node",
         "args": ["/caminho/completo/para/mcp-confluence/dist/index.js"],
         "env": {
           "CONFLUENCE_DOMAIN": "https://your-domain.atlassian.net",
           "CONFLUENCE_API_TOKEN": "SEU_TOKEN_AQUI",
           "CONFLUENCE_EMAIL": "seu-email@your-domain.com"
         }
       }
     }
   }
   

4. Substitua os valores

   • /caminho/completo/para/mcp-confluence → Caminho real do projeto
   • SEU_TOKEN_AQUI → Seu token de API
   • seu-email@your-domain.com → Seu email real

5. Reinicie o Cursor

   • Feche e abra o Cursor para aplicar as configurações

🎯 Exemplo de Configuração Completa

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/caminho/completo/para/mcp-confluence/dist/index.js"],
      "env": {
        "CONFLUENCE_DOMAIN": "https://your-domain.atlassian.net",
        "CONFLUENCE_API_TOKEN": "SEU_TOKEN_AQUI",
        "CONFLUENCE_EMAIL": "seu-email@your-domain.com"
      }
    }
  }
}

🎯 Como Usar

💬 Comandos Naturais

Após a configuração, você pode usar comandos naturais em português:

# Gerenciar espaços
"Liste todos os espaços do Confluence"
"Mostre os espaços disponíveis"

# Buscar e visualizar páginas
"Busque páginas sobre documentação"
"Mostre a página de onboarding"
"Pesquise páginas que mencionem Docker"

# Criar e editar conteúdo
"Crie uma nova página sobre APIs REST"
"Atualize a documentação de deploy"
"Adicione informações sobre Kubernetes"

# Gerenciar conteúdo
"Delete a página de teste"
"Mostre o conteúdo da página X"
"Busque páginas do espaço DEV"

🎮 Exemplos Práticos

🔍 Dicas de Uso

• Use comandos específicos para melhores resultados
• Mencione o espaço quando quiser filtrar resultados
• Seja descritivo ao criar ou atualizar páginas
• Use palavras-chave relevantes nas pesquisas

🛠️ Desenvolvimento

📦 Scripts Disponíveis

# Desenvolvimento
npm run dev          # Executa em modo desenvolvimento
npm run watch        # Executa com hot reload

# Build
npm run build        # Compila o projeto
npm start           # Executa o build compilado

# Instalação
npm install         # Instala dependências

🔧 Estrutura do Projeto

mcp-confluence/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── confluence-client.ts  # Cliente para API do Confluence
│   └── types.ts              # Definições de tipos TypeScript
├── dist/                     # Código compilado (gerado)
├── package.json             # Dependências e scripts
├── tsconfig.json           # Configuração TypeScript
├── .env                    # Variáveis de ambiente (local)
├── env.example            # Exemplo de configuração
└── README.md              # Documentação

🧪 Testando Localmente

# Compilar e executar
npm run build
node dist/index.js

# Ou em modo desenvolvimento
npm run dev

🔌 API do Confluence

Este MCP utiliza a API REST do Confluence para fornecer todas as funcionalidades:

📡 Endpoints Utilizados

• GET /rest/api/space - Listar espaços
• GET /rest/api/content - Buscar páginas
• GET /rest/api/content/{id} - Buscar página específica
• GET /rest/api/content/search - Pesquisar conteúdo
• POST /rest/api/content - Criar página
• PUT /rest/api/content/{id} - Atualizar página
• DELETE /rest/api/content/{id} - Deletar página

🔐 Autenticação

• Método: Basic Authentication
• Username: Email corporativo
• Password: Token de API do Atlassian
• Segurança: HTTPS obrigatório

🔒 Segurança

🛡️ Medidas de Segurança

• ✅ Token da API armazenado em variáveis de ambiente
• ✅ Arquivo .env protegido pelo .gitignore
• ✅ HTTPS obrigatório para todas as comunicações
• ✅ Permissões mínimas recomendadas para tokens
• ✅ Autenticação segura via Basic Auth

⚠️ Boas Práticas

• 🔐 Nunca commite o arquivo .env no repositório
• 🔑 Use tokens específicos para este projeto
• 🗑️ Revogue tokens não utilizados
• 📧 Use email corporativo da sua organização
• 🔄 Atualize tokens regularmente

🚨 Importante

Nunca compartilhe ou exponha seu token de API publicamente!

🤝 Suporte e Contribuição

📞 Precisa de Ajuda?

• 📖 Documentação: API REST do Confluence
• 🐛 Issues: Abra uma issue no repositório
• 💬 Discussões: Use as discussões do GitHub
• 📧 Contato: seu-email@your-domain.com

🛠️ Problemas Comuns

🚀 Contribuindo

1. Fork o repositório
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

📋 Roadmap

• Suporte a anexos
• Histórico de versões
• Templates de páginas
• Integração com Jira
• Interface web

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo para detalhes.