CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

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

До 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 - Запуск REST API сервера для HTTP-доступа ко всем инструментам MCP

• 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

Открывает вопросы типа "Какой PR ввёл строку 42?" или "Что сказали рецензенты о billing.ex?"

Автоматическая переиндексация в режиме наблюдения

Включите автоматическую переиндексацию при изменении файлов, запустив MCP-сервер с флагом --watch:

** .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)

• Python-проект с pyproject.toml

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

Известные ограничения (бета):

• Первая индексация может быть медленнее, чем для Elixir (этап генерации SCIP)

• Большие виртуальные окружения (.venv) автоматически исключаются

• Некоторые динамические паттерны Python могут не быть захвачены

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

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

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

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

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

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

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

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

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

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 или all

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

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 (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 — примечания к выпускам

Углублённые материалы:

• 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 по:

• Новым грамматикам языков

• Улучшениям вывода инструментов

• Улучшению документации и руководств по началу работы

Лицензия

MIT — см. LICENSE.

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

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