mcp-confluence-context

MCP server que expõe páginas do Confluence como contexto no Claude Code. Busque documentação de ferramentas, padrões e guias diretamente no prompt — sem copiar e colar.

Suporta múltiplos tenants (organizações Confluence distintas) rodando como instâncias independentes.

Como funciona

1. Você pede ao Claude para buscar uma página ou pesquisar por um termo
2. O servidor consulta o Confluence via REST API (com cache local)
3. O conteúdo da página é injetado como contexto no prompt
4. O Claude usa esse conteúdo para guiar a implementação

---

Pré-requisitos

• Node.js 20+
• Claude Code CLI instalado
• Acesso ao Confluence da sua empresa

---

Instalação — tenant único

Se você usa apenas uma organização Confluence, execute o setup uma vez:

macOS / Linux

./setup.sh

Windows (PowerShell)

.\setup.ps1

No Windows, caso o PowerShell bloqueie a execução de scripts, rode antes:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

O script vai solicitar:

Campo	Descrição
Nome do tenant	Identificador curto, ex: bradesco
CONFLUENCE_PAT	Personal Access Token do Confluence (veja como gerar abaixo)
CONFLUENCE_BASE_URL	URL da instância, ex: https://confluence.empresa.com.br
CONFLUENCE_SPACE_KEY	Chave do espaço padrão para filtrar buscas (ex: DEV). Opcional.
CACHE_TTL_SECONDS	Tempo de cache em segundos (padrão: 3600)

Após o setup, reinicie o Claude Code.

---

Instalação — múltiplos tenants (duas organizações)

Execute o setup uma vez para cada organização. Cada execução registra uma instância MCP independente no Claude Code.

1. Primeiro tenant

./setup.sh

Quando solicitado:

Nome do tenant: bradesco
CONFLUENCE_PAT: <seu token do Bradesco>
CONFLUENCE_BASE_URL: https://confluence.bradesco.com.br
CONFLUENCE_SPACE_KEY: DEV

Isso cria:

• .env.bradesco com as credenciais
• Entrada mcp-confluence-bradesco no ~/.claude.json

2. Segundo tenant

Execute o script novamente:

./setup.sh

Quando solicitado:

Nome do tenant: bradescoseguros
CONFLUENCE_PAT: <seu token do Bradesco Seguros>
CONFLUENCE_BASE_URL: https://confluence.bradescoseguros.com.br
CONFLUENCE_SPACE_KEY: SEG

Isso cria:

• .env.bradescoseguros com as credenciais
• Entrada mcp-confluence-bradescoseguros no ~/.claude.json

3. Reinicie o Claude Code

Após registrar os dois tenants, reinicie o Claude Code. O resultado no ~/.claude.json será:

{
  "mcpServers": {
    "mcp-confluence-bradesco": {
      "command": "node",
      "args": ["/caminho/para/dist/index.js"],
      "env": { "DOTENV_CONFIG_PATH": "/caminho/para/.env.bradesco" }
    },
    "mcp-confluence-bradescoseguros": {
      "command": "node",
      "args": ["/caminho/para/dist/index.js"],
      "env": { "DOTENV_CONFIG_PATH": "/caminho/para/.env.bradescoseguros" }
    }
  }
}

4. Usando os dois tenants no Claude Code

As tools ficam disponíveis com o prefixo do servidor. Basta mencionar de qual organização quer a informação:

# Buscar no Confluence do Bradesco
usando o servidor mcp-confluence-bradesco, pesquise por "autenticação OAuth"

# Buscar no Confluence do Bradesco Seguros
usando o servidor mcp-confluence-bradescoseguros, traga a página 191667649

---

Como gerar o Personal Access Token no Confluence

1. Acesse o Confluence e faça login
2. Clique na sua foto de perfil (canto superior direito) → Perfil
3. No menu lateral, clique em Configurações
4. Clique em Tokens de acesso pessoal
5. Clique em Criar token
6. Defina um nome (ex: mcp-confluence-context) e uma data de expiração
7. Clique em Criar e copie o token gerado — ele só é exibido uma vez

Se a opção não aparecer, solicite ao administrador do Confluence que habilite tokens de acesso pessoal.

---

Como encontrar o ID de uma página

Abra a página no Confluence e localize o ID na URL:

• https://confluence.empresa.com.br/pages/viewpage.action?pageId=191667649
• Ou: clique em ... (reticências) → Informações da página → o ID aparece na URL

---

Tools disponíveis

get_page

Busca o conteúdo completo de uma página pelo ID.

traga o conteúdo da página 191667649 e use como referência para criar o schema Zod

search_pages

Pesquisa páginas por texto. Use para descobrir o ID quando não souber.

pesquise no Confluence por "autenticação OAuth" e me mostre as páginas disponíveis

list_children

Lista as páginas filhas de uma página pai. Útil para navegar hierarquias de documentação.

liste as subpáginas da página 191667649

update_page

Salva o conteúdo de uma página como rascunho sem publicar. Requer o conteúdo em Confluence Storage Format. Após salvar, retorna a URL do rascunho para que você revise e publique manualmente no Confluence.

atualize a página 191667649 com o título "Guia de Auth" e o seguinte conteúdo em storage format: <p>Novo conteúdo</p>

O cache da página é invalidado automaticamente após a edição.

---

Exemplos de uso

# Buscar documentação e usar para implementar
busque no Confluence a documentação sobre "integração com o gateway de pagamentos"
e use o conteúdo para implementar o client em src/payments/gateway.ts

# Navegar a hierarquia antes de buscar
liste as subpáginas de 191667649, depois traga o conteúdo da que fala sobre autenticação

# Fornecer o ID diretamente quando já souber
use a página 191667649 do Confluence como referência e implemente o fluxo descrito
em src/auth/login.ts

---

Cache

O conteúdo das páginas é armazenado em ~/.mcp-confluence-context/page-{id}.json com TTL configurável (padrão 1h). Em caso de falha na conexão com o Confluence, o servidor utiliza automaticamente o cache expirado como fallback.

---

Estrutura do projeto

mcp-confluence-context/
├── src/
│   ├── index.ts              # Entrypoint do MCP server (4 tools)
│   ├── types.ts              # Tipos compartilhados
│   ├── confluence/
│   │   └── client.ts         # fetchPage, searchPages, listChildren, updatePageAsDraft
│   └── cache/
│       └── manager.ts        # Cache por pageId com TTL
├── setup.sh                  # Script de instalação — macOS/Linux
├── setup.ps1                 # Script de instalação — Windows (PowerShell)
└── .env.example              # Template de variáveis de ambiente

Os arquivos .env.<tenant> são criados pelo script de setup e não devem ser versionados.

---

Desenvolvimento

npm install
npm run build   # compila TypeScript
npm test        # roda os testes