papermoon-mkdocs-mcp

Un servidor MCP ligero para sitios de documentación MkDocs. Lee archivos markdown directamente del disco, proporciona búsqueda de texto completo y búsqueda semántica opcional, y expone la estructura del proyecto a través del Protocolo de Contexto de Modelo.

Características

• 5 herramientas MCP -- search, read_document, list_documents, get_project_info, get_document_outline

• Búsqueda de palabras clave SQLite FTS5 con clasificación BM25 (cero dependencias externas)

• Búsqueda semántica vectorial opcional mediante sentence-transformers

• Búsqueda híbrida que combina resultados de palabras clave y vectores con fusión de rango recíproco

• Indexación incremental -- actualizaciones rápidas cuando los archivos cambian

• Índice SQLite persistente que sobrevive a los reinicios del servidor

• Consciente de la navegación -- analiza mkdocs.yml y .nav.yml

• Documentos excluibles -- mantén borradores y páginas internas fuera de la superficie MCP

• Seguridad primero -- prevención de traversal de rutas, conexiones de búsqueda de solo lectura

• Dependencias mínimas -- 3 requeridas, 2 opcionales

Related MCP server: mdbook-mcp-server

Instalación

pip install papermoon-mkdocs-mcp

Para habilitar la búsqueda vectorial:

pip install papermoon-mkdocs-mcp[vector]

Inicio rápido

Ejecuta desde la raíz de cualquier proyecto MkDocs (donde se encuentra mkdocs.yml):

cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp

O apunta a un archivo de configuración específico:

papermoon-mkdocs-mcp --config /path/to/mkdocs.yml

El servidor detecta automáticamente mkdocs.yml en el directorio actual cuando se omite --config.

Opciones de transporte

Por defecto, el servidor utiliza el transporte stdio. Puedes cambiar a un transporte de red para configuraciones remotas o de múltiples clientes:

# Streamable HTTP (recommended for network access)
papermoon-mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (legacy client compatibility)
papermoon-mkdocs-mcp --transport sse --port 8080

Nota de seguridad: Al enlazar a una dirección que no sea de loopback, coloca el servidor detrás de un proxy inverso (por ejemplo, nginx, Caddy) que termine TLS.

Configuración del cliente MCP

Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Nota: Si Claude Desktop no puede encontrar el comando (Failed to spawn process: No such file or directory), usa la ruta completa al ejecutable en lugar de solo mkdocs-mcp:

{
  "mcpServers": {
    "mkdocs": {
      "command": "/path/to/.venv/bin/mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Esto es común cuando el paquete está instalado en un entorno virtual cuyo directorio bin/ no está en el PATH de Claude Desktop.

Claude Code / VS Code

Añade a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Herramientas disponibles

search

Busca documentación usando búsqueda de palabras clave, semántica o híbrida.

Devuelve resultados clasificados con ruta, título, puntuación de relevancia (normalizada 0.0--1.0) y fragmento de texto.

read_document

Lee un archivo de documentación por su ruta relativa.

Devuelve el cuerpo markdown (frontmatter eliminado), el frontmatter analizado como un campo separado, la estructura de encabezados y los metadatos del archivo.

list_documents

Lista todos los archivos de documentación, opcionalmente filtrados por sección.

Devuelve metadatos de documentos (ruta, título, descripción, categorías, tamaño, mtime).

get_project_info

Obtiene metadatos del proyecto MkDocs. No toma parámetros.

Devuelve el nombre del sitio, URL del sitio, directorio de docs, tema, árbol de navegación, número de documentos y estado del índice.

get_document_outline

Obtiene la estructura de encabezados (tabla de contenidos) de un documento.

Devuelve el título del documento y una lista de encabezados con nivel, texto y ancla.

Exclusión de documentos

Algunos archivos markdown no merecen exponerse a través de MCP: borradores, runbooks internos, archivos de trabajo generados. Añade una lista mcp_exclude a mkdocs.yml:

site_name: My Docs

mcp_exclude:
  - drafts/             # any directory named 'drafts', at any depth
  - internal/**         # anchored: only 'internal/' at the docs root
  - "*-scratch.md"      # by filename suffix, at any depth
  - "!internal/public.md"  # re-include one file from a broader rule

Las exclusiones se aplican en todas partes a la vez. Un documento excluido está ausente del árbol de navegación, nunca entra en el índice de búsqueda, no aparece en list_documents y es rechazado por read_document y get_document_outline -- el rechazo es idéntico a la respuesta para un archivo que no existe, por lo que no revela que el documento está ahí.

mcp_exclude afecta solo a este servidor MCP. No cambia lo que mkdocs build publica.

Sintaxis de patrones

Los patrones son de estilo gitignore y coinciden con la ruta de un documento relativa a docs_dir.

• Un patrón que contiene / está anclado en docs_dir; uno sin él coincide a cualquier profundidad.

• Una / final restringe un patrón a directorios, por lo que drafts/ no oculta un archivo llamado drafts.md.

• Las reglas se evalúan en orden y la última que coincida decide, así que coloca las re-inclusiones ! después de la regla que recortan.

• Las líneas en blanco y los comentarios # se ignoran.

Los archivos recién excluidos se eliminan del índice en la siguiente ejecución, y eliminar un patrón los trae de vuelta -- no es necesario borrar .mkdocs-mcp.db.

Arquitectura

src/mkdocs_mcp/
  config.py      -- MkDocs config detection and nav parsing
  exclusions.py  -- mcp_exclude pattern matching
  repository.py  -- SQLite schema and CRUD operations
  indexer.py     -- Index orchestration with incremental updates
  searcher.py    -- Keyword, vector, and hybrid search
  server.py      -- FastMCP server with 5 tool definitions
  utils.py       -- Path validation, frontmatter parsing, text extraction
  models.py      -- Pydantic response models

Al iniciar, el servidor lee mkdocs.yml, escanea el directorio de docs y construye (o actualiza incrementalmente) un índice SQLite FTS5. Las consultas de búsqueda acceden al índice directamente; la búsqueda vectorial incrusta la consulta con all-MiniLM-L6-v2 y la compara con las incrustaciones de documentos almacenadas. El modo híbrido fusiona ambas listas de resultados usando fusión de rango recíproco.

Desarrollo

git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest

Linting y verificación de tipos:

ruff check .
mypy src/

Requisitos

• Python >= 3.10

• Requeridos: fastmcp (>=3.0, <4), pydantic (>=2.0, <3), pyyaml (>=6.0), markdown (>=3.4)

• Opcionales (búsqueda vectorial): sentence-transformers (>=3.0), numpy (>=1.24)

Licencia

Consulta LICENSE para más detalles.