CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

Kontextkomprimierung für KI-Code-Assistenten – Geben Sie Ihrer KI strukturierten, tokeneffizienten Zugriff auf 17+ Sprachen, darunter Elixir, Python, TypeScript, JavaScript, Rust und mehr.

Bis zu 50 % weniger Wartezeit · Bis zu 70 % weniger Tokens · Bis zu 99 % weniger Erklärungsaufwand Engerer Kontext = Bessere Qualität

Schnellinstallation · Sicherheit · Entwickler · KI-Assistenten · Dokumentation

Warum CICADA?

Das Kernproblem: KI-Code-Assistenten verschwenden Kontext mit blinden Suchen. Grep wirft ganze Dateien aus, obwohl nur eine Funktionssignatur benötigt wird, und lässt weniger Raum für tatsächliches Denken.

Der Ansatz der Kontextkomprimierung

Anstelle von rohen Textauszügen gibt CICADA Ihrer KI strukturiertes, vorindiziertes Wissen:

Was Sie bekommen

• AST-Level-Indexierung – Modul-/Funktions-/Klassendefinitionen mit Signaturen, Spezifikationen, Dokumentation

• Unterstützung für 17+ Sprachen – Elixir, Python, TypeScript, JavaScript, Rust, Go, Java, Kotlin, Scala, C/C++, Ruby, C#, Visual Basic, Dart, PHP, Erlang (Beta)

• Vollständige Aufrufstellenverfolgung – Aliase, Importe, dynamische Referenzen in allen unterstützten Sprachen

• Semantische Suche – Finden Sie Code nach Konzept mit Stichwortextraktion oder Embeddings (Ollama-Integration)

• Git + PR-Zuordnung – Zeigen Sie auf, warum Code existiert, nicht nur, was

• Abhängigkeitsanalyse – Bidirektionale Verfolgung (was ruft dies auf, was ruft dies auf)

• Automatische Spracherkennung – Funktioniert nahtlos in polyglotten Codebasen

Related MCP server: CodeGraph

Installieren

# 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

oder

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

Verwendet die integrierte MCP-Verwaltung Ihres Editors, um CICADA zu installieren.

Verfügbare Befehle nach der Installation:

• cicada [claude|cursor|vs|gemini|codex|opencode|zed] - Ein-Befehl-interaktive Einrichtung pro Projekt

• cicada-mcp - MCP-Server (wird automatisch vom Editor gestartet)

• cicada serve - Startet REST-API-Server für HTTP-Zugriff auf alle MCP-Tools

• cicada status - Zeigt Indexstatus, PR-Index, Linkstatus, Agentendateien, MCP-Konfigurationen an

• cicada stats [repo] - Zeigt Nutzungsstatistiken (Tool-Aufrufe, Tokens, Ausführungszeiten)

• cicada watch - Überwacht Dateiänderungen und indiziert automatisch neu

• cicada index - Indiziert Code mit benutzerdefinierten Optionen neu (-f/--force, --keywords, --embeddings, --watch)

• cicada index-pr - Indiziert Pull-Requests für die PR-Zuordnung

• cicada run [tool] - Führt eines der 7 MCP-Tools direkt über die CLI aus

• cicada agents install - Installiert Claude Code-Agenten im Verzeichnis ./.claude/

• cicada link [parent_dir] - Verknüpft das aktuelle Repository mit einem bestehenden Index

• cicada clean - Entfernt die CICADA-Integration vollständig aus Ihrem Ordner sowie alle Einstellungen

Fragen Sie Ihren Assistenten:

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

Datenschutz & Sicherheit

• 100 % lokal: Parsing + Indexierung erfolgen auf Ihrem Rechner; kein externer Zugriff.

• Keine Telemetrie: CICADA sammelt keine Nutzungsdaten oder Telemetrie.

• Nur-Lese-Werkzeuge: MCP-Endpunkte lesen nur den Index; sie können Ihr Repository nicht ändern.

• Optionaler GitHub-Zugriff: PR-Funktionen basieren auf gh und Ihrem vorhandenen OAuth-Token.

• Datenlayout:

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

  Ihr Repository erhält lediglich eine Editor-Konfiguration (.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json oder .opencode.json).

Für Entwickler

Binden Sie CICADA einmal in Ihren Editor ein, und jede Assistentensitzung erbt den Kontext.

Installieren & Konfigurieren

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

PR-Zuordnung aktivieren (optional)

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

Ermöglicht Fragen wie „Welcher PR hat Zeile 42 eingeführt?“ oder „Was haben die Reviewer zu billing.ex gesagt?“

Automatische Neuindizierung mit Watch-Modus

Aktivieren Sie die automatische Neuindizierung bei Dateiänderungen, indem Sie den MCP-Server mit dem Flag --watch starten:

** .mcp.json**

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

Wenn der Watch-Modus aktiviert ist:

• Ein separater Prozess überwacht .ex, .exs (Elixir) und .py (Python)-Dateien auf Änderungen

• Änderungen werden automatisch neu indiziert (inkrementell, schnell)

• Eine 2-Sekunden-Entprellung verhindert übermäßige Neuindizierung bei schnellen Bearbeitungen

• Der Watch-Prozess stoppt automatisch, wenn der MCP-Server stoppt

• Ausgeschlossene Verzeichnisse: deps, _build, node_modules, .git, assets, priv, .venv, venv

CLI-Spickzettel

Hinweis: Die Spracherkennung erfolgt automatisch – CICADA erkennt Elixir (mix.exs) und Python (pyproject.toml)-Projekte automatisch.

Fehlerbehebung

Führen Sie zuerst den Indexer aus:

cicada index /path/to/project

Stellen Sie sicher, dass die Indexierung erfolgreich abgeschlossen wurde. Überprüfen Sie ~/.cicada/projects/<hash>/index.json.

Verwenden Sie den genauen Modulnamen, wie er im Code erscheint (z. B. MyApp.User, nicht User).

Wenn das Modul kürzlich hinzugefügt wurde, indizieren Sie neu:

cicada index .

Checkliste zur Fehlerbehebung:

1. Überprüfen, ob die Konfigurationsdatei existiert:

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

2. Prüfen, ob Pfade absolut sind:

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

3. Sicherstellen, dass der Index existiert:

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

4. Editor vollständig neu starten (nicht nur Fenster neu laden)

5. Editor-MCP-Protokolle prüfen:

   • Claude Code: --debug

   • Cursor: Einstellungen → MCP → Protokolle anzeigen

   • VS Code: Ausgabefeld → MCP

GitHub CLI einrichten:

# 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

Häufige Probleme:

• „Kein PR-Index gefunden“ → Führen Sie cicada index-pr . aus

• „Kein GitHub-Repository“ → Stellen Sie sicher, dass das Repository ein GitHub-Remote hat

• Langsame Indexierung → Die erste Indexierung ruft alle PRs ab; nachfolgende Läufe sind inkrementell

• Ratenbegrenzung → Die GitHub-API hat Ratenbegrenzungen; warten Sie und wiederholen Sie den Vorgang, wenn Sie die Grenzen erreichen

Neuerstellung erzwingen:

cicada index-pr --clean

Fehler: „Stichwortsuche nicht verfügbar“

Ursache: Der Index wurde ohne Stichwortextraktion erstellt.

Lösung:

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

Überprüfen:

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

Weitere Details: PR-Indexierung, Inkrementelle Indexierung.

Anforderungen:

• Node.js (für den scip-python-Indexer)

• Python-Projekt mit pyproject.toml

Ersteinrichtung: CICADA installiert scip-python automatisch über npm beim ersten Indexieren. Dies kann eine Minute dauern.

Bekannte Einschränkungen (Beta):

• Die erste Indexierung kann langsamer sein als bei Elixir (SCIP-Generierungsschritt)

• Große virtuelle Umgebungen (.venv) werden automatisch ausgeschlossen

• Einige dynamische Python-Muster werden möglicherweise nicht erfasst

Leistungstipps:

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

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

Probleme melden: GitHub Issues mit dem Label „Python“

Für KI-Assistenten

CICADA liefert 7 spezialisierte MCP-Tools für eine effiziente Code-Erkundung in Elixir-, Python- und Erlang-Codebasen.

🧭 Welches Tool sollten Sie verwenden?

Möchten Sie diese Tools in Aktion sehen? Schauen Sie sich Vollständige Workflow-Beispiele mit Profi-Tipps und realen Szenarien an.

Kernwerkzeuge

query - Intelligente Code-Erkennung (Ihr Ausgangspunkt)

• Erkennt automatisch Stichworte vs. Muster

• Filter: scope (öffentlich/privat), recent (letzte 14 Tage), filter_type (Module/Funktionen), match_source (Dokumentationen/Zeichenketten)

• Gibt Ausschnitte mit intelligenten nächsten Schritten zurück

• Verwenden Sie path_pattern, um nach Ort zu filtern

search_module - Tiefgehende Modulanalyse

• Vollständige API anzeigen: Funktionen, Signaturen, Spezifikationen, Dokumentation

• Für Python: Zeigt Klassen mit Methodenanzahlen und Signaturen

• Für Elixir: Zeigt Funktionen mit Stelligkeitsnotation

• Bidirektionale Analyse:

  • what_calls_it=true → Wer verwendet dieses Modul (Auswirkungsanalyse)

  • what_it_calls=true → Wovon dieses Modul abhängt

