CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

Compactación de contexto para asistentes de IA de código – Dale a tu IA acceso estructurado y eficiente en tokens a más de 17 lenguajes, incluyendo Elixir, Python, TypeScript, JavaScript, Rust y más.

Hasta un 50% menos de espera · Hasta un 70% menos de tokens · Hasta un 99% menos de explicaciones que dar Contexto más ajustado = Mejor calidad

Instalación rápida · Seguridad · Desarrolladores · Asistentes de IA · Documentación

¿Por qué CICADA?

El problema central: Los asistentes de IA de código desperdician contexto en búsquedas ciegas. Grep vuelca archivos enteros cuando solo necesitas la firma de una función, dejando menos espacio para el razonamiento real.

El enfoque de compactación de contexto

En lugar de volcados de texto sin procesar, CICADA le da a tu IA conocimiento estructurado y preindexado:

Lo que obtienes

• Indexación a nivel de AST – Definiciones de módulos/funciones/clases con firmas, especificaciones, documentación

• Soporte para más de 17 lenguajes – Elixir, Python, TypeScript, JavaScript, Rust, Go, Java, Kotlin, Scala, C/C++, Ruby, C#, Visual Basic, Dart, PHP, Erlang (beta)

• Seguimiento completo de lugares de llamada – Alias, importaciones, referencias dinámicas en todos los lenguajes compatibles

• Búsqueda semántica – Encuentra código por concepto con extracción de palabras clave o embeddings (integración con Ollama)

• Atribución de Git + PR – Descubre por qué existe el código, no solo qué hace

• Análisis de dependencias – Seguimiento bidireccional (qué llama a esto, a qué llama esto)

• Detección automática de lenguaje – Funciona sin problemas en bases de código políglotas

Related MCP server: CodeGraph

Instalación

# 1. Install uv (if needed)
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# In your repo
cicada claude   # or: cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode, cicada zed

uvx cicada-mcp claude   # or cursor, vs

o

claude mcp add cicada uvx cicada-mcp

gemini mcp add cicada uvx cicada-mcp

codex mcp add cicada uvx cicada-mcp

kimi mcp add --transport stdio cicada -- cicada-mcp

Usa la gestión MCP integrada de tu editor para instalar CICADA.

Comandos disponibles después de la instalación:

• cicada [claude|cursor|vs|gemini|codex|opencode|zed] - Configuración interactiva con un solo comando por proyecto

• cicada-mcp - Servidor MCP (iniciado automáticamente por el editor)

• cicada serve - Inicia el servidor de API REST para acceso HTTP a todas las herramientas MCP

• cicada status - Muestra el estado del índice, índice de PR, estado del enlace, archivos de agente, configuraciones MCP

• cicada stats [repo] - Muestra estadísticas de uso (llamadas a herramientas, tokens, tiempos de ejecución)

• cicada watch - Vigila cambios en archivos y reindexa automáticamente

• cicada index - Reindexa código con opciones personalizadas (-f/--force, --keywords, --embeddings, --watch)

• cicada index-pr - Indexa pull requests para atribución de PR

• cicada run [tool] - Ejecuta cualquiera de las 7 herramientas MCP directamente desde la CLI

• cicada agents install - Instala agentes de Claude Code en el directorio ./.claude/

• cicada link [parent_dir] - Enlaza el repositorio actual a un índice existente

• cicada clean - Elimina por completo la integración de cicada de tu carpeta y todos los ajustes

Pregunta a tu asistente:

# Elixir
"Show me the functions in MyApp.User"
"Where is authenticate/2 called?"

# Python
"Show me the AuthService class methods"
"Where is login() used in the codebase?"

# Both languages
"Find code related to API authentication"

Privacidad y seguridad

• 100% local: el análisis y la indexación ocurren en tu máquina; sin acceso externo.

• Sin telemetría: CICADA no recopila uso ni ninguna telemetría.

• Herramientas de solo lectura: los endpoints MCP solo leen el índice; no pueden modificar tu repositorio.

• Acceso opcional a GitHub: las funciones de PR dependen de gh y tu token OAuth existente.

• Disposición de datos:

  ~/.cicada/projects/<repo_hash>/
  ├─ index.json      # modules, functions, call sites, metadata
  ├─ config.yaml     # indexing options + mode
  ├─ hashes.json     # incremental indexing cache
  └─ pr_index.json   # optional PR metadata + reviews

  Tu repositorio solo gana una configuración de editor (.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json o .opencode.json).

Para desarrolladores

Conecta CICADA a tu editor una vez, y cada sesión del asistente hereda el contexto.

Instalación y configuración

cd /path/to/project
cicada claude   # or cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode / cicada zed

Habilitar atribución de PR (opcional)

brew install gh    # or apt install gh
gh auth login
cicada index-pr .     # incremental
cicada index-pr . --clean   # full rebuild

Desbloquea preguntas como "¿Qué PR introdujo la línea 42?" o "¿Qué dijeron los revisores sobre billing.ex?"

Reindexación automática con modo de vigilancia

Habilita la reindexación automática cuando los archivos cambien iniciando el servidor MCP con la bandera --watch:

