Ripgrep Search

Busque eficientemente em vaults do Obsidian usando a ferramenta ripgrep.

GitHub
7
Experimente este MCPPatrocinado

Documentação

Pesquisa no Vault do Obsidian para Claude

Este servidor MCP permite que o Claude pesquise conteúdo de arquivos usando ripgrep - com recursos extras para o Obsidian. Ele entende elementos específicos do Obsidian, como links wiki, propriedades de frontmatter, e fornece contexto inteligente sobre onde as correspondências são encontradas.

Ferramentas Disponíveis

rg_search_notes

Pesquise conteúdo de texto em suas notas com opções de escopo flexíveis.

  • Pesquise todo o conteúdo, apenas frontmatter, ou apenas o conteúdo das notas
  • Obtenha contexto inteligente mostrando qual propriedade de frontmatter ou título contém cada correspondência
  • Filtre por pasta e controle os limites de resultados

rg_search_links

Encontre e analise links em todo o seu vault.

  • Descubra links wiki ([[Note Title]]), links markdown e URLs externas
  • Filtre links por padrões de URL ou padrões de título
  • Útil para encontrar links quebrados ou analisar as conexões do seu grafo de conhecimento

rg_search_backlinks

Encontre todas as notas que linkam para uma nota alvo específica.

  • Identifique quais notas referenciam um tópico ou nota específica
  • Entenda o contexto ao redor de cada referência de backlink
  • Descubra como ideias se conectam em todo o seu vault

rg_search_recent_notes

Encontre notas modificadas dentro de intervalos de datas específicos.

  • Pesquise por data de modificação usando o formato AAAA-MM-DD
  • Útil para revisar trabalhos recentes ou encontrar notas de períodos específicos
  • Combine com outras pesquisas para encontrar notas recentes sobre tópicos específicos

rg_search_orphaned_notes

Identifique notas que não possuem links de entrada ou saída.

  • Encontre notas isoladas que podem precisar de melhor integração
  • Descubra conteúdo esquecido que poderia ser conectado ao seu grafo de conhecimento
  • Útil para manutenção e organização do vault

Capacidades Específicas do Obsidian

Detecção de Contexto Inteligente

