Este projeto implementa um servidor MCP (Model Context Protocol) compatível com o Trae IDE que permite realizar consultas semânticas no seu codebase atual usando embeddings locais. Otimizado especialmente para projetos Flutter/Dart!

🚀 Funcionalidades

Busca Semântica: Encontre código usando linguagem natural
Foco Flutter/Dart: Otimizado para projetos Flutter com suporte completo a Dart
Suporte Multi-linguagem: JavaScript, TypeScript, Java, Swift, Kotlin, etc.
Embeddings Locais: Usa @xenova/transformers para processamento local
Protocolo MCP: Compatível com Trae IDE via stdio
Performance: Índice local FAISS para consultas rápidas
Filtros Inteligentes: Ignora automaticamente .dart_tool, build/, .fvm, etc.
Configuração Flutter: Suporte completo a pubspec.yaml, assets, plugins

📋 Pré-requisitos

Node.js 18.0 ou superior
npm ou yarn
Pelo menos 4GB de RAM disponível
Espaço em disco: ~1GB para modelos e índices

Para Projetos Flutter

Flutter SDK 3.0 ou superior
Dart SDK 3.0 ou superior

🚀 Instalação e Configuração

Pré-requisitos

Node.js 18+ instalado
npm ou yarn
Trae IDE instalado

🎯 Instalação e Uso

Clone o repositório no seu projeto:

cd /caminho/para/seu/projeto
git clone https://github.com/seu-usuario/mcp-codebase-search.git
cd mcp-codebase-search

Instale as dependências:

npm install

Instale globalmente para usar via NPX:

npm install -g .

Indexe o projeto:

# Indexar o projeto atual (diretório pai)
node index-codebase.cjs
# Ou usando o CLI:
npx mcp-codebase-search index [caminho/opcional]

Executar o servidor MCP:

# Via NPX (recomendado)
npx mcp-codebase-search --stdio

# Ou diretamente
node mcp-server.cjs --stdio

Nota: A primeira execução pode demorar alguns minutos para baixar os modelos de embedding.

🎯 Integração com Trae IDE

Configuração no Trae

Abra as configurações do Trae IDE
Navegue para MCP Servers
Adicione um novo servidor MCP:

Configuração MCP no Trae IDE

Opção 1: Usando NPX (Recomendado)

{
  "mcpServers": {
    "codebase-search": {
      "command": "npx",
      "args": ["mcp-codebase-search@latest", "--stdio"]
    }
  }
}

Opção 2: Caminho direto