• Unterstützt Platzhalter (Elixir: MyApp.*, Python: api.handlers.*) und ODER-Muster (MyApp.User|MyApp.Post)

• Nach Sichtbarkeit filtern (public/private/all)

search_function - Nachverfolgung der Funktionsnutzung

• Definitionen und alle Aufrufstellen finden

• what_calls_it=true (Standard) → Alle Aufrufer anzeigen

• what_it_calls=true → Alle Abhängigkeiten anzeigen

• Codebeispiele mit include_usage_examples=true einfügen

• Nach usage_type filtern: source, tests oder all

Git-Verlauf (Einheitliches Werkzeug)

git_history - Alle Git-Operationen in einem Werkzeug

• Einzelne Zeile: git_history("file.ex", start_line=42) → blame + PR

• Zeilenbereich: git_history("file.ex", start_line=40, end_line=60) → gruppierter blame

• Funktionsverfolgung: git_history("file.ex", function_name="create_user") → Entwicklung

• Dateiverlauf: git_history("file.ex") → alle PRs/Commits

• Zeitfilter: recent=true (14d), recent=false (>14d), recent=null (alle)

• Autorenfilter: author="john"

• Automatische PR-Index-Integration, wenn verfügbar

Zusätzliche Werkzeuge

expand_result - Detailansicht aus Abfrageergebnissen

• Erkennt automatisch Modul vs. Funktion

• Zeigt vollständige Details mit Nutzungsbeispielen

• Konfigurierbar: Code, Abhängigkeiten, Aufrufer

• Praktischer Wrapper um search_module und search_function

query_jq - Erweiterte Indexabfragen

• Direkte jq-Abfragen gegen den Index

• Schemaerkennung mit | schema

• Kompakte (Standard) oder hübsche Ausgabe

• Beispielmodus für große Ergebnisse

Detaillierte Parameter + Ausgabeformate: MCP_TOOLS_REFERENCE.md.

Token-freundliche Antworten

Alle Werkzeuge geben strukturierte Markdown/JSON-Ausschnitte (Signaturen, Aufrufstellen, PR-Metadaten) statt vollständiger Dateien zurück, um Prompts schlank zu halten.

Neu in v0.5.1: Alle Werkzeuge verwenden standardmäßig kompakte Ausgabe, um die Token-Nutzung zu minimieren. Verwenden Sie verbose=true für detaillierte Ausgabe mit vollständiger Dokumentation und Spezifikationen.

Dokumentation

• Codebook – Vollständige Funktionsreferenz und Benutzerhandbücher

• Workflows – Praxisbeispiele, die Werkzeuge miteinander verketten

• Installation – Schritt-für-Schritt-Einrichtung für alle Editoren

• Contributing – Entwicklungsrichtlinien und Architektur

• CHANGELOG.md – Versionshinweise

Vertiefungen:

• Keyword-Extraktionsanalyse – Semantische Suchinterna

• PR-Indexierung – GitHub-Integrationsdetails

• MCP-Werkzeugaufruf-Benchmarking – Token/Zeit-Benchmarks

• Werkzeug-Auffindbarkeit – UX-Verbesserungsforschung

Roadmap

Aktueller Status

Produktionsreif:

• ✅ 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#/Visual Basic (SCIP)

• 🚧 Dart (SCIP)

• 🚧 PHP (SCIP)

Vergleich mit Alternativen

Wann CICADA wählen: Sie möchten einen lokalen Erstbetrieb mit umfangreichem Git-Kontext (PR-Zuordnung, blame, Funktionsentwicklungsverfolgung) und effizienter Token-Nutzung.

Wann Serena wählen: Sie benötigen Codebearbeitungsfähigkeiten durch LSP und können eine höhere Ressourcennutzung akzeptieren.

Wann Codicil wählen: Sie haben ein Elixir-Projekt und bevorzugen LLM-gestützte semantische Zusammenfassungen (nur Elixir).

Mitwirken

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

Vor dem Einreichen eines PRs:

• Führen Sie black cicada tests aus

• Stellen Sie sicher, dass Tests + Abdeckung bestanden werden (pytest --cov=cicada --cov-report=term-missing)

• Aktualisieren Sie die Dokumentation, wenn sich das Verhalten ändert

Wir begrüßen Issues/PRs für:

• Neue Sprachgrammatiken

• Verbesserungen der Werkzeugausgabe

• Bessere Einführungsdokumentation und Tutorials

Lizenz

MIT – siehe LICENSE.

Verschwenden Sie keinen Kontext mit blinden Suchen. Geben Sie Ihrer KI CICADA.

Erste Schritte · Probleme melden