# 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

1. **Clone o repositório no seu projeto:**
```bash
cd /caminho/para/seu/projeto
git clone https://github.com/seu-usuario/mcp-codebase-search.git
cd mcp-codebase-search
```

2. **Instale as dependências:**
```bash
npm install
```

3. **Instale globalmente para usar via NPX:**
```bash
npm install -g .
```

4. **Indexe o projeto:**
```bash
# Indexar o projeto atual (diretório pai)
node index-codebase.cjs
```

5. **Executar o servidor MCP:**
```bash
# 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

1. **Abra as configurações do Trae IDE**
2. **Navegue para MCP Servers**
3. **Adicione um novo servidor MCP:**

#### Configuração MCP no Trae IDE

**Opção 1: Usando NPX (Recomendado)**
```json
{
  "mcpServers": {
    "codebase-search": {
      "command": "npx",
      "args": ["mcp-codebase-search", "--stdio"]
    }
  }
}
```

**Opção 2: Caminho direto**
```json
{
  "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

1. **No Trae IDE, use o comando de busca MCP**
2. **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

1. **Configuração inicial:**
   ```bash
   # 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
   ```

2. **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:

```bash
# 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
```bash
# 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:
```javascript
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

```bash
# 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

```bash
# 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

1. **Configure o servidor MCP no Trae IDE** (veja seção de configuração)
2. **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

```bash
# 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:

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

## 📜 Scripts Disponíveis

```bash
# 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:
```bash
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:

1. **Certifique-se de usar a configuração correta:**
   ```json
   {
     "mcpServers": {
       "codebase-search": {
         "command": "node",
         "args": ["mcp-codebase-search/mcp-server.js", "--stdio"],
         "cwd": "${workspaceFolder}"
       }
     }
   }
   ```

2. **Verifique se o índice foi criado:**
   ```bash
   node mcp-codebase-search/index-codebase.js
   ```

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

#### Servidor MCP não conecta
```bash
# 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
```bash
# Verificar se o índice existe
ls -la .trae_index/

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

#### Modelo não baixa
```bash
# Limpar cache e tentar novamente
rm -rf ~/.cache/huggingface/
npm start
```

### Dicas de Performance

1. **Projetos Grandes**: Para projetos com +10k arquivos, considere filtrar diretórios:
   ```javascript
   // Em index-codebase.js, adicione ao IGNORE_PATTERNS
   'build/', 'dist/', '.git/', 'coverage/'
   ```

2. **Consultas Eficientes**: Use termos específicos:
   - ✅ "validação de formulário Flutter"
   - ❌ "código"

3. **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

```bash
# 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
```bash
# Re-indexe o projeto atual
node mcp-codebase-search/index-codebase.js
```

#### Modelo não carregado
```bash
# 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:

```bash
# 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**