Quando correspondências são encontradas, o Claude recebe contexto inteligente:

  • Correspondências em frontmatter: Mostra o nome da propriedade (ex.: tags, project, status)
  • Correspondências em conteúdo: Mostra o título mais próximo (ex.: ## Project Ideas, ### Meeting Notes)
  • Propriedades aninhadas: Lida com estruturas YAML complexas no frontmatter

Compreensão de Links

  • Links Wiki: [[Note Title]] e [[Note Title|Display Text]]
  • Links Markdown: [Display Text](note-file.md) e URLs externas
  • Links em Frontmatter: Links dentro de propriedades e listas YAML

Organização de Arquivos

  • Filtragem por Pasta: Limite pesquisas a diretórios específicos
  • Descoberta por Data: Encontre arquivos pelo horário de modificação
  • Estrutura do Vault: Entende os padrões de organização de arquivos do Obsidian

Parâmetros Adicionais

A maioria das ferramentas de pesquisa suporta estes parâmetros comuns:

Comportamento de Pesquisa

  • case_sensitive: true ou false (padrão: false)
  • folder: Limite a pesquisa a uma pasta específica (ex.: "Daily Notes", "Projects/Active")
  • max_results: Número de resultados a retornar (1-100, padrão: 15, limitado automaticamente)
  • smart_context: Incluir detecção de contexto (padrão: true, defina como false para pesquisas mais rápidas)

Escopo de Pesquisa (para rg_search_notes)

  • search_scope:
    • "all" - Pesquisar tudo (padrão)
    • "content_only" - Pular frontmatter, pesquisar apenas o conteúdo das notas
    • "frontmatter_only" - Pesquisar apenas propriedades de frontmatter YAML

Filtragem por Data (para rg_search_recent_notes)

  • start_date: Data inicial no formato AAAA-MM-DD (ex.: "2024-01-15")
  • end_date: Data final no formato AAAA-MM-DD (ex.: "2024-01-31")

Filtragem de Links (para rg_search_links)

  • link_type: "all", "wiki_links", "markdown_links", ou "external_urls"
  • url_pattern: Padrão regex para filtrar URLs
  • title_pattern: Padrão regex para filtrar títulos de links

Instalação

Pré-requisitos

  • Python 3.8 ou superior
  • ripgrep instalado e disponível no PATH
  • Um vault do Obsidian

Instalar ripgrep

Windows:

# Using winget (recommended)
winget install BurntSushi.ripgrep.MSVC

# Using chocolatey
choco install ripgrep

# Using scoop
scoop install ripgrep

macOS:

brew install ripgrep

Linux (Ubuntu/Debian):

sudo apt install ripgrep

Instalar o Servidor MCP

# Clone the repository
git clone https://github.com/kpetrovsky/kp-ripgrep-mcp.git
cd kp-ripgrep-mcp

# Install the package
pip install -e .

Configurar o Claude Desktop

Adicione esta configuração ao Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-search": {
      "command": "python",
      "args": ["-m", "rgrep_mcp.server"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Substitua /path/to/your/obsidian/vault pelo caminho real do seu vault.

Configuração Alternativa

Variável de Ambiente (todas as plataformas):

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

Arquivo de Configuração: Crie ~/.rgrep-mcp.json:

{
  "vault_path": "/path/to/your/obsidian/vault",
  "default_case_sensitive": false,
  "default_result_limit": 15
}

Solução de Problemas

"ripgrep (rg) não está instalado ou não está no PATH"

Verifique a instalação do ripgrep:

rg --version

Se este comando falhar, reinstale o ripgrep usando as instruções acima.

"Nenhum caminho de vault configurado" ou "O caminho do vault não existe"

  • Certifique-se de que a variável de ambiente OBSIDIAN_VAULT_PATH está configurada corretamente
  • Verifique se o caminho aponta para o diretório do seu vault do Obsidian (contém arquivos .md)
  • Use caminhos absolutos, não caminhos relativos
  • No Windows, use barras normais ou escape as barras invertidas no JSON: "C:/Users/Name/Vault" ou "C:\\Users\\Name\\Vault"

O Claude não está encontrando os resultados esperados

  • Verifique os termos de pesquisa: Confirme que o conteúdo realmente existe em suas notas
  • Verifique o escopo: Tente "search_scope": "all" primeiro, depois refine
  • Teste com consultas simples: Comece com buscas de texto básicas antes de usar padrões complexos
  • Verifique restrições de pasta: Se estiver usando o parâmetro folder, certifique-se de que ele contém as notas esperadas

Problemas de desempenho com vaults grandes

  • Use filtragem por pasta: Limite as pesquisas a diretórios específicos quando possível
  • Reduza max_results: Comece com limites menores (5-10) para respostas mais rápidas
  • Desative smart_context: Defina "smart_context": false para pesquisas mais rápidas quando o contexto não for necessário
  • Seja específico: Termos de pesquisa mais direcionados são mais rápidos que consultas amplas

Erros de formato de data

Use o formato AAAA-MM-DD para datas:

  • ✅ "2024-01-15"
  • ✅ "2024-12-31"
  • ❌ "01/15/2024"
  • ❌ "Jan 15, 2024"

Problemas de permissão

  • Certifique-se de que o Claude Desktop tem permissão para acessar o diretório do seu vault
  • No macOS, você pode precisar conceder Acesso Total ao Disco ao Claude Desktop nas Preferências do Sistema

Exemplo de Uso

Pergunte ao Claude:

  • "Encontre todas as notas contendo 'machine learning' na minha pasta Research"
  • "Mostre-me notas que modifiquei na semana passada"
  • "Quais notas linkam para minha nota 'Project Ideas'?"
  • "Encontre notas com 'productivity' na propriedade de tags"
  • "Pesquise por 'meeting' apenas no conteúdo das notas, não no frontmatter"

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.