CodeSeeker

Busca e transformação avançada de código, com tecnologia ugrep e ast-grep para fluxos de desenvolvimento modernos.

GitHub
10
Experimente este MCPPatrocinado

Documentação

CodeSeeker

Pesquisa e transformação avançada de código para assistentes de IA

Um servidor abrangente do Model Context Protocol (MCP) que combina o poder das filosofias do ugrep e do ast-grep para oferecer capacidades inteligentes de pesquisa e substituição para fluxos de trabalho modernos de desenvolvimento.

CodeSeeker-MCP MCP server

🚀 Recursos

O CodeSeeker fornece aos assistentes de IA capacidades completas de pesquisa E substituição:

🔍 Ferramentas de Pesquisa Principais

  • Pesquisa Básica: Correspondência de padrões padrão com filtragem por tipo de arquivo e contexto
  • Pesquisa Booleana: Pesquisa estilo Google com operadores AND, OR, NOT
  • Pesquisa Difusa: Correspondência aproximada de padrões permitindo erros de caracteres
  • Pesquisa em Arquivos: Pesquisa dentro de arquivos compactados e arquivos (zip, tar, 7z, etc.)
  • Pesquisa Interativa: Inicia a interface TUI do ugrep para pesquisa em tempo real
  • Pesquisa de Estrutura de Código: Encontra funções, classes, métodos, importações e variáveis

🔧 Ferramentas de Pesquisa e Substituição

  • Pesquisar e Substituir: Localizar e substituir com segurança, com pré-visualização e backups automáticos
  • Substituição em Lote: Múltiplas operações de pesquisa/substituição em um único comando
  • Refatoração de Código: Refatoração ciente da linguagem para estruturas de código em várias linguagens

⚡ Recursos Avançados

  • Saída JSON: Resultados estruturados perfeitos para processamento por IA
  • Filtragem por Tipo de Arquivo: Pesquise linguagens de programação específicas ou tipos de documento
  • Linhas de Contexto: Mostre linhas ao redor para melhor compreensão
  • Estatísticas de Pesquisa: Obtenha métricas detalhadas sobre operações de pesquisa
  • Suporte a Arquivos: Pesquise arquivos aninhados sem extração
  • Segurança em Primeiro Lugar: Modo de simulação (dry-run) por padrão com criação automática de backup
  • Consciência de Linguagem: Padrões inteligentes para JavaScript, TypeScript, Python, Java, C++

📋 Pré-requisitos

1. Instalar o ugrep

Ubuntu/Debian:

sudo apt-get install ugrep

macOS (Homebrew):

brew install ugrep

Windows (Chocolatey):

choco install ugrep

A partir do código-fonte:

git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install

Verificar a instalação:

ugrep --version
# Should show version 7.4 or higher

2. Instalar o Node.js

Certifique-se de ter o Node.js 18+ instalado:

node --version
# Should show v18.0.0 or higher

🛠️ Instalação

Clonar e Compilar

git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build

Teste Rápido

npm test
# Should show all tests passing

⚙️ Configuração

Integração com o Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "codeseeker": {
      "command": "node",
      "args": ["/absolute/path/to/codeseeker-mcp/build/index.js"]
    }
  }
}

Nota: Substitua /absolute/path/to/codeseeker-mcp pelo caminho real da sua instalação.

📖 Exemplos de Uso

Pesquisa Básica

Search for "function" in JavaScript files:
- Pattern: function
- File Types: js,ts
- Path: ./src
- Case Sensitive: false

Pesquisa Booleana

Find TODO items that are urgent but not marked as later:
- Query: TODO AND urgent -NOT later
- File Types: cpp,h,js,py

Pesquisa Difusa

Find "function" with up to 2 character errors (matches "functoin", "functio", etc.):
- Pattern: function  
- Max Errors: 2
- File Types: js,ts,py

Pesquisar e Substituir

Replace old function names with new ones (safe preview first):
- Pattern: oldFunctionName
- Replacement: newFunctionName
- File Types: js,ts
- Dry Run: true (preview changes)
- Backup: true (create backups)

Substituição em Lote

