MCP Repo Search Server

---

Por que usar isso?

O problema: Você está trabalhando no seu repositório frontend e precisa encontrar um endpoint de API do backend. Ou está depurando e precisa encontrar onde uma função é definida no seu monorepo. Com o Claude Code, você pode pesquisar no repositório atual, mas e os seus outros projetos locais?

A solução: O Repo Lens permite que você declare seus repositórios uma vez em um arquivo de configuração YAML — ou pesquise qualquer diretório ad-hoc — e pesquise em todos eles simultaneamente usando pesquisa estrutural baseada em AST. Encontre a assinatura exata da função, a definição de classe ou a rota de API que você precisa sem sair do seu contexto atual.

Casos de uso

• Desenvolvimento Frontend + Backend: Pesquise rotas de API do backend enquanto trabalha no seu repositório frontend
• Projetos PHP + JS/TS: Encontre classes, traits e interfaces PHP junto com tipos TypeScript
• Arquitetura de microsserviços: Encontre definições de funções em vários serviços
• Navegação em monorepo: Pesquise entre pacotes sem trocar de diretório
• Exploração de código: Entenda como diferentes projetos do seu ecossistema se conectam

---

Início rápido

npx repo-lens-mcp

---

Principais recursos

Inteligência baseada em AST

Diferente da pesquisa de texto estilo grep, o Repo Lens usa ast-grep (escrito em Rust) para analisar o código em Árvores Sintáticas Abstratas:

• Precisão estrutural: Distinga entre class User e const User
• Consciência de exportação: Encontre apenas funções exportadas ou inclua as privadas
• Extração de assinaturas: Obtenha assinaturas completas de funções, não apenas nomes

Pesquisa sem atrito

Pesquise qualquer diretório instantaneamente com o parâmetro paths — sem necessidade de configuração:

• Passe caminhos de diretório diretamente para qualquer ferramenta de pesquisa
• Declare repositórios persistentes em repolens.yaml com aliases para uso repetido
• Combine ambos: repositórios registrados + caminhos ad-hoc na mesma consulta

Pesquisa em vários repositórios

Declare seus repositórios uma vez e pesquise todos de uma só vez:

• Configuração YAML estática — declare uma vez, pesquise sempre
• Filtre por alias de repositório ou pesquise em todos
• Os resultados incluem o contexto do repositório

Descoberta de rotas de API

Mapeie todos os endpoints de API em projetos Express, NestJS, Fastify e Laravel. Encontre aquele endpoint /users/:id em segundos.

---

Instalação

Claude Desktop / VS Code (Recomendado)

Adicione isso ao seu claude_desktop_config.json (ou às configurações de MCP do VS Code):

{
  "mcpServers": {
    "repo-lens": {
      "command": "npx",
      "args": ["-y", "repo-lens-mcp", "--config", "/home/user/repolens.yaml"]
    }
  }
}

Reinicie o Claude e estará pronto para usar.

Desenvolvimento local

git clone https://github.com/YohannHommet/repo-lens-mcp.git
cd repo-lens-mcp
pnpm install
pnpm build
pnpm dev

---

Configuração

Arquivo de configuração (repolens.yaml)

Crie um arquivo de configuração YAML declarando seus repositórios:

# repolens.yaml
repositories:
  - path: ~/projects/backend-api
    alias: backend
  - path: ~/projects/frontend-app
    alias: frontend
  - path: ~/projects/shared-lib

~ é expandido automaticamente para o seu diretório inicial.

Resolução do caminho de configuração

1. Argumento de CLI --config <path> (explícito — falha se o arquivo não for encontrado)
2. Padrão: ~/.config/repo-lens-mcp/repolens.yaml (gracioso — retorna vazio se não for encontrado, caminhos ad-hoc ainda funcionam)

Variáveis de ambiente

Variável	Padrão	Descrição
MCP_LOG_LEVEL	info	Nível de log: debug, info, warn, error

Exemplo:

{
  "env": {
    "MCP_LOG_LEVEL": "debug"
  }
}

---

Capacidades

Listagem de repositórios (1 ferramenta)

Ferramenta	Descrição
repolens_list_repositories	Lista todos os repositórios configurados (somente leitura)

Pesquisa de símbolos (3 ferramentas)

Pesquisa estrutural baseada em AST com tecnologia ast-grep. Suporta JavaScript/TypeScript e PHP (classes, traits, interfaces, enums, funções, métodos, constantes):

Ferramenta	Descrição
repolens_find_functions	Encontra definições de funções/métodos em JS/TS e PHP (suporta curingas como handle*)
repolens_find_classes	Encontra definições de classes (também encontra traits PHP)
repolens_find_types	Encontra interfaces e aliases de tipo (PHP: apenas interfaces)

Todas as ferramentas de pesquisa aceitam:

• paths — Caminhos de diretório ad-hoc para pesquisar (separados por vírgula, sem necessidade de registro)
• repoFilter — Filtra repositórios registrados por alias

Descoberta de rotas de API (1 ferramenta)

Ferramenta	Descrição
repolens_find_api_routes	Mapeia endpoints de API em Express, NestJS, Fastify, Laravel

---

Exemplos de uso

1. Pesquisar qualquer diretório (sem configuração)

"Encontre todas as funções que começam com 'handle' no meu backend"

repolens_find_functions(paths: "/home/user/projects/backend", name: "handle*")

2. Listar repositórios configurados

"Quais repositórios estão disponíveis?"

repolens_list_repositories()

3. Encontrar um endpoint de API

"Encontre a rota Express que lida com requisições POST para /login"

repolens_find_api_routes(repoFilter: "backend", method: "POST", pathPattern: "/login")

4. Encontrar uma classe específica

"Onde a classe UserService está definida?"

repolens_find_classes(name: "UserService")

---

E quanto à pesquisa de texto / operações de arquivo?

O Repo Lens foca em pesquisa multi-repositório baseada em AST. Para pesquisa de texto e operações de arquivo dentro do seu repositório atual, use as ferramentas integradas do Claude Code (Grep, Read, Glob), que são otimizadas para uso em repositório único.

Essa separação mantém o Repo Lens rápido e focado no que ele faz de melhor: inteligência estrutural de código entre repositórios.

---

Licença

AGPL-3.0

Este software é gratuito para uso. Se você modificar e distribuir (ou executá-lo como um serviço de rede), você deve compartilhar seu código-fonte sob a mesma licença.

---

Feito com carinho por Yohann Hommet