simple-init-service

v1.0.1

Published

4 months ago

MCP server for semantic codebase search using Transformers.js

0High
0Medium
0Low

moisesmayrinck

mcp semantic-search codebase embeddings trae-ide

MCP Codebase Search

Servidor MCP para consulta semântica de codebase - Especializado em Flutter/Dart

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

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", "--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 deve ter sido criado previamente com node index-codebase.js
✅ 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
   
# Volte para o diretório do projeto e indexe
cd ..
node mcp-codebase-search/index-codebase.cjs

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 MCP

O servidor MCP inclui uma funcionalidade para re-indexar o codebase automaticamente quando necessário. Isso é útil quando você faz alterações no código e quer atualizar o índice de busca sem reiniciar o servidor.

Como Usar no Trae IDE

O Trae IDE pode executar comandos MCP para re-indexação. Quando você solicitar ao assistente para "re-indexar o projeto" ou "atualizar o índice", ele usará automaticamente esta funcionalidade.

Como Re-indexar

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

# Re-indexar o projeto atual
node mcp-codebase-search/index-codebase.cjs

O Trae IDE também pode solicitar re-indexação automaticamente quando necessário.

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: ./codebase_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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MCP Codebase Search

🚀 Funcionalidades

📋 Pré-requisitos

Para Projetos Flutter

🚀 Instalação e Configuração

Pré-requisitos

🎯 Instalação e Uso

🎯 Integração com Trae IDE

Configuração no Trae

Configuração MCP no Trae IDE

Uso no Trae IDE

🔄 Workflow Recomendado

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

Como Usar no Trae IDE

Como Re-indexar

Quando Re-indexar

⚙️ Configurações Avançadas

Variáveis de Ambiente

Personalizar Tipos de Arquivo

📁 Estrutura do Projeto

🔧 Uso

Passo 1: Preparar seu projeto Flutter

Passo 2: Indexar o codebase

Passo 3: Iniciar o servidor MCP

Passo 4: Usar no Trae IDE

🎯 Exemplos de Consultas Flutter/Dart

Widgets e UI

Lógica de Negócio

Configuração e Setup

🗂️ Linguagens e Arquivos Suportados

Foco Principal: Flutter/Dart

Outras Linguagens

Padrões Ignorados (Flutter)

🔧 Configuração Avançada

Variáveis de Ambiente

Personalizar Extensões de Arquivo

📜 Scripts Disponíveis

📊 Monitoramento

📊 Exemplo de Uso no Trae IDE

Consultas Típicas

🔧 Troubleshooting

Problemas Comuns

Erro: "MCP error -32000: Connection closed"

Servidor MCP não conecta

Índice não encontrado

Modelo não baixa

Dicas de Performance

Logs e Debugging

🐛 Solução de Problemas

Índice não encontrado

Modelo não carregado

Performance lenta

Projeto Flutter não indexado corretamente

📝 Uso com Projeto Flutter

🎯 Exemplo de Projeto Flutter

🤝 Contribuição

📄 Licença