Confluence to Markdown MCP Server

Servidor para búsqueda híbrida sobre contenido de Confluence guardado e indexado localmente en clientes de IA.

Documentación

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

Servidor MCP que expone la búsqueda de confluence2md-indexer a cualquier cliente de IA compatible con MCP. Se ejecuta como un servidor stdio local, consulta un índice SQLite construido a partir de exportaciones de confluence2md y devuelve resultados clasificados con metadatos de puntuación.

Parte de la Plataforma `confluence2md`

confluence2md-mcp es el tercer paso en un pipeline local de conocimiento de Confluence de tres herramientas. Envuelve un índice SQLite construido por confluence2md-indexer (que indexa la salida de confluence2md) y lo sirve a clientes de IA a través de MCP. Consulta docs/platform.md para ver la arquitectura completa.

Requisitos

Un índice SQLite construido por confluence2md-indexer v0.5.0 o posterior
El contenido fuente debe usar el formato de metadatos confluence2md — no se admiten otros formatos

Variables de Entorno

Variable	Requerida	Descripción
`CONFLUENCE_INDEX_DB`	recomendada	Ruta al archivo de base de datos SQLite. Si no se establece, recurre a `confluence2md-index.db` en el directorio de trabajo actual.
`CONFLUENCE2MD_EMBEDDING_PROVIDER`	opcional	`bow-local` (predeterminado: local, sin conexión, sin clave API), `openai` o `openai-compatible`.
`CONFLUENCE2MD_EMBEDDING_MODEL`	opcional	Identificador del modelo, por ejemplo `text-embedding-3-small`.
`CONFLUENCE2MD_EMBEDDING_DIM`	opcional	Dimensión del vector, como `1024`. Parte de la identidad de incrustación.
`CONFLUENCE2MD_EMBEDDING_BASE_URL`	opcional	Endpoint para un proveedor de `openai-compatible`.
`CONFLUENCE2MD_EMBEDDING_API_KEY_ENV`	opcional	Nombre de la variable que contiene la clave API (preferido sobre una clave literal).
`CONFLUENCE2MD_EMBEDDING_API_KEY`	opcional	Clave API literal.
`CONFLUENCE2MD_EMBEDDING_SKIP`	opcional	`true` desactiva el canal vectorial y deja la búsqueda léxica.

Las variables CONFLUENCE2MD_EMBEDDING_* restantes del indexador también se respetan — AUTH_HEADER, AUTH_SCHEME, HEADERS, QUERY_PARAMS, DOCUMENT_PREFIX, QUERY_PREFIX, BATCH_SIZE, TIMEOUT, MAX_RETRIES — consulta el docs/embedding-providers.md del indexador.

El índice y la consulta deben coincidir en la configuración de incrustación. Un índice registra la identidad de los vectores que contiene (provider:variant@dimension, por ejemplo bow-local:fnv1a@256), mientras que una consulta híbrida o vectorial resuelve su propia identidad a partir de estas variables. Cuando difieren, la consulta falla con embedding mismatch: ... en lugar de devolver resultados débiles; el error de la herramienta nombra ambas identidades y cómo solucionarlo. Usa mode: "lexical" para buscar sin incrustaciones.

Este servidor solo lee variables de entorno. La CLI del indexador también acepta un config.yaml; si indexaste mediante un archivo de configuración, exporta las variables CONFLUENCE2MD_EMBEDDING_* equivalentes aquí para que ambos lados resuelvan el mismo proveedor.

Actualización de un Índice

Este servidor enlaza confluence2md-indexer v0.5.0, que lee columnas de metadatos de documentos que los índices construidos por versiones anteriores del indexador no tienen. Dichos índices no se migran en su lugar, así que reconstruye una vez después de actualizar:

confluence2md-indexer index ./output --rebuild

Consultar un índice construido por un indexador anterior falla con un error de base de datos; reconstruir es la solución compatible.

Instalación

Descarga el binario para tu plataforma desde Releases y colócalo en algún lugar de tu PATH.

VS Code

Crea o edita .vscode/mcp.json en tu espacio de trabajo:

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

MCP: Add Server en la Paleta de Comandos también funciona.

Claude Code

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

Nota sobre WSL: Usa el binario de Linux, no el .exe de Windows — el .exe no hereda las variables de entorno de WSL. La ruta de la base de datos debe ser una ruta nativa de Linux (p. ej., /home/user/confluence2md-index.db), no /mnt/c/, para evitar problemas de bloqueo de SQLite en montajes NTFS.

Codex CLI

Añade a ~/.codex/config.json:

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

Herramientas

`confluence.search`

Busca contenido de Confluence indexado desde una base de datos SQLite local.