Multiple replacements in one operation:
- Replace "var " with "const "
- Replace "== " with "=== " 
- File Types: js,ts
- Dry Run: true

Refatoração de Código

Refactor function names across a codebase:
- Structure Type: function
- Old Pattern: getUserData
- New Pattern: fetchUserData
- Language: typescript
- Dry Run: true

🔧 Referência de Ferramentas

Ferramentas de Pesquisa

basic_search

Pesquisa de padrões padrão com opções de filtragem.

Parâmetros:

  • pattern (obrigatório): Padrão de pesquisa ou regex
  • path (opcional): Diretório para pesquisar (padrão: diretório atual)
  • caseSensitive (opcional): Pesquisa sensível a maiúsculas/minúsculas (padrão: falso)
  • fileTypes (opcional): Tipos de arquivo separados por vírgula (ex.: "js,py,cpp")
  • excludeTypes (opcional): Tipos de arquivo a excluir
  • contextLines (opcional): Linhas de contexto ao redor das correspondências
  • maxResults (opcional): Máximo de resultados (padrão: 100)

boolean_search

Pesquisa estilo Google com operadores booleanos.

Parâmetros:

  • query (obrigatório): Consulta booleana (suporta AND, OR, NOT, parênteses)
  • path, fileTypes, maxResults: Mesmos da pesquisa básica

Exemplos de consultas:

  • "error AND (critical OR fatal)"
  • "TODO AND urgent -NOT completed"
  • "function OR method -NOT test"

fuzzy_search

Correspondência aproximada de padrões.

Parâmetros:

  • pattern (obrigatório): Padrão a pesquisar
  • maxErrors (opcional): Erros de caracteres permitidos 1-9 (padrão: 2)
  • path, fileTypes, maxResults: Mesmos da pesquisa básica

archive_search

Pesquisa em arquivos compactados e arquivos.

Parâmetros:

  • pattern (obrigatório): Padrão de pesquisa
  • path, maxResults: Mesmos da pesquisa básica
  • archiveTypes (opcional): Tipos de arquivo a pesquisar

code_structure_search

Encontra estruturas de código específicas.

Parâmetros:

  • structureType (obrigatório): Tipo a pesquisar (função, classe, método, importação, variável)
  • name (opcional): Nome específico a pesquisar
  • language (obrigatório): Linguagem de programação (js, ts, py, java, cpp)
  • path, maxResults: Mesmos da pesquisa básica

interactive_search

Inicia o modo TUI interativo.

Parâmetros:

  • initialPattern (opcional): Padrão de pesquisa inicial
  • path (opcional): Diretório inicial

Ferramentas de Substituição

search_and_replace

Localizar e substituir com segurança e pré-visualização.

Parâmetros:

  • pattern (obrigatório): Padrão de pesquisa ou regex
  • replacement (obrigatório): Texto de substituição (suporta grupos de captura $1, $2)
  • path (opcional): Diretório a processar (padrão: diretório atual)
  • fileTypes (opcional): Tipos de arquivo a incluir
  • caseSensitive (opcional): Pesquisa sensível a maiúsculas/minúsculas (padrão: falso)
  • dryRun (opcional): Modo de pré-visualização (padrão: verdadeiro)
  • maxFiles (opcional): Máximo de arquivos a processar (padrão: 50)
  • backup (opcional): Criar backups (padrão: verdadeiro)

bulk_replace

Múltiplas operações de pesquisa/substituição.

Parâmetros:

  • replacements (obrigatório): Matriz de objetos {pattern, replacement, description}
  • path, fileTypes, caseSensitive, dryRun, backup: Mesmos da pesquisa_e_substituição

code_refactor

Refatoração de código ciente da linguagem.

Parâmetros:

  • structureType (obrigatório): Tipo de estrutura de código (função, classe, variável, importação)
  • oldPattern (obrigatório): Padrão a encontrar
  • newPattern (obrigatório): Padrão de substituição
  • language (obrigatório): Linguagem de programação (js, ts, py, java, cpp)
  • path, dryRun, backup: Mesmos da pesquisa_e_substituição

Ferramentas Utilitárias

list_file_types

