Confluence to Markdown MCP Server

Servidor para busca híbrida em conteúdo do Confluence salvo e indexado localmente em clientes de IA.

Documentação

`confluence2md-mcp` - Servidor MCP para Índices `confluence2md`

Servidor MCP que expõe a busca do confluence2md-indexer a qualquer cliente de IA compatível com MCP. Executa como um servidor stdio local, consulta um índice SQLite construído a partir de exportações do confluence2md e retorna resultados ranqueados com metadados de pontuação.

Parte da Plataforma `confluence2md`

confluence2md-mcp é o terceiro passo em um pipeline local de conhecimento do Confluence com três ferramentas. Ele encapsula um índice SQLite construído pelo confluence2md-indexer (que indexa a saída do confluence2md) e o serve a clientes de IA via MCP. Consulte docs/platform.md para a arquitetura completa.

Requisitos

Um índice SQLite construído pelo confluence2md-indexer v0.5.0 ou mais recente
O conteúdo de origem deve usar o formato de metadados confluence2md — outros formatos não são suportados

Variáveis de Ambiente

Variável	Obrigatória	Descrição
`CONFLUENCE_INDEX_DB`	recomendada	Caminho para o arquivo de banco de dados SQLite. Usa `confluence2md-index.db` no diretório de trabalho atual como fallback se não definida.
`CONFLUENCE2MD_EMBEDDING_PROVIDER`	opcional	`bow-local` (padrão: local, offline, sem chave de API), `openai` ou `openai-compatible`.
`CONFLUENCE2MD_EMBEDDING_MODEL`	opcional	ID do modelo, por exemplo `text-embedding-3-small`.
`CONFLUENCE2MD_EMBEDDING_DIM`	opcional	Dimensão do vetor, como `1024`. Parte da identidade de incorporação.
`CONFLUENCE2MD_EMBEDDING_BASE_URL`	opcional	Endpoint para um provedor `openai-compatible`.
`CONFLUENCE2MD_EMBEDDING_API_KEY_ENV`	opcional	Nome da variável que contém a chave de API (preferível a uma chave literal).
`CONFLUENCE2MD_EMBEDDING_API_KEY`	opcional	Chave de API literal.
`CONFLUENCE2MD_EMBEDDING_SKIP`	opcional	`true` desativa o canal vetorial e mantém apenas a busca lexical.

As variáveis CONFLUENCE2MD_EMBEDDING_* restantes do indexador também são respeitadas — AUTH_HEADER, AUTH_SCHEME, HEADERS, QUERY_PARAMS, DOCUMENT_PREFIX, QUERY_PREFIX, BATCH_SIZE, TIMEOUT, MAX_RETRIES — consulte o docs/embedding-providers.md do indexador.

O índice e a consulta devem concordar sobre a configuração de incorporação. Um índice registra a identidade dos vetores que contém (provider:variant@dimension, por exemplo bow-local:fnv1a@256), enquanto uma consulta híbrida ou vetorial resolve sua própria identidade a partir dessas variáveis. Quando as duas diferem, a consulta falha com embedding mismatch: ... em vez de retornar resultados fracos; o erro da ferramenta nomeia ambas as identidades e como corrigir. Use mode: "lexical" para buscar sem incorporações.

Este servidor lê apenas variáveis de ambiente. A CLI do indexador também aceita um config.yaml; se você indexou por meio de um arquivo de configuração, exporte as variáveis CONFLUENCE2MD_EMBEDDING_* equivalentes aqui para que ambos os lados resolvam o mesmo provedor.

Atualizando um Índice

Este servidor vincula confluence2md-indexer v0.5.0, que lê colunas de metadados de documentos que índices construídos por versões anteriores do indexador não possuem. Esses índices não são migrados no local, então reconstrua uma vez após a atualização:

confluence2md-indexer index ./output --rebuild

Consultar um índice construído por um indexador mais antigo falha com um erro de banco de dados; reconstruir é a correção suportada.

Instalação

Baixe o binário para sua plataforma em Releases e coloque-o em algum lugar do seu PATH.

VS Code

Crie ou edite .vscode/mcp.json no seu workspace:

{
  "servers": {
    "confluence2md": {
      "type": "stdio",
      "command": "confluence2md-mcp",
      "args": [],
      "env": {
        "CONFLUENCE_INDEX_DB": "/path/to/confluence2md-index.db"
      }
    }
  }
}

MCP: Add Server na Paleta de Comandos também funciona.

Claude Code

claude mcp add confluence2md \
  confluence2md-mcp \
  -e CONFLUENCE_INDEX_DB=/path/to/confluence2md-index.db

Nota sobre WSL: Use o binário Linux, não o .exe do Windows — o .exe não herda variáveis de ambiente do WSL. O caminho do banco de dados deve ser um caminho Linux nativo (por exemplo, /home/user/confluence2md-index.db), não /mnt/c/, para evitar problemas de bloqueio do SQLite em montagens NTFS.

Codex CLI

Adicione a ~/.codex/config.json:

{
  "mcpServers": {
    "confluence2md": {
      "command": "confluence2md-mcp",
      "args": [],
      "env": {
        "CONFLUENCE_INDEX_DB": "/path/to/confluence2md-index.db"
      }
    }
  }
}

Ferramentas

`confluence.search`

Busca conteúdo do Confluence indexado em um banco de dados SQLite local.

