CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

AIコードアシスタント向けコンテキスト圧縮 – Elixir、Python、TypeScript、JavaScript、Rustなど17以上の言語に対応した、構造化されたトークン効率の高いアクセスをAIに提供します。

待ち時間最大50%削減 · トークン最大70%削減 · 説明作業最大99%削減 コンテキストがコンパクト = 品質向上

クイックインストール · セキュリティ · 開発者向け · AIアシスタント向け · ドキュメント

CICADAの理由

中核的な問題: AIコードアシスタントは、盲目的な検索にコンテキストを浪費します。grepは関数シグネチャだけが必要な場合でもファイル全体をダンプし、実際の推論に使える余地が減ってしまいます。

コンテキスト圧縮アプローチ

生のテキストダンプの代わりに、CICADAはAIに構造化され、事前にインデックス化された知識を提供します:

得られるもの

• ASTレベルのインデックス – シグネチャ、スペック、ドキュメントを含むモジュール/関数/クラス定義

• 17以上の言語サポート – Elixir、Python、TypeScript、JavaScript、Rust、Go、Java、Kotlin、Scala、C/C++、Ruby、C#、Visual Basic、Dart、PHP、Erlang（ベータ版）

• 完全な呼び出し箇所追跡 – サポートされているすべての言語におけるエイリアス、インポート、動的参照

• セマンティック検索 – キーワード抽出または埋め込み（Ollama統合）による概念からのコード検索

• Git + PR属性 – コードが なぜ 存在するのかを明らかにする（単なる内容だけでなく）

• 依存関係分析 – 双方向追跡（これを呼び出すもの、これが呼び出すもの）

• 自動言語検出 – 複数言語のコードベースでシームレスに動作

Related MCP server: CodeGraph

インストール

# 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

または

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

エディタの組み込みMCP管理を使用してCICADAをインストールします。

インストール後に利用可能なコマンド:

• cicada [claude|cursor|vs|gemini|codex|opencode|zed] - プロジェクトごとのワンコマンド対話型セットアップ

• cicada-mcp - MCPサーバー（エディタで自動起動）

• cicada serve - すべてのMCPツールにHTTPアクセスするためのREST APIサーバーを起動

• cicada status - インデックスステータス、PRインデックス、リンクステータス、エージェントファイル、MCP設定を表示

• cicada stats [repo] - 使用統計（ツール呼び出し、トークン、実行時間）を表示

• cicada watch - ファイル変更を監視し、自動的に再インデックス

• cicada index - カスタムオプション（-f/--force、--keywords、--embeddings、--watch）でコードを再インデックス

• cicada index-pr - PR属性のためにプルリクエストをインデックス

• cicada run [tool] - 7つのMCPツールのいずれかをCLIから直接実行

• cicada agents install - Claude Codeエージェントを ./.claude/ ディレクトリにインストール

• cicada link [parent_dir] - 現在のリポジトリを既存のインデックスにリンク

• cicada clean - フォルダからcicada統合とすべての設定を完全に削除

アシスタントに尋ねる:

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

プライバシーとセキュリティ

• 100%ローカル: 解析とインデックス作成はマシン上で行われます。外部アクセスはありません。

• テレメトリなし: CICADAは使用状況やテレメトリを収集しません。

• 読み取り専用ツール: MCPエンドポイントはインデックスを読み取るのみで、リポジトリを変更することはできません。

• オプションのGitHubアクセス: PR機能は gh と既存のOAuthトークンに依存します。

• データ構成:

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

  リポジトリにはエディタ設定（.mcp.json、.cursor/mcp.json、.vscode/settings.json、.gemini/settings.json、.codex/mcp.json、または .opencode.json）のみが追加されます。

開発者向け

エディタに一度CICADAを組み込めば、すべてのアシスタントセッションがコンテキストを継承します。

インストールと設定

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

PR属性の有効化（オプション）

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

「42行目を導入したPRはどれ？」や「レビュアーは billing.ex について何と言ったか？」といった質問が可能になります。

ウォッチモードによる自動再インデックス

--watch フラグを指定してMCPサーバーを起動することで、ファイル変更時の自動再インデックスが有効になります:

.mcp.json

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

ウォッチモードが有効な場合:

• 別のプロセスが .ex、.exs（Elixir）および .py（Python）ファイルの変更を監視します

• 変更は自動的に再インデックスされます（増分的、高速）

• 2秒のデバウンスにより、急な編集時の過剰な再インデックスを防ぎます

• MCPサーバーが停止すると、ウォッチプロセスも自動的に停止します

• 除外ディレクトリ: deps、_build、node_modules、.git、assets、priv、.venv、venv

CLIチートシート

注: 言語検出は自動です – CICADAはElixir（mix.exs）およびPython（pyproject.toml）プロジェクトを自動的に検出します。

トラブルシューティング

最初にインデクサーを実行してください:

cicada index /path/to/project

インデックス作成が正常に完了したことを確認してください。~/.cicada/projects/<hash>/index.json を確認してください。

コードに表示されている正確なモジュール名を使用してください（例: MyApp.User、User ではありません）。

モジュールが最近追加された場合は、再インデックスしてください:

cicada index .

トラブルシューティングチェックリスト:

1. 設定ファイルが存在することを確認:

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

2. パスが絶対パスであることを確認:

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

3. インデックスが存在することを確認:

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

4. エディタを完全に再起動（ウィンドウの再読み込みのみではありません）

5. エディタのMCPログを確認:

   • Claude Code: --debug

   • Cursor: 設定 → MCP → ログを表示

   • VS Code: 出力パネル → MCP

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

よくある問題:

• 「PRインデックスが見つかりません」→ cicada index-pr . を実行

• 「GitHubリポジトリではありません」→ リポジトリにGitHubリモートがあることを確認

• インデックスが遅い → 初回インデックスはすべてのPRを取得します。以降の実行は増分的です

• レート制限 → GitHub APIにはレート制限があります。制限に達した場合は待機して再試行

強制再構築:

cicada index-pr --clean

エラー: 「キーワード検索は利用できません」

原因: インデックスがキーワード抽出なしで構築されました。

解決策:

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

確認:

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

詳細: PRインデックス、増分インデックス

要件:

• Node.js（scip-pythonインデクサー用）

• pyproject.tomlを含むPythonプロジェクト

初回セットアップ: CICADAは初回インデックス時にnpm経由でscip-pythonを自動的にインストールします。これには1分かかる場合があります。

既知の制限（ベータ版）:

• 初回のインデックスはElixirよりも遅い場合があります（SCIP生成ステップ）

• 大規模な仮想環境（.venv）は自動的に除外されます

• 一部の動的Pythonパターンは捕捉されない可能性があります

パフォーマンスのヒント:

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

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

問題を報告: 「Python」ラベルを付けて GitHub Issues へ

AIアシスタント向け

CICADAは、Elixir、Python、およびErlangコードベースでの効率的なコード探索のために設計された7つの焦点を絞ったMCPツールを提供します。

🧭 どのツールを使うべきか？

これらのツールの動作を確認したいですか？ 完全なワークフロー例 でプロのヒントと実際のシナリオをご覧ください。

コアツール

query - スマートコード発見（出発点）

• キーワードとパターンを自動検出

• フィルター: scope（public/private）、recent（過去14日間）、filter_type（modules/functions）、match_source（docs/strings）

• スマートな次のステップの提案を含むスニペットを返す

• path_pattern を使用して場所でフィルタリング

search_module - 深いモジュール分析

• 完全なAPIを表示: 関数、シグネチャ、仕様、ドキュメント

• Python: メソッド数とシグネチャを持つクラスを表示

• Elixir: アリティ表記で関数を表示

• 双方向解析:

  • what_calls_it=true → このモジュールを使用している箇所を確認（影響分析）

  • what_it_calls=true → このモジュールが依存しているものを確認

• ワイルドカード（Elixir: MyApp.*、Python: api.handlers.*）とORパターン（MyApp.User|MyApp.Post）をサポート

• 可視性（public/private/all）でフィルタリング

search_function - 関数使用状況の追跡

• 定義と呼び出し箇所をすべて検索