Obtenha todos os tipos de arquivo suportados para filtragem.

get_search_stats

Obtenha estatísticas detalhadas de pesquisa e métricas de desempenho.

🏗️ Desenvolvimento

Estrutura do Projeto

codeseeker-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── test.js              # Test suite
├── README.md            # This file
└── SETUP.md             # Quick setup guide

Compilação

npm run build           # Compile TypeScript
npm run dev            # Watch mode for development
npm run inspector      # Debug with MCP inspector

Testando o Servidor

# Test basic functionality
npm test

# Use MCP inspector for interactive testing
npm run inspector

# Test with Claude Desktop
# (Add to config and restart Claude Desktop)

🚨 Recursos de Segurança

Modo de Simulação (Dry Run)

Todas as operações de substituição usam o modo de simulação por padrão para segurança:

  • Pré-visualize as alterações antes de aplicar
  • Veja exatamente o que será modificado
  • Sem sobrescritas acidentais

Backups Automáticos

Ao fazer alterações:

  • Arquivos de backup criados automaticamente com carimbos de data/hora
  • Arquivos originais preservados
  • Reversão fácil se necessário

Tratamento de Erros

  • Mensagens de erro abrangentes
  • Tratamento de falhas gracioso
  • Verificação de permissões de arquivo

🐛 Solução de Problemas

Problemas Comuns

"ugrep não encontrado"

  • Certifique-se de que o ugrep está instalado e no seu PATH
  • Execute ugrep --version para verificar a instalação

"Permissão negada"

  • Certifique-se de que o arquivo build/index.js é executável
  • Execute chmod +x build/index.js (em sistemas Unix)

"Erros de módulo não encontrado"

  • Execute npm install para instalar as dependências
  • Certifique-se de estar usando Node.js 18 ou superior

"Claude Desktop não mostra as ferramentas"

  • Verifique se o caminho do arquivo de configuração está correto
  • Reinicie o Claude Desktop após alterações de configuração
  • Verifique os logs do Claude Desktop para erros de conexão

"Nenhum arquivo encontrado para processar"

  • Verifique se o caminho existe e contém arquivos correspondentes
  • Verifique se os filtros de tipo de arquivo estão corretos
  • Certifique-se de que o ugrep pode acessar os diretórios especificados

⚡ Notas de Desempenho

  • O ugrep é extremamente rápido, muitas vezes superando outras ferramentas de grep
  • A saída JSON adiciona sobrecarga mínima
  • A pesquisa em arquivos pode ser mais lenta dependendo da compactação
  • Grandes conjuntos de resultados são limitados pelo parâmetro maxResults
  • As operações de substituição processam arquivos de forma eficiente com streaming
  • O modo interativo requer um terminal e não pode ser executado via MCP

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

📄 Licença

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

🔗 Projetos Relacionados

📊 Resumo de Ferramentas

FerramentaPropósitoEntradaSaída
basic_searchPesquisa de texto padrãoPadrão + filtrosCorrespondências com contexto
boolean_searchConsultas de pesquisa lógicaExpressão booleanaResultados filtrados
fuzzy_searchCorrespondência aproximadaPadrão + tolerância a errosCorrespondências difusas
archive_searchPesquisar arquivos compactadosPadrão + tipos de arquivoConteúdo do arquivo
code_structure_searchEncontrar elementos de códigoTipo de estrutura + linguagemDefinições de código
search_and_replaceLocalizar e substituir textoPadrão + substituiçãoPré-visualização/alterações
bulk_replaceMúltiplas substituiçõesMatriz de operaçõesResultados em lote
code_refactorRefatorar estruturas de códigoPadrões antigo/novo + linguagemCódigo refatorado
interactive_searchIniciar modo TUIPadrão inicialComando para executar
list_file_typesMostrar tipos suportadosNenhumExtensões disponíveis
get_search_statsMétricas de pesquisaParâmetros de pesquisaEstatísticas de desempenho

CodeSeeker - Inteligência em cada pesquisa, precisão em cada alteração.

Total de Ferramentas Disponíveis: 11 (8 de pesquisa + 3 de substituição)