Markdown Navigation MCP

Markdown Navigation MCP Server

Navegue com eficiência por arquivos Markdown grandes (2.000+ linhas) sem carregar documentos inteiros no contexto. Reduz o uso de tokens em 50-80% ao trabalhar com documentação, arquivos de planejamento e especificações técnicas.

Início Rápido

Pré-requisitos: Universal Ctags e 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 o Claude Code (~/claude.json):

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

Recursos

• Zero configuração: Execução automática de ctags sob demanda
• Cache inteligente: Respostas em submicrossegundos para consultas repetidas
• Invalidação automática: Cache atualizado quando arquivos mudam
• Leitura seletiva: Carregue apenas as seções necessárias
• Navegação em árvore: Visualize a estrutura do documento sem ler o conteúdo
• Correspondência de padrões: Encontre seções por padrões regex
• Controle de profundidade: Limite a profundidade da árvore/seção para visualizações focadas

Ferramentas

markdown_tree

Exibe a estrutura do documento como árvore (formato ASCII ou JSON).

Parâmetros principais:

• file_path: Caminho para o arquivo markdown
• format: "ascii" ou "json" (padrão: "json")
• max_depth: Limite a profundidade da árvore 1-6 (padrão: 2 mostra H1+H2)
• section_name_pattern: Regex para filtrar seções

markdown_section_bounds

Obtém os limites de números de linha para uma seção específica.

Parâmetros principais:

• file_path: Caminho para o arquivo markdown
• section_heading: Texto exato do cabeçalho (sem símbolos #)

markdown_read_section

Lê o conteúdo de uma seção específica.

Parâmetros principais:

• file_path: Caminho para o arquivo markdown
• section_heading: Texto exato do cabeçalho (sem símbolos #)
• max_subsection_levels: Limite a profundidade das subseções (omitir para todas)

markdown_list_sections

Lista todas as seções com filtros.

Parâmetros principais:

• file_path: Caminho para o arquivo markdown
• max_depth: Nível máximo de cabeçalho a exibir (padrão: 2)
• section_name_pattern: Regex para filtrar nomes de seções

Exemplos de Uso

Encontrando e lendo uma tarefa 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)

Descobrindo seções de documentação

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 exemplos mais detalhados de uso das ferramentas com saída real, consulte examples/EXAMPLES.md.

Configuração

Caminho personalizado do ctags

Se o ctags não estiver no PATH, especifique o local:

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

Solução de Problemas

"ctags not found in PATH"

• Instale o Universal Ctags ou use a flag -ctags-path

"section not found"

• Use o texto exato do cabeçalho (sensível a maiúsculas/minúsculas, sem símbolos #)
• Execute markdown_list_sections para ver as seções disponíveis

"no entries found"

• Certifique-se de que o arquivo possui cabeçalhos markdown (#, ##, ###, ####)
• Verifique se o Universal Ctags (não o Exuberant) está instalado

Problemas de cache

• Reinicie o servidor MCP para limpar o cache (invalida automaticamente quando arquivos mudam)

Desenvolvimento

Para detalhes de implementação, arquitetura e diretrizes de contribuição, consulte CLAUDE.md.

Comandos rápidos de desenvolvimento:

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

Licença

Este projeto é licenciado sob a GNU General Public License v3.0.