Argumento	Requerido	Descripción
`query`	✓	Texto de la consulta de búsqueda
`dbPath`		Sobrescribe la ruta de la base de datos. Recurre a la variable de entorno `CONFLUENCE_INDEX_DB`, luego a `confluence2md-index.db` en el directorio de trabajo actual.
`mode`		`hybrid` (predeterminado) \| `lexical` \| `vector`
`fusion`		`weighted` (predeterminado) \| `rrf`
`alpha`		Alfa de fusión ponderada `[0..1]`, predeterminado `0.70`
`rrfK`		Constante k de RRF, predeterminado `60`
`topK`		Candidatos a clasificar, predeterminado `10`
`limit`		Máximo de resultados a devolver
`offset`		Desplazamiento de resultados
`candidateK`		Candidatos por canal de recuperación, predeterminado `50`
`expand`		Cantidad de fragmentos de expansión de contexto
`spaceKey`		Filtrar por clave de espacio
`pageId`		Filtrar por ID de página
`fromDate`		Límite inferior `YYYY-MM-DD`
`toDate`		Límite superior `YYYY-MM-DD`
`spaces`		Filtrar por varias claves de espacio; prevalece sobre `spaceKey`
`host`		Filtrar por host del sitio rastreado
`author`		Nombre del creador o último modificador, sin distinguir mayúsculas
`createdBy`		Solo nombre del creador
`modifiedBy`		Solo nombre del último modificador
`depthMin` / `depthMax`		Límites de profundidad de rastreo; `depthMin: 1` excluye páginas semilla
`seedOnly`		Solo las páginas desde las que comenzó el rastreo
`hasAttachments`		Solo páginas que tengan al menos un adjunto
`updatedSince`		Modificado dentro de una antigüedad (`30d`, `2w`, `12h`) o después de una fecha absoluta (`2026-01-01`)
`embeddingProvider`		Sobrescribe el proveedor para esta llamada: `bow-local` \| `openai` \| `openai-compatible`
`embeddingModel`		Sobrescribe el modelo de incrustación
`embeddingDim`		Sobrescribe la dimensión de incrustación
`embeddingBaseURL`		Sobrescribe el endpoint de incrustación
`embeddingApiKeyEnv`		Nombre de la variable de entorno que contiene la clave API
`embeddingAuthHeader` / `embeddingAuthScheme`		Sobrescribe el encabezado y el esquema de autenticación
`embeddingSkip`		Desactiva el canal vectorial para esta llamada
`embeddingDocumentPrefix` / `embeddingQueryPrefix`		Prefijos de texto para modelos asimétricos

Los filtros de metadatos se aplican por igual a la recuperación léxica, vectorial e híbrida. Los argumentos prevalecen sobre las variables de entorno: el indexador solo completa los campos de incrustación que los argumentos dejan sin establecer, por lo que embeddingModel sobrescribe CONFLUENCE2MD_EMBEDDING_MODEL para esa llamada. Una clave API literal deliberadamente no es un argumento — viajaría a través de la conversación del cliente y el registro del servidor — así que establece CONFLUENCE2MD_EMBEDDING_API_KEY o nombra otra variable con embeddingApiKeyEnv.

Campos de respuesta:

Campo	Descripción
`schemaVersion`	Cadena de versión del esquema para estabilidad del contrato
`tool`	Siempre `"confluence.search"`
`dbPath`	Ruta de base de datos resuelta utilizada para la consulta
`request`	Parámetros de solicitud reflejados
`count`	Número de resultados devueltos en esta respuesta
`total`	Total de resultados clasificados antes de la paginación
`results`	Matriz de objetos de resultado con texto del fragmento y desglose de puntuación

Los fallos se devuelven como errores de herramienta que conservan el mensaje del indexador y añaden la solución cuando la causa es accionable: un desajuste de incrustación nombra ambas identidades, un índice faltante o sin vectores nombra el comando de reconstrucción, y un canal vectorial desactivado apunta a CONFLUENCE2MD_EMBEDDING_SKIP. mode: "lexical" funciona sin ninguna configuración de incrustación.

`confluence.list_spaces`

Lista las claves de espacio de Confluence que contiene el índice, para que un cliente pueda acotar una búsqueda sin conocer las claves de antemano.

Argumento	Requerido	Descripción
`dbPath`		Sobrescribe la ruta de la base de datos. Recurre a `CONFLUENCE_INDEX_DB`, luego a `confluence2md-index.db` en el directorio de trabajo actual.

Campos de respuesta: schemaVersion, tool, dbPath, count y spaces — una matriz ordenada de cadenas de clave de espacio, vacía cuando el índice no contiene espacios.

Desarrollo

Compilación

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

Si las descargas de módulos fallan con 403, establece GOPROXY=direct.

Pruebas

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

La suite también contiene una prueba de extremo a extremo sin conexión: instala el indexador fijado (go install ...@v0.5.0), construye un índice a partir de un corpus temporal con el proveedor bow-local predeterminado y controla el servidor a través de stdio — verificando la lista de herramientas, la lista de espacios, una búsqueda acotada por espacio y el error de desajuste de proveedor. No necesita clave API ni servicio en ejecución, y solo se omite cuando la CLI del indexador no se puede instalar.

Versión

Las compilaciones de lanzamiento sellan el binario mediante ldflags; la versión se informa en la respuesta de initialize de MCP y se escribe en el registro de inicio. Un go build sin sellar informa dev.

Solución de Problemas

Sin resultados: verifica que CONFLUENCE_INDEX_DB apunte a un índice construido que contenga las tablas chunks_fts y embeddings.
WSL + binario de Windows: usa el binario de Linux con una ruta de base de datos nativa de Linux — consulta la nota de WSL anterior.
Herramientas que no aparecen en el chat: reinicia tu cliente MCP después del registro.