** .mcp.json**

{
  "mcpServers": {
    "cicada": {
      "command": "cicada-mcp",
      "args": ["--watch"],
      "env": {
        "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>"
      }
    }
  }
}

Cuando el modo de vigilancia está habilitado:

• Un proceso separado monitorea los archivos .ex, .exs (Elixir) y .py (Python) en busca de cambios

• Los cambios se reindexan automáticamente (incremental, rápido)

• Un debounce de 2 segundos evita la reindexación excesiva durante ediciones rápidas

• El proceso de vigilancia se detiene automáticamente cuando el servidor MCP se detiene

• Directorios excluidos: deps, _build, node_modules, .git, assets, priv, .venv, venv

Hoja de referencia de CLI

Nota: La detección de lenguaje es automática – CICADA detecta proyectos de Elixir (mix.exs) y Python (pyproject.toml) automáticamente.

Solución de problemas

Ejecuta el indexador primero:

cicada index /path/to/project

Asegúrate de que la indexación se haya completado correctamente. Verifica ~/.cicada/projects/<hash>/index.json.

Usa el nombre exacto del módulo tal como aparece en el código (ej., MyApp.User, no User).

Si el módulo se agregó recientemente, reindexa:

cicada index .

Lista de verificación de solución de problemas:

1. Verifica que el archivo de configuración exista:

   # For Claude Code
   ls -la .mcp.json
   
   # For Cursor
   ls -la .cursor/mcp.json
   
   # For VS Code
   ls -la .vscode/settings.json

2. Comprueba que las rutas sean absolutas:

   cat .mcp.json
   # Should contain: /absolute/path/to/project
   # Not: ./project or ../project

3. Asegúrate de que el índice exista:

   ls -la ~/.cicada/projects/
   # Should show directory for your project

4. Reinicia el editor por completo (no solo recargar la ventana)

5. Revisa los registros MCP del editor:

   • Claude Code: --debug

   • Cursor: Configuración → MCP → Ver registros

   • VS Code: Panel de salida → MCP

Configuración de GitHub CLI:

# Install GitHub CLI
brew install gh  # macOS
sudo apt install gh  # Ubuntu
# or visit https://cli.github.com/

# Authenticate
gh auth login

# Index PRs
cicada index-pr

Problemas comunes:

• "No se encontró índice de PR" → Ejecuta cicada index-pr .

• "No es un repositorio de GitHub" → Asegúrate de que el repositorio tenga un remoto de GitHub

• Indexación lenta → La primera indexación obtiene todos los PRs; las ejecuciones posteriores son incrementales

• Límite de velocidad → La API de GitHub tiene límites de velocidad; espera y reintenta si alcanzas los límites

Reconstrucción forzada:

cicada index-pr --clean

Error: "Búsqueda por palabras clave no disponible"

Causa: El índice se construyó sin extracción de palabras clave.

Solución:

# Re-index with keyword extraction
cicada index .  # or --keywords

Verificar:

cat ~/.cicada/projects/<hash>/config.yaml
# Should show:
# indexing:
#   mode: keywords

Más detalles: Indexación de PR, Indexación incremental.

Requisitos:

• Node.js (para el indexador scip-python)

• Proyecto Python con pyproject.toml

Configuración inicial: CICADA instala automáticamente scip-python a través de npm en la primera indexación. Esto puede tomar un minuto.

Limitaciones conocidas (Beta):

• La primera indexación puede ser más lenta que la de Elixir (paso de generación de SCIP)

• Los entornos virtuales grandes (.venv) se excluyen automáticamente

• Algunos patrones dinámicos de Python pueden no capturarse

Consejos de rendimiento:

# Ensure .venv is excluded
echo "/.venv/" >> .gitignore

# Use keywords mode for quickest indexing
cicada index --keywords .

Reportar problemas: GitHub Issues con la etiqueta "Python"

Para asistentes de IA

CICADA incluye 7 herramientas MCP enfocadas diseñadas para la exploración eficiente de código en bases de código de Elixir, Python y Erlang.

🧭 ¿Qué herramienta deberías usar?

¿Quieres ver estas herramientas en acción? Consulta Ejemplos completos de flujos de trabajo con consejos profesionales y escenarios del mundo real.

Herramientas principales

query - Descubrimiento inteligente de código (tu punto de partida)

• Detecta automáticamente palabras clave vs patrones

• Filtros: scope (público/privado), recent (últimos 14 días), filter_type (módulos/funciones), match_source (documentación/cadenas)

• Devuelve fragmentos con sugerencias inteligentes de próximos pasos

• Usa path_pattern para filtrar por ubicación

search_module - Análisis profundo de módulos

• Ver API completa: funciones, firmas, especificaciones, documentación

• Para Python: Muestra clases con recuentos de métodos y firmas

• Para Elixir: Muestra funciones con notación de aridad

• Análisis bidireccional:

  • what_calls_it=true → Ver quién usa este módulo (análisis de impacto)

  • what_it_calls=true → Ver de qué depende este módulo

• Compatible con comodines (Elixir: MyApp.*, Python: api.handlers.*) y patrones OR (MyApp.User|MyApp.Post)