Argumento	Obrigatório	Descrição
`query`	✓	Texto da consulta de busca
`dbPath`		Substitui o caminho do banco de dados. Usa a variável de ambiente `CONFLUENCE_INDEX_DB` como fallback e depois `confluence2md-index.db` no diretório de trabalho atual.
`mode`		`hybrid` (padrão) \| `lexical` \| `vector`
`fusion`		`weighted` (padrão) \| `rrf`
`alpha`		Alfa de fusão ponderada `[0..1]`, padrão `0.70`
`rrfK`		Constante k do RRF, padrão `60`
`topK`		Candidatos a ranquear, padrão `10`
`limit`		Máximo de resultados a retornar
`offset`		Deslocamento de resultados
`candidateK`		Candidatos por canal de recuperação, padrão `50`
`expand`		Contagem de blocos para expansão de contexto
`spaceKey`		Filtrar por chave de espaço
`pageId`		Filtrar por ID de página
`fromDate`		Limite inferior `YYYY-MM-DD`
`toDate`		Limite superior `YYYY-MM-DD`
`spaces`		Filtrar por qualquer uma de várias chaves de espaço; prevalece sobre `spaceKey`
`host`		Filtrar por host do site rastreado
`author`		Nome do criador ou último modificador, sem diferenciar maiúsculas de minúsculas
`createdBy`		Apenas nome do criador
`modifiedBy`		Apenas nome do último modificador
`depthMin` / `depthMax`		Limites de profundidade de rastreamento; `depthMin: 1` exclui páginas iniciais
`seedOnly`		Apenas as páginas de onde o rastreamento começou
`hasAttachments`		Apenas páginas com pelo menos um anexo
`updatedSince`		Modificado dentro de uma idade (`30d`, `2w`, `12h`) ou após uma data absoluta (`2026-01-01`)
`embeddingProvider`		Substitui o provedor para esta chamada: `bow-local` \| `openai` \| `openai-compatible`
`embeddingModel`		Substitui o modelo de incorporação
`embeddingDim`		Substitui a dimensão de incorporação
`embeddingBaseURL`		Substitui o endpoint de incorporação
`embeddingApiKeyEnv`		Nome da variável de ambiente que contém a chave de API
`embeddingAuthHeader` / `embeddingAuthScheme`		Substitui o cabeçalho e o esquema de autenticação
`embeddingSkip`		Desativa o canal vetorial para esta chamada
`embeddingDocumentPrefix` / `embeddingQueryPrefix`		Prefixos de texto para modelos assimétricos

Os filtros de metadados se aplicam igualmente à recuperação lexical, vetorial e híbrida. Argumentos prevalecem sobre variáveis de ambiente: o indexador preenche apenas os campos de incorporação que os argumentos deixam sem definição, então embeddingModel substitui CONFLUENCE2MD_EMBEDDING_MODEL para essa chamada. Uma chave de API literal deliberadamente não é um argumento — ela viajaria pela conversa do cliente e pelo log do servidor — então defina CONFLUENCE2MD_EMBEDDING_API_KEY ou nomeie outra variável com embeddingApiKeyEnv.

Campos de resposta:

Campo	Descrição
`schemaVersion`	String de versão do esquema para estabilidade de contrato
`tool`	Sempre `"confluence.search"`
`dbPath`	Caminho do banco de dados resolvido usado para a consulta
`request`	Parâmetros de solicitação ecoados
`count`	Número de resultados retornados nesta resposta
`total`	Total de resultados ranqueados antes da paginação
`results`	Matriz de objetos de resultado com texto do bloco e detalhamento de pontuação

Falhas são retornadas como erros de ferramenta que mantêm a mensagem do indexador e adicionam a correção quando a causa é acionável: uma incompatibilidade de incorporação nomeia ambas as identidades, um índice ausente ou sem vetores nomeia o comando de reconstrução, e um canal vetorial desativado aponta para CONFLUENCE2MD_EMBEDDING_SKIP. mode: "lexical" funciona sem qualquer configuração de incorporação.

`confluence.list_spaces`

Lista as chaves de espaço do Confluence que o índice contém, para que um cliente possa delimitar uma busca sem conhecer as chaves antecipadamente.

Argumento	Obrigatório	Descrição
`dbPath`		Substitui o caminho do banco de dados. Usa `CONFLUENCE_INDEX_DB` como fallback e depois `confluence2md-index.db` no diretório de trabalho atual.

Campos de resposta: schemaVersion, tool, dbPath, count e spaces — uma matriz ordenada de strings de chave de espaço, vazia quando o índice não contém espaços.

Desenvolvimento

Compilação

# Linux / macOS / WSL
go build -o bin/confluence2md-mcp .

# Windows
go build -o bin/confluence2md-mcp.exe .

# Cross-compile Linux binary from Windows
GOOS=linux GOARCH=amd64 go build -o bin/confluence2md-mcp-linux-amd64 .

Se o download de módulos falhar com 403, defina GOPROXY=direct.

Teste

go test ./... -run TestMCPStdioSmoke -v

A suíte também contém um teste de ponta a ponta offline: instala o indexador fixado (go install ...@v0.5.0), constrói um índice a partir de um corpus temporário com o provedor bow-local padrão e aciona o servidor via stdio — verificando a lista de ferramentas, a lista de espaços, uma busca delimitada por espaço e o erro de incompatibilidade de provedor. Não precisa de chave de API ou serviço em execução, e é ignorado apenas quando a CLI do indexador não pode ser instalada.

Versão

Compilações de lançamento carimbam o binário via ldflags; a versão é relatada na resposta initialize do MCP e gravada no log de inicialização. Um go build sem carimbo relata dev.

Solução de Problemas

Sem resultados: verifique se CONFLUENCE_INDEX_DB aponta para um índice construído que contém as tabelas chunks_fts e embeddings.
WSL + binário Windows: use o binário Linux com um caminho de banco de dados Linux nativo — consulte a nota sobre WSL acima.
Ferramentas não aparecendo no chat: reinicie seu cliente MCP após o registro.