• what_calls_it=true（デフォルト）→ すべての呼び出し元を確認

• what_it_calls=true → すべての依存関係を確認

• include_usage_examples=true でコード例を含める

• usage_type でフィルタ: source、tests、またはすべて

Git履歴（統合ツール）

git_history - すべてのGit操作を1つのツールで

• 単一行: git_history("file.ex", start_line=42) → blame + PR

• 行範囲: git_history("file.ex", start_line=40, end_line=60) → グループ化されたblame

• 関数追跡: git_history("file.ex", function_name="create_user") → 進化

• ファイル履歴: git_history("file.ex") → すべてのPR/コミット

• 時間フィルタ: recent=true（14日）、recent=false（14日超）、recent=null（すべて）

• 著者フィルタ: author="john"

• 利用可能な場合、自動PRインデックス統合

追加ツール

expand_result - クエリ結果からドリルダウン

• モジュールと関数を自動検出

• 使用例を含む完全な詳細を表示

• 含める内容を設定: コード、依存関係、呼び出し元

• search_module と search_function の便利なラッパー

query_jq - 高度なインデックスクエリ

• インデックスに対する直接のjqクエリ

• | schema でスキーマ探索

• コンパクト（デフォルト）または整形出力

• 大きな結果のためのサンプルモード

詳細なパラメータと出力形式: MCP_TOOLS_REFERENCE.md.

トークンに優しいレスポンス

すべてのツールは、完全なファイルではなく構造化されたMarkdown/JSONスニペット（シグネチャ、呼び出し箇所、PRメタデータ）を返すため、プロンプトを簡潔に保てます。

v0.5.1の新機能: すべてのツールはデフォルトでコンパクト出力を使用し、トークン使用量を最小限に抑えるようになりました。詳細なドキュメントと仕様を含む完全な出力には verbose=true を使用してください。

ドキュメント

• Codebook – 完全な機能リファレンスとユーザーガイド

• Workflows – ツールを連鎖させる実世界の例

• Installation – すべてのエディタ向けのステップバイステップ設定

• Contributing – 開発ガイドラインとアーキテクチャ

• CHANGELOG.md – リリースノート

深掘り:

• キーワード抽出分析 – セマンティック検索の内部動作

• PRインデックス – GitHub統合の詳細

• MCPツール呼び出しベンチマーク – トークン/時間ベンチマーク

• ツール発見可能性 – UX改善のリサーチ

ロードマップ

現在のステータス

本番対応:

• ✅ Elixir (tree-sitter)

• ✅ Python (SCIP)

• ✅ TypeScript (SCIP)

• ✅ JavaScript (SCIP)

• ✅ Rust (SCIP)

ベータ版:

• 🚧 Erlang (tree-sitter)

• 🚧 Go (SCIP)

• 🚧 Java/Kotlin/Scala (SCIP)

• 🚧 C/C++ (SCIP)

• 🚧 Ruby (SCIP)

• 🚧 C#/Visual Basic (SCIP)

• 🚧 Dart (SCIP)

• 🚧 PHP (SCIP)

代替手段との比較

CICADAを選ぶべき場合: リッチなGitコンテキスト（PR帰属、blame、関数進化追跡）と効率的なトークン使用量を備えたローカルファーストの運用が必要な場合。

Serenaを選ぶべき場合: LSPによるコード編集機能が必要で、より高いリソース使用量を受け入れられる場合。

Codicilを選ぶべき場合: Elixirプロジェクトがあり、LLMによるセマンティックサマリーを好む場合（Elixir専用）。

コントリビューション

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

PRを提出する前に:

• black cicada tests を実行

• テストとカバレッジがパスすることを確認（pytest --cov=cicada --cov-report=term-missing）

• 動作が変更された場合はドキュメントを更新

以下のissue/PRを歓迎します:

• 新しい言語の文法

• ツール出力の改善

• より良いオンボーディングドキュメントとチュートリアル

ライセンス

MIT – LICENSE を参照。

盲目的な検索でコンテキストを無駄にしないでください。あなたのAIにCICADAを。

はじめる · 問題を報告