• Filtrar por visibilidad (público/privado/todo)

search_function - Seguimiento de uso de funciones

• Encontrar definiciones y todos los sitios de llamada

• what_calls_it=true (predeterminado) → Ver todos los llamantes

• what_it_calls=true → Ver todas las dependencias

• Incluir ejemplos de código con include_usage_examples=true

• Filtrar por usage_type: source, tests o all

Historial de Git (Herramienta Unificada)

git_history - Todas las operaciones de git en una herramienta

• Línea única: git_history("file.ex", start_line=42) → blame + PR

• Rango de líneas: git_history("file.ex", start_line=40, end_line=60) → blame agrupado

• Seguimiento de funciones: git_history("file.ex", function_name="create_user") → evolución

• Historial de archivo: git_history("file.ex") → todos los PRs/commits

• Filtrado por tiempo: recent=true (14d), recent=false (>14d), recent=null (todos)

• Filtrado por autor: author="john"

• Integración automática con índice de PR cuando está disponible

Herramientas Adicionales

expand_result - Profundizar desde resultados de consultas

• Detecta automáticamente módulo vs función

• Muestra detalles completos con ejemplos de uso

• Configurar qué incluir: código, dependencias, llamantes

• Contenedor conveniente alrededor de search_module y search_function

query_jq - Consultas avanzadas al índice

• Consultas directas jq al índice

• Descubrimiento de esquemas con | schema

• Salida compacta (predeterminada) o pretty

• Modo de muestra para resultados grandes

Parámetros detallados + formatos de salida: MCP_TOOLS_REFERENCE.md.

Respuestas Eficientes en Tokens

Todas las herramientas devuelven fragmentos estructurados Markdown/JSON (firmas, sitios de llamada, metadatos de PR) en lugar de archivos completos, manteniendo los prompts ligeros.

Nuevo en v0.5.1: Todas las herramientas ahora usan salida compacta por defecto para minimizar el uso de tokens. Usa verbose=true para salida detallada con documentación y especificaciones completas.

Documentación

• Codebook – Referencia completa de características y guías de usuario

• Workflows – Ejemplos reales encadenando herramientas

• Instalación – Configuración paso a paso para todos los editores

• Contribuir – Guías de desarrollo y arquitectura

• CHANGELOG.md – Notas de lanzamiento

Inmersiones Profundas:

• Análisis de Extracción de Palabras Clave – Internals de búsqueda semántica

• Indexación de PR – Detalles de integración con GitHub

• Benchmarking de Llamadas a Herramientas MCP – Benchmarks de tokens/tiempo

• Descubribilidad de Herramientas – Investigación de mejoras de UX

Roadmap

Estado Actual

Listo para Producción:

• ✅ Elixir (tree-sitter)

• ✅ Python (SCIP)

• ✅ TypeScript (SCIP)

• ✅ JavaScript (SCIP)

• ✅ Rust (SCIP)

Beta:

• 🚧 Erlang (tree-sitter)

• Go (SCIP)

• Java/Kotlin/Scala (SCIP)

• C/C++ (SCIP)

• Ruby (SCIP)

• C#/Visal Basic (SCIP)

• Dart (SCIP)

• PHP (SCIP)

Comparación con Alternativas

| Característica | CICADA | Serena | Codicil (solo Elixir) | | ------------------------ | ----------------------------------- | ------------------------------------------ | ---------------------------------------------------------- | n| Método de Análisis | SCIP (índice estático) | LSP (servidor en tiempo real) | Resúmenes LLM + embeddings | | Edición de Código | ❌ | ✅ | ❌ | | Contexto de Git | ✅ Historial de PR, blame, evolución | ❌ | ❌ | | Uso de Recursos | Bajo (lectura desde disco) | Alto (procesos persistenteservidor) | Medio (llamadas a API) | | Privacidad | 100% local | 100% local | Requiere APIs LLM externas | | Búsqueda Semántica | Ollama local o palabras clave | ❌ | Embeddings OpenAI/Anthropic | | Grafo de Llamadas | Bidireccional con resolución de alias | Basado en LSP | ❌ |

Cuándo elegir CICADA: Quieres operación local-first con contexto git rico (atribución de PR, blame, seguimiento de evolución de funciones) y uso eficiente de tokens.

Cuándo elegir Serena: Necesitas capacidades de edición de código a través de LSP y puedes aceptar mayor uso de recursos.

Cuándo elegir Codicil: Tienes un proyecto Elixir y prefieres resúmenes semánticos potenciados por LLM (solo Elixir). n *** n

Contribuir

git clone https://github.com/wende/cicada.git
cd cicada
uv sync
pytest

Antes de enviar un PR:

• Ejecuta black cicada tests

• Asegúrate de que las pruebas + cobertura pasen (pytest --cov=cicada --cov-report=term-missing)

• Actualiza la documentación si el comportamiento cambia

Aceptamos issues/PRs para:

• Nuevas gramáticas de lenguaje

• Mejoras en la salida de herramientas

• Mejores documentos de incio y tutoriales

Licencia

MIT – ver LICENSE.

Empezar · Reportar Problemas