Markdown Navigation MCP

Markdown Navigation MCP Server

Navega eficientemente por archivos markdown grandes (más de 2.000 líneas) sin cargar documentos completos en el contexto. Reduce el uso de tokens entre un 50 y un 80 % al trabajar con documentación, archivos de planificación y especificaciones técnicas.

Inicio rápido

Requisitos previos: Universal Ctags y Go 1.21+

# Install ctags
brew install universal-ctags         # macOS
sudo apt install universal-ctags     # Ubuntu/Debian
sudo dnf install universal-ctags     # Fedora

# Build and install
git clone <repo-url>
cd markdown-mcp
go build -o mdnav-server ./cmd/server
sudo cp mdnav-server /usr/local/bin/

Configurar Claude Code (~/claude.json):

{
  "mcpServers": {
    "markdown-nav": {
      "command": "mdnav-server"
    }
  }
}

Características

• Configuración cero: ejecución automática de ctags bajo demanda
• Caché inteligente: respuestas en menos de un microsegundo para consultas repetidas
• Invalidación automática: la caché se actualiza cuando los archivos cambian
• Lectura selectiva: carga solo las secciones que necesitas
• Navegación por árbol: visualiza la estructura del documento sin leer el contenido
• Coincidencia de patrones: encuentra secciones mediante patrones regex
• Control de profundidad: limita la profundidad del árbol/secciones para vistas enfocadas

Herramientas

markdown_tree

Muestra la estructura del documento como un árbol (formato ASCII o JSON).

Parámetros clave:

• file_path: Ruta al archivo markdown
• format: "ascii" o "json" (predeterminado: "json")
• max_depth: Limita la profundidad del árbol de 1 a 6 (predeterminado: 2 muestra H1+H2)
• section_name_pattern: Regex para filtrar secciones

markdown_section_bounds

Obtiene los límites de número de línea de una sección específica.

Parámetros clave:

• file_path: Ruta al archivo markdown
• section_heading: Texto exacto del encabezado (sin símbolos #)

markdown_read_section

Lee el contenido de una sección específica.

Parámetros clave:

• file_path: Ruta al archivo markdown
• section_heading: Texto exacto del encabezado (sin símbolos #)
• max_subsection_levels: Limita la profundidad de las subsecciones (omitir para todas)

markdown_list_sections

Lista todas las secciones con filtros.

Parámetros clave:

• file_path: Ruta al archivo markdown
• max_depth: Nivel máximo de encabezado a mostrar (predeterminado: 2)
• section_name_pattern: Regex para filtrar nombres de secciones

Ejemplos de uso

Encontrar y leer una tarea específica

User: "Review Task 4 from the planning document"

Claude uses:
1. markdown_tree to see document structure
2. markdown_section_bounds to find Task 4 location
3. markdown_read_section to read only Task 4 content

Result: Complete task analysis using only relevant section (~200 lines instead of 2000)

Descubrir secciones de documentación

User: "What testing strategies are documented?"

Claude uses:
1. markdown_list_sections with pattern="test" to find testing sections
2. markdown_read_section for each relevant section

Result: Comprehensive overview without loading entire document

Para ver ejemplos más detallados de uso de herramientas con resultados reales, consulta examples/EXAMPLES.md.

Configuración

Ruta personalizada de ctags

Si ctags no está en PATH, especifica su ubicación:

{
  "mcpServers": {
    "markdown-nav": {
      "command": "mdnav-server",
      "args": ["-ctags-path", "/custom/path/to/ctags"]
    }
  }
}

Solución de problemas

"ctags not found in PATH"

• Instala Universal Ctags o usa la opción -ctags-path

"section not found"

• Usa el texto exacto del encabezado (distingue mayúsculas y minúsculas, sin símbolos #)
• Ejecuta markdown_list_sections para ver las secciones disponibles

"no entries found"

• Asegúrate de que el archivo tenga encabezados markdown (#, ##, ###, ####)
• Verifica que Universal Ctags (no Exuberant) esté instalado

Problemas de caché

• Reinicia el servidor MCP para limpiar la caché (se invalida automáticamente cuando los archivos cambian)

Desarrollo

Para detalles de implementación, arquitectura y pautas de contribución, consulta CLAUDE.md.

Comandos rápidos de desarrollo:

go test ./...              # Run tests
golangci-lint run         # Lint code
go build ./cmd/server     # Build server

Licencia

Este proyecto está licenciado bajo la GNU General Public License v3.0.