{
  "mcpServers": {
    "codebase-search": {
      "command": "node",
      "args": ["mcp-codebase-search/mcp-server.cjs", "--stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Requisitos:

✅ O diretório mcp-codebase-search deve estar na raiz do seu projeto
✅ O índice será criado no diretório code_index dentro do projeto
✅ Usa protocolo MCP via stdio para comunicação com o Trae IDE

Uso no Trae IDE

No Trae IDE, use o comando de busca MCP
Digite sua consulta em linguagem natural:
- "função para validar email"
- "widget para exibir lista no Flutter"
- "navegação entre telas"
- "gerenciamento de estado"
- "requisição HTTP API"

🔄 Workflow Recomendado

Configuração inicial:

# Navegue até o diretório do seu projeto
cd /caminho/para/seu/projeto

# Clone o MCP no seu projeto
git clone https://github.com/seu-usuario/mcp-codebase-search.git
cd mcp-codebase-search

# Instale as dependências
npm install

# Indexe o projeto (gera a pasta code_index)
npx mcp-codebase-search index
# Ou especifique o caminho do projeto
npx mcp-codebase-search index /caminho/para/seu/projeto

No Trae IDE:
- Configure o servidor MCP nas configurações
- Use a busca MCP para encontrar código relevante
- Refine suas consultas conforme necessário
- Re-indexe quando necessário executando novamente o indexador

🔄 Re-indexação Automática via CLI

O CLI inclui um comando para monitorar alterações e reindexar automaticamente:

npx mcp-codebase-search watch-index [caminho/opcional]

O índice será atualizado automaticamente ao detectar mudanças no código.
O índice é salvo na pasta code_index do projeto.

Como Re-indexar Manualmente

Para re-indexar o projeto manualmente, execute novamente o comando de indexação:

npx mcp-codebase-search index

Quando Re-indexar

Após adicionar novos arquivos ao projeto
Depois de fazer mudanças significativas no código
Quando a busca não retorna resultados esperados
Após atualizar dependências ou estrutura do projeto

⚙️ Configurações Avançadas

Variáveis de Ambiente

# Nível de log (padrão: info)
LOG_LEVEL=debug npm start

# Diretório do índice (padrão: ./code_index)
INDEX_PATH=/custom/path npm start

Personalizar Tipos de Arquivo

Edite index-codebase.cjs para adicionar extensões:

const SUPPORTED_EXTENSIONS = [
  '.dart', '.js', '.ts', '.py', '.java', '.kt',
  '.swift', '.go', '.rs', '.cpp', '.c', '.h',
  '.json', '.yaml', '.yml', '.md', '.txt'
];

📁 Estrutura do Projeto

seu-projeto/
├── mcp-codebase-search/   # Diretório do MCP (clonado)
│   ├── index-codebase.js  # Script para indexar o codebase
│   ├── mcp-server.js      # Servidor MCP
│   ├── test-search.js     # Script de teste da API
│   ├── package.json       # Dependências Node.js
│   └── README.md         # Este arquivo
├── codebase_index/       # Índice gerado (criado automaticamente)
├── lib/                  # Seu código Flutter/Dart
│   ├── main.dart
│   ├── models/
│   ├── screens/
│   ├── services/
│   └── utils/
├── pubspec.yaml          # Configuração Flutter
└── ... (outros arquivos do projeto)

🔧 Uso

Passo 1: Preparar seu projeto Flutter

Certifique-se de que seu projeto Flutter está em um diretório acessível. O indexador suporta:

Arquivos Flutter/Dart:

.dart - Código Dart/Flutter
pubspec.yaml - Configuração de dependências
pubspec.lock - Lock de dependências (ignorado)
Assets, plugins, configurações

Configurações Mobile:

build.gradle - Configuração Android
Info.plist - Configuração iOS
AndroidManifest.xml

Outras linguagens suportadas:

JavaScript, TypeScript, HTML, CSS
Swift, Kotlin, Java
JSON, YAML, XML, Markdown

Passo 2: Indexar o codebase

# Indexar o projeto atual (do diretório raiz do projeto)
node mcp-codebase-search/index-codebase.js

Exemplo de saída para projeto Flutter:

2024-01-15 10:30:15 - INFO - Iniciando indexação do codebase...
2024-01-15 10:30:16 - INFO - Encontrados 67 arquivos para indexar
2024-01-15 10:30:20 - INFO - Processando: lib/main.dart
2024-01-15 10:30:21 - INFO - Processando: lib/models/user.dart
2024-01-15 10:30:22 - INFO - Processando: lib/screens/home_screen.dart
2024-01-15 10:30:23 - INFO - Processando: pubspec.yaml
...
2024-01-15 10:32:15 - INFO - Indexação concluída! 67 arquivos indexados.
2024-01-15 10:32:16 - INFO - Índice salvo em: ./codebase_index

Passo 3: Iniciar o servidor MCP

# Para uso com Trae IDE (modo stdio)
node mcp-codebase-search/mcp-server.js --stdio

# Para teste via HTTP (opcional)
node mcp-codebase-search/mcp-server.js

Saída esperada:

2024-01-15 10:35:00 - INFO - Carregando índice de: ./codebase_index
2024-01-15 10:35:02 - INFO - Índice carregado: 67 documentos
2024-01-15 10:35:02 - INFO - Servidor rodando em http://localhost:8000
2024-01-15 10:35:02 - INFO - Documentação disponível em: http://localhost:8000/docs

O servidor MCP estará pronto para receber consultas via stdio do Trae IDE.

Passo 4: Usar no Trae IDE

Configure o servidor MCP no Trae IDE (veja seção de configuração)
Use consultas em linguagem natural:
- "widget para exibir lista de usuários"
- "validação de email em dart"
- "Navigator push para nova tela"
- "gerenciamento de estado Flutter"

🎯 Exemplos de Consultas Flutter/Dart

Widgets e UI

"widget para exibir lista scrollável"
"como criar um botão customizado"
"formulário com validação de campos"
"navegação entre telas flutter"

Lógica de Negócio

"modelo de dados para usuário"
"serviço para fazer requisições HTTP"
"validação de CPF e email"
"gerenciamento de estado"

Configuração e Setup

"configuração de dependências pubspec"
"setup para Android e iOS"
"configuração de assets e fontes"
"plugins nativos flutter"

🗂️ Linguagens e Arquivos Suportados

Foco Principal: Flutter/Dart

.dart - Código Dart/Flutter (widgets, modelos, serviços)
pubspec.yaml - Configuração de dependências Flutter
.gradle - Configuração Android
.plist - Configuração iOS
AndroidManifest.xml - Manifest Android

Outras Linguagens

Web: .js, .ts, .html, .css, .scss
Mobile Nativo: .swift, .kt, .java, .m
Backend: .py, .go, .rs, .cpp
Configuração: .json, .yaml, .xml, .toml
Documentação: .md, .txt

Padrões Ignorados (Flutter)

O indexador automaticamente ignora:

.dart_tool/ - Ferramentas do Dart
build/ - Arquivos de build
.fvm/ - Flutter Version Management
pubspec.lock - Lock de dependências
android/app/build/ - Build Android
ios/build/ - Build iOS
.flutter-plugins* - Cache de plugins
coverage/ - Relatórios de cobertura

🔧 Configuração Avançada

Variáveis de Ambiente

# Caminho do índice (padrão: ./codebase_index)
export INDEX_PATH=/caminho/personalizado/indice

# Número máximo de resultados (padrão: 10)
export MAX_RESULTS=20

# Nível de log (padrão: info)
export LOG_LEVEL=debug

Personalizar Extensões de Arquivo

Edite o arquivo index-codebase.js para adicionar novas extensões:

const SUPPORTED_EXTENSIONS = [
  // Flutter/Dart (prioridade)
  '.dart', '.pubspec',
  // Suas extensões personalizadas
  '.custom', '.config'
];

📜 Scripts Disponíveis

# Indexar o projeto atual
node mcp-codebase-search/index-codebase.js

# Iniciar servidor MCP (modo stdio para Trae IDE)
node mcp-codebase-search/mcp-server.js --stdio

# Iniciar servidor HTTP (para testes)
node mcp-codebase-search/mcp-server.js

# Testar a API
node mcp-codebase-search/test-search.js

# Testar servidor MCP
node mcp-codebase-search/mcp-server.js --stdio

📊 Monitoramento

O servidor MCP fornece logs detalhados sobre:

Número de documentos indexados
Consultas realizadas
Performance das buscas
Erros e avisos

Para logs detalhados:

LOG_LEVEL=debug node mcp-codebase-search/mcp-server.js --stdio

📊 Exemplo de Uso no Trae IDE

Consultas Típicas

Busca por funcionalidade:

"função para validar email"
"widget para exibir lista"
"navegação entre telas"

Busca por padrões:

"como fazer requisição HTTP"
"gerenciamento de estado"
"validação de formulário"

Busca por componentes:

"botão customizado Flutter"
"lista scrollável"
"modal ou dialog"

🔧 Troubleshooting

Problemas Comuns

Erro: "MCP error -32000: Connection closed"

Este erro indica que o Trae IDE não conseguiu se conectar ao servidor MCP. Soluções:

Certifique-se de usar a configuração correta:

{
  "mcpServers": {
    "codebase-search": {
      "command": "node",
      "args": ["mcp-codebase-search/mcp-server.js", "--stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Verifique se o índice foi criado:

node mcp-codebase-search/index-codebase.js

Teste o comando manualmente:
```
node mcp-codebase-search/mcp-server.js --stdio
```
Deve mostrar "✅ Servidor MCP pronto para receber consultas via stdio!"

Servidor MCP não conecta

# Testar o servidor manualmente
node mcp-codebase-search/mcp-server.js --stdio

# Verificar se o índice existe
ls -la codebase_index/

Índice não encontrado

# Verificar se o índice existe
ls -la .trae_index/

# Re-indexar o projeto atual
node index-codebase.js

Modelo não baixa

# Limpar cache e tentar novamente
rm -rf ~/.cache/huggingface/
npm start

Dicas de Performance

Projetos Grandes: Para projetos com +10k arquivos, considere filtrar diretórios:

// Em index-codebase.js, adicione ao IGNORE_PATTERNS
'build/', 'dist/', '.git/', 'coverage/'

Consultas Eficientes: Use termos específicos:
- ✅ "validação de formulário Flutter"
- ❌ "código"
Threshold Otimizado:
- 0.2-0.3: Resultados mais amplos
- 0.4-0.6: Resultados mais precisos
- 0.7+: Apenas matches muito similares

Logs e Debugging

# Logs detalhados do servidor MCP
LOG_LEVEL=debug node mcp-codebase-search/mcp-server.js --stdio

# Logs de indexação
node mcp-codebase-search/index-codebase.js

🐛 Solução de Problemas

Índice não encontrado

# Re-indexe o projeto atual
node mcp-codebase-search/index-codebase.js

Modelo não carregado

# Limpe o cache e reinstale
rm -rf node_modules/.cache
npm install

Performance lenta

Verifique se tem pelo menos 4GB RAM disponível
Use SSD para melhor performance de I/O
Considere indexar apenas diretórios específicos

Projeto Flutter não indexado corretamente

Verifique se está no diretório raiz do projeto Flutter
Confirme que existe pubspec.yaml no diretório
Verifique se os arquivos .dart estão em lib/

📝 Uso com Projeto Flutter

Para usar com seu projeto Flutter, certifique-se de que possui a estrutura típica:

lib/main.dart - App principal com navegação
lib/models/ - Modelos de dados
lib/screens/ - Telas da aplicação
lib/services/ - Serviços HTTP e APIs
lib/utils/ - Utilitários e validações
pubspec.yaml - Configuração do projeto

🎯 Exemplo de Projeto Flutter

Para usar o MCP Codebase Search com um projeto Flutter existente:

# 1. Navegue até o diretório do seu projeto Flutter
cd /caminho/para/seu/projeto/flutter

# 2. Clone e configure o MCP
git clone https://github.com/seu-usuario/mcp-codebase-search.git
cd mcp-codebase-search
npm install

# 3. Volte para o diretório do projeto e indexe
cd ..
node mcp-codebase-search/index-codebase.js

# 4. Configure no Trae IDE e use via MCP
# O servidor será iniciado automaticamente pelo Trae IDE

O MCP indexará automaticamente:

lib/ - Código Dart principal
test/ - Testes
integration_test/ - Testes de integração
Arquivos de configuração (pubspec.yaml, etc.)

🤝 Contribuição

Contribuições são bem-vindas! Especialmente para:

Melhorias no suporte Flutter/Dart
Novos padrões de arquivos Flutter
Otimizações de performance
Exemplos de uso

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

Desenvolvido com ❤️ para a comunidade Flutter/Dart

Keywords

FAQs

What is mcp-codebase-search?

Is mcp-codebase-search popular?

Is mcp-codebase-search well maintained?

Package last updated on 27 Aug 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

mcp-codebase-search