Search Tools MCP Server

🔍 Search Tools MCP Server

⚡ Um servidor inteligente de Model Context Protocol (MCP) que potencializa a análise de código com recursos avançados de busca e mapeamento de dependências

🌟 Visão Geral

O Search Tools MCP Server é um kit de ferramentas poderoso que combina busca tradicional de código com algoritmos inteligentes de análise. Ele utiliza o algoritmo CodeRank (inspirado no PageRank) para identificar os módulos mais críticos no seu código e oferece recursos sofisticados de busca que vão além da simples correspondência de texto.

🎯 Principais Recursos

🔎 Recursos Inteligentes de Busca

• Busca Contextual por Palavras-chave: Busca com Ripgrep e linhas de contexto configuráveis
• Descoberta de Símbolos: Extrai e analisa funções, classes, métodos e módulos
• Rastreamento de Uso: Encontra onde os símbolos são usados em todo o código
• Resultados Priorizados: Resultados de busca classificados por importância do código

🧠 Inteligência e Análise

• Algoritmo CodeRank: Identifica os módulos mais críticos usando análise de redes
• Mapeamento de Dependências: Rastreia cadeias complexas de dependências e análise de impacto
• Detecção de Pontos Críticos: Encontra áreas do código altamente conectadas e frequentemente usadas
• Impacto de Refatoração: Analisa o impacto potencial de mudanças no código

🎨 Filtros Avançados

• Filtro por tipo de símbolo (funções, métodos, classes)
• Padrões de inclusão/exclusão de arquivos
• Rastreamento de dependências de módulos externos
• Análise de documentação em Markdown

🛠️ Instalação

Pré-requisitos

• Python 3.13+
• Gerenciador de pacotes uv
• Ferramenta CLI kit (para análise de símbolos)
• ripgrep (para busca rápida de texto)

Configuração

# Clone the repository
git clone <repository-url>
cd search-tools

# Install dependencies
uv sync

⚙️ Configuração

Adicionando ao Cursor/Windsurf

Adicione a seguinte configuração ao seu arquivo mcp.json:

{
  "mcpServers": {
    "search-tools": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/search-tools",
        "main.py"
      ]
    }
  }
}

Para usuários de macOS com Homebrew:

{
  "mcpServers": {
    "search-tools": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/search-tools/directory",
        "main.py"
      ]
    }
  }
}

Para adicionar ao claude code:

claude mcp add-json search-tools '{"type":"stdio","command":"/Users/yourusername/.local/bin/uv","args":[ "run", "--directory", "/path/to/your/search-tools/directory", "main.py"]}'

📍 Encontrando Seus Caminhos

Para encontrar os caminhos corretos para o seu sistema:

# Find uv location
which uv

# Get absolute path to search-tools directory  
pwd  # (run this from the search-tools directory)

🚀 Ferramentas Disponíveis

🔍 contextual_keyword_search

Busca por palavras-chave com linhas de contexto configuráveis ao redor das correspondências.

Parâmetros:

• keyword: Termo de busca (sem diferenciar maiúsculas/minúsculas)
• working_directory: Caminho absoluto do diretório de busca
• num_context_lines: Linhas de contexto (padrão: 2)

🏗️ get_repo_symbols

Extrai símbolos (funções, classes, métodos) do seu código.

Parâmetros:

• repo: Caminho do repositório
• working_directory: Diretório de execução de comandos
• keep_types: Filtro por tipos de símbolos
• file_must_contain/file_must_not_contain: Filtro de arquivos

📊 get_symbol_usages

Encontra onde símbolos específicos são usados em todo o código.

Parâmetros:

• repo: Caminho do repositório
• symbol_name_or_substring: Símbolo a ser pesquisado
• working_directory: Diretório de execução de comandos
• symbol_type: Filtro de tipo opcional

🎯 coderank_analysis

Analisa a importância do repositório usando o algoritmo CodeRank.

Parâmetros:

• repo_path: Repositório a ser analisado
• external_modules: Dependências externas separadas por vírgula
• top_n: Número de módulos principais a retornar (padrão: 10)
• analyze_markdown: Incluir arquivos markdown
• output_format: "summary", "detailed" ou "json"

🔥 find_code_hotspots

Identifica áreas críticas do código combinando conectividade e frequência de uso.

Parâmetros:

• repo_path: Caminho do repositório
• working_directory: Diretório de execução de comandos
• min_connections: Conexões mínimas de importação (padrão: 5)
• include_external: Incluir dependências externas
• top_n: Número de pontos críticos a retornar (padrão: 20)

🌐 trace_dependency_impact

Rastreia cadeias de dependências e analisa o impacto de refatoração.

Parâmetros:

• repo_path: Caminho do repositório
• target_module: Módulo a ser analisado
• working_directory: Diretório de execução de comandos
• analysis_type: "dependency", "refactoring" ou "both"
• max_depth: Profundidade máxima do rastreamento (padrão: 3)
• change_type: "modify", "split", "merge" ou "remove"

🎪 smart_code_search

Busca aprimorada combinando ripgrep com priorização CodeRank.

Parâmetros:

• keyword: Termo de busca (suporta regex)
• repo_path: Caminho do repositório
• working_directory: Diretório de execução de comandos
• rank_results: Ordenar por importância do módulo
• context_lines: Linhas de contexto ao redor das correspondências (padrão: 3)
• max_results: Número máximo de resultados a retornar (padrão: 20)

🧪 Desenvolvimento e Testes

Executando o Servidor

# Development mode
uv run mcp dev main.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector python main.py

🔧 Dependências

• mcp[cli]: Framework Model Context Protocol
• cased-kit: Kit de ferramentas para análise de símbolos
• networkx: Análise de grafos para o algoritmo CodeRank

🎨 Detalhes do Algoritmo

Algoritmo CodeRank

O algoritmo CodeRank trata seu código como um grafo direcionado onde:

• Nós: Módulos Python, classes, funções, métodos
• Arestas: Relações de importação e dependências
• Pesos: Pesos diferentes para dependências internas vs. externas

Isso cria um sistema de classificação que identifica as partes mais "centrais" e importantes do seu código, de forma semelhante a como o PageRank identifica páginas web importantes.

💡 Casos de Uso

• 🔍 Exploração de Código: Entenda rapidamente grandes bases de código
• 🏗️ Planejamento de Refatoração: Identifique áreas de alto impacto antes das mudanças
• 📚 Documentação: Encontre os módulos mais importantes para documentar primeiro
• 🐛 Investigação de Bugs: Foque nos caminhos críticos do código
• 👥 Revisão de Código: Priorize esforços de revisão em módulos importantes

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar issues, solicitações de recursos ou pull requests.

📄 Licença

Este projeto é open source. Verifique o arquivo de licença para mais detalhes.

---