Clangaroo

🦘 Clangaroo: Inteligencia de código C++ rápida para LLMs vía MCP

✨ Acerca de

NOTA (enero de 2026): Claude Code ahora tiene soporte integrado para LSPs, lo que hace esto innecesario. Dado que aún puede ser útil en otros entornos agénticos, dejaré el proyecto aquí por ahora.

Clangaroo permite a Claude Code, Gemini CLI y otros agentes de codificación moverse por tu código C++ con facilidad. Clangaroo proporciona búsqueda rápida y directa de símbolos, funciones, definiciones, jerarquías de llamadas, jerarquías de tipos y más para tus mejores amigos LLM.

Clangaroo combina la velocidad del análisis de Tree-sitter con la precisión de clangd LSP, opcionalmente mejorado con IA de Google Gemini Flash para obtener información más profunda. Deja que tus compañeros de IA pasen más tiempo programando y menos tiempo tropezando.

¿Pero POR QUÉ hiciste esto? ❤️ Me encanta usar Claude Code, pero cada vez que se compacta automáticamente y luego empieza a buscar con grep la función en la que hemos estado trabajando durante mucho tiempo, muero un poco por dentro. ¿Pero no hay ya algunos MCPs que hacen esto? ¿Por qué necesitamos otro? Pasé un tiempo buscando y encontré tanto MCP-language-server como Serena, que ambos se ven perfectamente bien. Desafortunadamente, ninguno funcionó para mí 😭

Clangaroo está pensado para ser súper simple y está destinado a "simplemente funcionar".

📚 Tabla de Contenidos

• 🚀 Inicio Rápido
• 🎯 Características
• 💬 Ejemplos de Uso
• 🛠️ Herramientas Disponibles
• 🤖 Características de IA (Opcional)
• ⚙️ Referencia de Configuración
• 📋 Requisitos
• 🔧 Solución de Problemas
• 📄 Licencia
• 🙏 Agradecimientos

🚀 Inicio Rápido

1. Instalar Clangaroo

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

2. Paso de compilación especial para tu proyecto C++

El LSP de clang necesita que hagas esto una 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 .

Esto creará un archivo especial compile_commands.json en la raíz de tu proyecto.

3. Configurar Claude Desktop u otro cliente MCP

¿Sabías que ahora puedes agregar servidores MCP a LM Studio?

🎯 Configuración recomendada con IA:

N.B.: El uso de --ai-enabled utilizará Google Gemini e incurrirá en un pequeño costo a través de tu clave API de Gemini, si se proporciona. Esto suele ser muy menor siempre que uses Gemini Flash o Flash Lite.

Nota: Reemplaza 'command' y 'project' con las rutas correctas para tu sistema, y reemplaza your-google-ai-api-key con tu clave API (si usas una). Si no deseas usar los servicios mejorados con IA, simplemente omite todas las opciones de --ai y la clave 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"
      }
    }
  }
}

📍 Ubicaciones del archivo de configuración de Claude Desktop

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

Profundidad predeterminada del análisis de IA (--ai-analysis-level, predeterminado: summary).

• summary: Resumen rápido con puntos clave
  
• detailed: Análisis completo con ejemplos y contexto
  
  

Profundidad predeterminada del contexto (--ai-context-level, predeterminado: minimal).

• minimal: Solo el símbolo y la documentación inmediata
  
• local: Incluir código circundante en el mismo archivo
  
• full: Incluir dependencias y archivos relacionados
  

4. Reiniciar Claude Desktop

Sal y reinicia Claude. ¡Estás listo para explorar tu código C++! 🎉

5. Agregar servidor MCP a 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:

"Descubre la guarida críptica donde la clase `UserManager` es conjurada desde el vacío."  
"Revela cada rincón sombrío que invoca el temido ritual `summonSoulPayment()`."  
"Expón los poderes impíos heredados por la clase `DatabaseConnection` de sus antiguos ancestros."  
"Analiza la retorcida jerarquía de llamadas de `unleashChaos()` y narra el descenso del programa a la locura."
#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="tu-clave-api"
   

Lo Que Obtienes

• 📚 Documentación Inteligente: Documentación compleja de C++ explicada claramente
• 🔍 Análisis de Patrones: Entiende por qué y cómo se llaman las funciones
• 🏛️ Perspectivas de Arquitectura: Identifica patrones de diseño automáticamente
• 💡 Consejos de Refactorización: Obtén recomendaciones de mejora
• 💰 Rentable: $3-7/mes de uso típico con caché inteligente

⚙️ Referencia de Configuración

Ver todas las opciones de configuración

Opciones Básicas

• --project PATH - Ruta a la raíz del proyecto C++ (requerido)
• --log-level LEVEL - Verbosidad del registro: debug, info, warning, error
• --timeout SECONDS - Tiempo de espera de solicitud LSP (predeterminado: 5.0)

Opciones de Rendimiento

• --warmup - Precalentar el índice abriendo archivos clave
• --warmup-limit N - Número de archivos a precalentar (predeterminado: 10)
• --wait-for-index - Esperar a que se complete la indexación de clangd
• --index-timeout SECONDS - Tiempo de espera para la indexación (predeterminado: 300)
• --index-path PATH - Ubicación personalizada del índice de clangd

Opciones de IA

• --ai-enabled - Habilitar características de IA
• --ai-provider PROVIDER - Proveedor de IA: gemini-2.5-flash o gemini-2.5-flash-lite
• --ai-api-key KEY - Clave API de Google AI
• --ai-cache-days DAYS - Almacenar en caché resúmenes de IA por N días (predeterminado: 7)
• --ai-cost-limit AMOUNT - Límite de costo mensual en USD (predeterminado: 10.0)
• --ai-analysis-level LEVEL - Profundidad de análisis predeterminada: summary o detailed
• --ai-context-level LEVEL - Profundidad del contexto de código: minimal, local o full

Opciones de Jerarquía de Llamadas

• --call-hierarchy-depth DEPTH - Profundidad máxima (1-10, predeterminado: 3)
• --call-hierarchy-max-calls NUM - Límite total de llamadas (predeterminado: 100)
• --call-hierarchy-per-level NUM - Llamadas por nivel de profundidad (predeterminado: 25)

📋 Requisitos

• Python 3.10+
• clangd 16+ (brew install llvm o apt install clangd)
• Proyecto C++ con compile_commands.json
• (Opcional) Clave API de Google AI para características de IA

🔧 Solución de Problemas

Claude no ve las herramientas

1. Verifica la ubicación del archivo de configuración y la sintaxis JSON
2. Usa rutas absolutas en la configuración
3. Reinicia Claude Desktop por completo
4. Revisa los registros con --log-level debug

Sin resultados de las consultas

1. Verifica que compile_commands.json incluya los archivos
2. Espera la indexación: agrega el indicador --wait-for-index
3. Prueba clangd directamente: clangd --check=file.cpp

Problemas de rendimiento

• Habilita el precalentamiento: --warmup --warmup-limit 30
• Usa índice compartido: --index-path /shared/clangd-index
• Reduce la profundidad de la jerarquía de llamadas para bases de código grandes

📄 Licencia

Licencia MIT - consulta el archivo para más detalles.

🙏 Agradecimientos

• clangd por el servidor de lenguaje C++
• Tree-sitter por el análisis de sintaxis
• MCP por la especificación del protocolo
• Google Gemini por las capacidades de IA

---