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

$3

- Flutter SDK 3.0 ou superior
- Dart SDK 3.0 ou superior

🚀 Instalação e Configuração

$3

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

$3

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

Ou usando o CLI:

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

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.

$3

#### 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@latest", "--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 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

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"

$3

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

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

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

$3

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

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

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

$3

#### Variáveis de Ambiente
`bash

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

$3

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

$3

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

$3

`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.

$3

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

$3

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

$3

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

$3

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

🗂️ Linguagens e Arquivos Suportados

$3

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

$3

- 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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- 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