CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

Умное сжатие контекста для ИИ-ассистентов программистов – Дайте вашему ИИ структурированный, эффективный по токенам доступ к 17+ языкам программирования, включая Elixir, Python, TypeScript, JavaScript, Rust и многие другие.

До 50% меньше времени ожидания · До 70% меньше токенов · До 99% меньше пояснений необходимо делать Более плотный контекст = Лучшее качество

Быстрая установка · Безопасность · Разработчикам · ИИ-ассистентам · Документация

Почему CICADA?

Основная проблема: ИИ-ассистенты программистов тратят контекст на бесконечные поиски с помощью grep. Инструмент выводит целые файлы, когда вам нужна только сигнатура функции, что ограничивает пространство для реального анализа.

Подход умного сжатия контекста

Вместо сырых дампов текста CICADA предоставляет вашему ИИ структурированную, заранее проиндексированную информацию:

Что вы получаете

• Индексация на уровне AST – Определения модулей/функций/классов с сигнатурами, спецификациями и документацией
• Поддержка 17+ языков – Elixir, Python, TypeScript, JavaScript, Rust, Go, Java, Kotlin, Scala, C/C++, Ruby, C#, Visual Basic, Dart, PHP, Erlang (в бета-версии)
• Полный контроль точек вызова – Алиасы, импорты, динамические ссылки во всех поддерживаемых языках
• Семантический поиск – Находите код по смыслу с помощью извлечения ключевых слов или эмбеддингов (интеграция с Ollama)
• Атрибуция через Git + PR – Понимание почему существует код, а не только что он делает
• Анализ зависимостей – Двунаправленный контроль (кто вызывает это, что это вызывает)
• Автоматическое определение языка – Бесшовная работа с полиглотными кодовыми базами

Установка

# 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

Запускает CICADA по запросу (менее качественная индексация, но без установки).

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 - Запуск REST API-сервера для HTTP-доступа ко всем MCP-инструментам - cicada status - Показать статус индексации, индекс PR, статус ссылок, файлы агентов, конфигурации MCP - cicada stats [repo] - Отображение статистики использования (вызовы инструментов, токены, времена выполнения) - cicada watch - Отслеживание изменений файлов и автоматическая переиндексация - cicada index - Переиндексация кода с настраиваемыми параметрами (-f/--force, --keywords, --embeddings, --watch) - cicada index-pr - Индексация pull-запросов для атрибуции PR - cicada run [tool] - Выполнение любого из 7 MCP-инструментов напрямую из CLI - cicada agents install - Install Claude Code agents to ./.claude/ directory - cicada link [parent_dir] - Links current repository to an existing index - cicada clean - Completely removes cicada integration from your folder as well as all settings

Ask your assistant:

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

Privacy & Security

• 100% local: parsing + indexing happen on your machine; no external access.
• No telemetry: CICADA doesn't collect usage or any telemetry.
• Read-only tools: MCP endpoints only read the index; they can't change your repo.
• Optional GitHub access: PR features rely on gh and your existing OAuth token.
• Data layout: ~/.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 Your repo only gains an editor config (.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json, or .opencode.json).

For Developers

Wire CICADA into your editor once, and every assistant session inherits the context.

Install & Configure

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

Enable PR Attribution (optional)

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

Unlocks questions like "Which PR introduced line 42?" or "What did reviewers say about billing.ex?"

Automatic Re-indexing with Watch Mode

Enable automatic reindexing when files change by starting the MCP server with the --watch flag:

** .mcp.json**

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

When watch mode is enabled: - A separate process monitors .ex, .exs (Elixir) and .py (Python) files for changes - Changes are automatically reindexed (incremental, fast) - 2-second debounce prevents excessive reindexing during rapid edits - The watch process stops automatically when the MCP server stops - Excluded directories: deps, _build, node_modules, .git, assets, priv, .venv, venv

CLI Cheat Sheet

Note: Language detection is automatic – CICADA detects Elixir (mix.exs) and Python (pyproject.toml) projects automatically.

Troubleshooting

"Index file not found"

Run the indexer first:

cicada index /path/to/project

Ensure indexing completed successfully. Check for ~/.cicada/projects/<hash>/index.json.

"Module not found"

Use the exact module name as it appears in code (e.g., MyApp.User, not User).

If module was recently added, re-index:

cicada index .

MCP Server Won't Connect

Troubleshooting checklist:

1. Verify configuration file exists: ```bash # For Claude Code ls -la .mcp.json

# For Cursor ls -la .cursor/mcp.json

# For VS Code ls -la .vscode/settings.json ```

1. Check paths are absolute: bash cat .mcp.json # Should contain: /absolute/path/to/project # Not: ./project or ../project

2. Ensure index exists: bash ls -la ~/.cicada/projects/ # Should show directory for your project

3. Restart editor completely (not just reload window)

4. Check editor MCP logs: - Claude Code: --debug - Cursor: Settings → MCP → View Logs - VS Code: Output panel → MCP

PR Features Not Working

Setup 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

Common issues: - "No PR index found" → Run cicada index-pr . - "Not a GitHub repository" → Ensure repo has GitHub remote - Slow indexing → First-time indexing fetches all PRs; subsequent runs are incremental - Rate limiting → GitHub API has rate limits; wait and retry if you hit limits

Принудительная перестройка индекса:

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, Инкрементальная индексация.

Индексация Python

Требования: - Node.js (для индексатора scip-python) - Проект Python с pyproject.toml

Первичная настройка: CICADA автоматически устанавливает scip-python через npm при первой индексации. Это может занять минуту.

Известные ограничения (Beta): - Первая индексация может быть медленнее, чем Elixir (этап генерации SCIP) - Большие виртуальные окружения (.venv) автоматически исключаются - Некоторые динамические паттерны Python могут не быть захвачены

Советы по производительности:

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

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

Сообщать о проблемах: GitHub Issues с меткой «Python»

Для ИИ-ассистентов

CICADA поставляется с 7 специализированными MCP-инструментами, предназначенными для эффективного исследования кода в проектах Elixir, Python и Erlang.

🧭 Какой инструмент использовать?

Хотите увидеть эти инструменты в действии? Посмотрите Примеры полного рабочего процесса с профессиональными советами и реальными сценариями.

Основные инструменты

query — Умное обнаружение кода (ваша точка входа) - Автоматически определяет ключевые слова vs паттерны - Фильтры: 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.*) и ИЛИ паттерны (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, или all

История Git (Унифицированный Инструмент)

git_history — Все операции с git в одном инструменте - Одна строка: 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 (14d), recent=false (>14d), recent=null (все) - Фильтрация по автору: author="john" - Автоматическая интеграция с индексом PR при наличии

Дополнительные Инструменты

expand_result — Углубление из результатов запросов - Автоматически определяет модуль vs функцию - Показывает полные детали с примерами использования - Настройка включения: код, зависимости, вызывающие - Удобный обёртка вокруг 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 – Примечания к выпускам

Глубокие погружения: - Keyword Extraction Analysis – Внутренности семантического поиска - PR Indexing – Детали интеграции с GitHub - MCP Tool Call Benchmarking – Бенчмарки токенов/времени - Tool Discoverability – Исследование улучшений 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) - Обновите документацию при изменении поведения

Мы приветствуем issues/PR для: - Новых грамматик языков - Улучшения вывода инструментов - Лучшей документации и Tutorials для начала работы

Лицензия

MIT – см. LICENSE.

Перестаньте тратить контекст на случайные поиски. Дайте своему ИИ CICADA.

Начать · Сообщить о проблемах