Clangaroo

🦘 Clangaroo: Inteligência de código C++ rápida para LLMs via MCP

✨ Sobre

NOTA (janeiro de 2026): O Claude Code agora tem suporte integrado para LSPs, tornando isso desnecessário. Como ainda pode ser útil em outros ambientes agênticos, deixarei o projeto aqui por enquanto.

O Clangaroo permite que Claude Code, Gemini CLI e outros agentes de codificação naveguem pelo seu código C++ com facilidade. O Clangaroo fornece consulta rápida e direta de símbolos, funções, definições, hierarquias de chamadas, hierarquias de tipos e muito mais para seus melhores amigos LLM.

O Clangaroo combina a velocidade da análise do Tree-sitter com a precisão do clangd LSP, opcionalmente aprimorado pela IA do Google Gemini Flash para insights mais profundos. Deixe seus amigos de IA passarem mais tempo codificando e menos tempo tropeçando.

Mas POR QUE você fez isso? Eu ❤️ usar o Claude Code, mas toda vez que ele compacta automaticamente e começa a procurar a função em que trabalhamos por muito tempo, eu morro um pouco por dentro. Mas já não existem alguns MCPs que fazem isso - por que precisamos de outro? Passei algum tempo pesquisando e encontrei tanto o MCP-language-server quanto o Serena, que parecem perfeitamente bons! Infelizmente, nenhum funcionou para mim 😭

O Clangaroo foi feito para ser super simples e tem a intenção de 'simplesmente funcionar'.

📚 Sumário

• 🚀 Início Rápido
• 🎯 Recursos
• 💬 Exemplos de Uso
• 🛠️ Ferramentas Disponíveis
• 🤖 Recursos de IA (Opcional)
• ⚙️ Referência de Configuração
• 📋 Requisitos
• 🔧 Solução de Problemas
• 📄 Licença
• 🙏 Agradecimentos

🚀 Início Rápido

1. Instalar o Clangaroo

git clone https://github.com/jasondk/clangaroo
cd clangaroo
pip install -e .

2. Etapa especial de compilação para o seu projeto C++

O clang LSP precisa que você faça isso uma vez:

# For Makefile-based projects
make clean
compiledb make

# (Some people prefer using 🐻)
bear -- make

# For CMake projects
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cp build/compile_commands.json .

Isso criará um arquivo especial compile_commands.json na raiz do seu projeto.

3. Configure o Claude Desktop ou outro cliente MCP

Você sabia que agora pode adicionar servidores MCP ao LM Studio?

🎯 Configuração recomendada com IA:

N.B.: O uso de --ai-enabled usará o Google Gemini e incorrerá em um pequeno custo via sua chave de API do Gemini, se fornecida. Isso geralmente é muito pequeno, desde que você use o Gemini Flash ou Flash Lite.

Nota: Substitua 'command' e 'project' pelos caminhos corretos para o seu sistema e substitua your-google-ai-api-key pela sua chave de API (se estiver usando uma). Se você não deseja usar os serviços aprimorados por IA, basta omitir todas as opções --ai e a chave de API.

{
  "mcpServers": {
    "clangaroo": {
      "command": "/usr/local/bin/clangaroo",
      "args": [
        "--project", "/path/to/your/cpp/project",
        "--warmup",
        "--warmup-limit", "10",
        "--log-level", "info",
        "--ai-enabled",
        "--ai-provider", "gemini-2.5-flash",
        "--ai-cache-days", "14",
        "--ai-cost-limit", "15.0",
        "--call-hierarchy-depth", "10",
        "--ai-analysis-level", "summary",
        "--ai-context-level", "minimal"
      ],
      "env": {
        "CLANGAROO_AI_API_KEY": "your-google-ai-api-key"
      }
    }
  }
}

📍 Locais dos arquivos de configuração do Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Profundidade padrão da análise de IA (--ai-analysis-level, padrão: summary).

• summary: Visão geral rápida com pontos-chave
  
• detailed: Análise abrangente com exemplos e contexto
  
  

Profundidade padrão do contexto (--ai-context-level, padrão: minimal).

• minimal: Apenas o símbolo e a documentação imediata
  
• local: Incluir código circundante no mesmo arquivo
  
• full: Incluir dependências e arquivos relacionados
  

4. Reinicie o Claude Desktop

Saia e reinicie o Claude. Você está pronto para explorar seu código C++! 🎉

5. Adicione o servidor MCP ao Claude Code

claude mcp add-from-claude-desktop (and make sure clangaroo is checked)

OR

claude mcp add /usr/local/bin/clangaroo --project /path/to/your/cpp/project --warmup --warmup-limit 10 --log-level info --ai-enabled --ai-provider gemini-2.5-flash --ai-cache-days 14 --ai-cost-limit 15.0 --call-hierarchy-depth 10 --ai-analysis-level summary --ai-context-level minimal --name clangaroo --env CLANGAROO_AI_API_KEY=your-google-ai-api-key

🎯 Features

• ⚡ Ultra-Fast Navigation: Fast response times for code structure queries
• 🔍 Smart Symbol Search: Hybrid Tree-sitter + clangd search with automatic fallback
• 📊 Deep Code Analysis: Call hierarchies, type hierarchies, and reference tracking
• 🤖 AI-Powered Insights: Documentation summarization, pattern detection, and architectural analysis
• 💪 Robust: Works even with compilation errors thanks to Tree-sitter fallback
• 🚀 Zero Configuration: Just point to a project with compile_commands.json

💬 Usage Examples

This is really meant for coding agents like Claude Code more than you, but if you want to use it, you can just talk to your LLM naturally about your code once the MCP server is hooked up:

"Descubra o covil enigmático onde a classe `UserManager` é invocada do vazio."  
"Revele cada canto sombrio que invoca o temido ritual `summonSoulPayment()`."  
"Exponha os poderes profanos herdados pela classe `DatabaseConnection` de seus ancestrais antigos."  
"Disseque a distorcida hierarquia de chamadas de `unleashChaos()` e narre a descida do programa à loucura."
#YMMV

🛠️ Available Tools

Tool Category	Tools	Description
🔍 Discovery	cpp_list_files cpp_search_symbols	Find files and symbols in your codebase
📍 Navigation	cpp_definition cpp_references cpp_hover	Jump to definitions, find references, get type info
📞 Call Analysis	cpp_incoming_calls cpp_outgoing_calls	Trace function relationships
🏗️ Type Hierarchy	cpp_prepare_type_hierarchy cpp_supertypes cpp_subtypes	Analyze inheritance
⚡ Structure	cpp_list_functions cpp_list_classes cpp_get_outline cpp_extract_signatures	Fast structural analysis

🤖 AI Features (Optional)

Setup

1. Get your API key from Google AI Studio
2. Add to your environment (bash):

   export CLANGAROO_AI_API_KEY="your-api-key"
   

O que você obtém

• 📚 Documentação Inteligente: Documentação C++ complexa explicada claramente
• 🔍 Análise de Padrões: Entenda por que e como as funções são chamadas
• 🏛️ Insights de Arquitetura: Identifique padrões de design automaticamente
• 💡 Dicas de Refatoração: Obtenha recomendações de melhoria
• 💰 Custo Eficaz: US$ 3-7/mês de uso típico com cache inteligente

⚙️ Referência de Configuração

Ver todas as opções de configuração

Opções Básicas

• --project PATH - Caminho para a raiz do projeto C++ (obrigatório)
• --log-level LEVEL - Nível de detalhe do log: debug, info, warning, error
• --timeout SECONDS - Tempo limite de solicitação LSP (padrão: 5.0)

Opções de Desempenho

• --warmup - Pré-aquecer o índice abrindo arquivos-chave
• --warmup-limit N - Número de arquivos para aquecer (padrão: 10)
• --wait-for-index - Aguardar a conclusão da indexação do clangd
• --index-timeout SECONDS - Tempo limite para espera de indexação (padrão: 300)
• --index-path PATH - Local personalizado do índice clangd

Opções de IA

• --ai-enabled - Ativar recursos de IA
• --ai-provider PROVIDER - Provedor de IA: gemini-2.5-flash ou gemini-2.5-flash-lite
• --ai-api-key KEY - Chave da API do Google AI
• --ai-cache-days DAYS - Armazenar em cache resumos de IA por N dias (padrão: 7)
• --ai-cost-limit AMOUNT - Limite mensal de custo em USD (padrão: 10,0)
• --ai-analysis-level LEVEL - Profundidade de análise padrão: resumo ou detalhado
• --ai-context-level LEVEL - Profundidade do contexto do código: mínimo, local ou completo

Opções de Hierarquia de Chamadas

• --call-hierarchy-depth DEPTH - Profundidade máxima (1-10, padrão: 3)
• --call-hierarchy-max-calls NUM - Limite total de chamadas (padrão: 100)
• --call-hierarchy-per-level NUM - Chamadas por nível de profundidade (padrão: 25)

📋 Requisitos

• Python 3.10+
• clangd 16+ (brew install llvm ou apt install clangd)
• Projeto C++ com compile_commands.json
• (Opcional) Chave da API do Google AI para recursos de IA

🔧 Solução de Problemas

O Claude não vê as ferramentas

1. Verifique o local do arquivo de configuração e a sintaxe JSON
2. Use caminhos absolutos na configuração
3. Reinicie o Claude Desktop completamente
4. Verifique os logs com --log-level debug

Nenhum resultado de consultas

1. Verifique se compile_commands.json inclui os arquivos
2. Aguarde a indexação: adicione o sinalizador --wait-for-index
3. Teste o clangd diretamente: clangd --check=file.cpp

Problemas de desempenho

• Ative o aquecimento: --warmup --warmup-limit 30
• Use índice compartilhado: --index-path /shared/clangd-index
• Reduza a profundidade da hierarquia de chamadas para bases de código grandes

📄 Licença

Licença MIT - veja o arquivo para detalhes.

🙏 Agradecimentos

• clangd para servidor de linguagem C++
• Tree-sitter para análise de sintaxe
• MCP para a especificação do protocolo
• Google Gemini para recursos de IA

---