Cicada

CICADA is an MCP server that provides structured code indexing for AI code assistants. Through AST-level indexing, call site tracking, and semantic search, it provides efficient context compression for Elixir, Python, and Erlang code repositories, reducing token usage and improving the quality of code understanding.

Developer tools Knowledge management and memory #Code indexing #Context compression #Semantic search #AI assistant .Python

rating : 2.5 points

downloads : 4.7K

update time : 2025-12-12

Open Site

What is CICADA?

CICADA is a context compression tool specifically designed for AI code assistants. It solves the problem of AI assistants wasting a large amount of context space for blind searches when analyzing code. Through AST-level code indexing, complete call site tracking, and semantic search functions, CICADA enables AI to obtain a more comprehensive understanding of code with fewer token consumptions.

How to use CICADA?

CICADA integrates with various AI code assistants through the Model Context Protocol (MCP). After installation, it automatically indexes your code repository and provides structured responses when the AI assistant needs to query code information. You can directly ask code-related questions in the AI assistant, and CICADA will return accurate and concise answers.

Applicable scenarios

CICADA is particularly suitable for the following scenarios: 1. Exploration and understanding of large code repositories 2. Code refactoring and dependency analysis 3. New developers quickly familiarizing themselves with the code repository 4. AI-assisted code review 5. Dead code detection and cleanup

Main features

AST-level indexing

Deeply parse the abstract syntax tree of the code, extract the definitions, signatures, specifications, and documentation comments of modules, functions, and classes, and establish a complete code structure index.

Complete call site tracking

Track all function calls, alias references, imports, and dynamic references, provide a complete code dependency graph, and support bidirectional dependency analysis.

Semantic search

Intelligent search based on keyword extraction, capable of finding relevant code based on concepts rather than literal matching. For example, searching for 'authentication' can find the verify_credentials function.

Git and PR traceability

Integrate Git history and GitHub PR information, capable of tracing the modification history of code, PR discussions, and review comments, helping to understand the background of code changes.

Dead code detection

Intelligently identify potentially unused functions and code, providing three confidence levels: high, medium, and low, to help safely clean up code.

Multi-language support

Automatically detect and support Elixir, Python, Erlang, and TypeScript projects, providing a unified query interface and consistent response format.

Automatic monitoring mode

Monitor file changes in real-time and automatically incrementally re-index to ensure that the index is always synchronized with the latest code without manual triggering.

Advantages

Improved context efficiency: Reduce waiting time by 50% and save 70% of token usage.

Intelligent code discovery: Semantic search enables AI to understand the intent of code rather than just match literals.

Fully local: All indexing and processing are performed locally to protect code privacy.

Zero-configuration integration: One-click installation allows integration with mainstream AI code assistants.

Incremental indexing: Only re-index changed files, significantly improving efficiency.

Structured responses: Return precise code snippets rather than complete files, reducing context pollution.

Limitations

Time required for initial indexing: The initial indexing of large code repositories may take several minutes.

Memory usage: Indexing large code repositories requires a certain amount of memory space.

Limited language support: Currently, it mainly supports Elixir and Python, and support for other languages is still being improved.

Requires a local environment: It must be installed and run in the development environment.

Python indexing depends on Node.js: Python projects require a Node.js environment to run the SCIP indexer.

How to use

Install the uv tool

If uv is not installed yet, you need to install this Python package management tool first.

Install the CICADA MCP server

Use uv to install the CICADA MCP server.

Enter the project directory and configure

Enter your code project directory and select the corresponding configuration command according to the AI assistant you are using.

Start using

After configuration is complete, you can directly ask code-related questions in the AI assistant.

Usage examples

Explore a new code repository

When you need to quickly understand the structure and main components of a new code repository.

Find function call relationships

When you need to understand how a function is used in the code repository.

Dependency analysis before code refactoring

Before modifying an important function, understand its dependencies and scope of influence.

Understand code change history

When you need to understand the background and reasons for code modifications.

Clean up unused code

Identify potentially unused functions during the code cleanup process.

Frequently asked questions

Will CICADA collect my code data?

Which programming languages does CICADA support?

How long does it take to index a large code repository?

How to update the index to reflect code changes?

Will CICADA affect my development environment?

What conditions are required for the PR traceability function?

Why does Python indexing require Node.js?

How to uninstall CICADA?

Related resources

GitHub repository

CICADA's source code, issue tracking, and contribution guidelines.

MCP tool reference documentation

Detailed description of MCP tool parameters and output formats.

Workflow examples

Examples of actual usage scenarios and best practices.

Model Context Protocol official website

Official documentation and specifications of the MCP protocol.

Change log

Version update records and function changes of CICADA.

🚀 CICADA

Code Intelligence: Contextual Analysis, Discovery, and Attribution

CICADA offers contextual compaction for AI code assistants. It enables your AI to access Elixir, Python, and Erlang codebases in a structured and token - efficient manner.

Up to 50% less waiting · Up to 70% less tokens · Up to 99% less explanations to do Tighter context = Better Quality

Quick Install · Security · Developers · AI Assistants · Docs

🚀 Quick Start

CICADA addresses the core problem that AI code assistants often waste context on blind searches. Traditional methods like grep dump entire files, leaving less room for actual reasoning. CICADA, on the other hand, provides structured, pre - indexed knowledge to your AI.

✨ Features

The Context Compaction Approach

Instead of raw text dumps, CICADA gives your AI structured, pre - indexed knowledge:

Traditional Search	CICADA
Grep dumps entire files	Returns only signatures + call sites
Misses aliased imports	Tracks all reference types
No semantic understanding	Keyword search finds `verify_credentials` when you ask for "authentication"

What You Get

AST - level indexing – Module/function/class definitions with signatures, specs, docs
Complete call - site tracking – Aliases, imports, dynamic references across Elixir and Python
Semantic search – Find code by concept, not just literal strings
Git + PR attribution – Surface why code exists, not just what
Dead - code detection – Safe refactors with dependency analysis
Automatic language detection – Works seamlessly with both Elixir and Python

📦 Installation

# 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

Try before installing permanently

Runs CICADA on demand (worse indexing quality, but zero install).

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

Uses your editor's built - in MCP management to install CICADA.

Available commands after installation:

cicada [claude|cursor|vs|gemini|codex|opencode] - One - command interactive setup per project
cicada-mcp - MCP server (auto - started by editor)
cicada status - Show index status, PR index, link status, agent files, MCP configs
cicada stats [repo] - Display usage statistics (tool calls, tokens, execution times)
cicada watch - Watch for file changes and automatically reindex
cicada index - Re - index code with custom options (-f/--force + --fast/--regular/--max, --watch)
cicada index-pr - Index pull requests for PR attribution
cicada find-dead-code - Find potentially unused functions
cicada run [tool] - Execute any of the 7 MCP tools directly from 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

You can 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 + keyword tier
├─ 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

Enable PR Attribution (optional)

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

This 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.

Command	Purpose	Run When
`cicada claude`	Configure MCP + incremental re - index	First setup, after local changes
`cicada status`	Check index health, link status, agent files	After setup, troubleshooting
`cicada stats`	View usage statistics and token metrics	Monthly reviews, optimization
`cicada watch`	Monitor files and auto - reindex on changes	During active development
`cicada index --force --regular .`	Full rebuild w/ semantic keywords	After large refactors or enabling AI tier
`cicada index-pr .`	Sync PR metadata/reviews	After new PRs merge
`cicada find-dead-code --min-confidence high`	List unused public functions	Cleanup sprints

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:

Verify configuration file exists:

# For Claude Code
ls -la .mcp.json

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

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

Check paths are absolute:

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

Ensure index exists:

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

Restart editor completely (not just reload window)
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

Force rebuild:

cicada index-pr --clean

Keyword Search Not Working

Error: "Keyword search not available"

Cause: Index was built without keyword extraction.

Solution:

# Re - index with keyword extraction
cicada index .  # or --fast or --max

Verify:

cat ~/.cicada/projects/<hash>/config.yaml
# Should show keyword_extraction: enabled

More detail: docs/PR_INDEXING.md, docs/08-INCREMENTAL_INDEXING.md.

Python Indexing

Requirements:

Node.js (for scip - python indexer)
Python project with pyproject.toml

First - time setup: CICADA automatically installs scip - python via npm on first index. This may take a minute.

Known limitations (Beta):

First indexing may be slower than Elixir (SCIP generation step)
Large virtual environments (.venv) are automatically excluded
Some dynamic Python patterns may not be captured

Performance tips:

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

# Use --fast tier for quicker indexing
cicada index --fast .

Report issues: GitHub Issues with "Python" label

🤖 For AI Assistants

CICADA ships 7 focused MCP tools designed for efficient code exploration across Elixir, Python, and Erlang codebases.

🧭 Which Tool Should You Use?

Need	Tool	Notes
Start exploring	`query`	🚀 START HERE - Smart discovery with keywords/patterns + filters (scope, recent, path)
View a module's complete API	`search_module`	Functions, signatures, specs, docs. Use `what_calls_it`/`what_it_calls` for bidirectional analysis
Find where a function is used	`search_function`	Definition + all call sites. Supports wildcards (`*`) and OR (`\|`) patterns
Track git history	`git_history`	Unified tool: blame, commits, PRs, function evolution (replaces 4 legacy tools)
Find dead code	`find_dead_code`	Identify potentially unused functions with confidence levels
Drill down into results	`expand_result`	Auto - expands modules or functions from query results
Advanced index queries	`query_jq`	Custom jq queries for power users

Want to see these tools in action? Check out Complete Workflow Examples with pro tips and real - world scenarios.

Core Tools

query - Smart code discovery (your starting point)

Automatically detects keywords vs patterns
Filters: scope (public/private), recent (last 14 days), filter_type (modules/functions), match_source (docs/strings)
Returns snippets with smart next - step suggestions
Use path_pattern to filter by location

search_module - Deep module analysis

View complete API: functions, signatures, specs, docs
For Python: Shows classes with method counts and signatures
For Elixir: Shows functions with arity notation
Bidirectional analysis:
- what_calls_it=true → See who uses this module (impact analysis)
- what_it_calls=true → See what this module depends on
Supports wildcards (Elixir: MyApp.*, Python: api.handlers.*) and OR patterns (MyApp.User|MyApp.Post)
Filter by visibility (public/private/all)

search_function - Function usage tracking

Find definitions and all call sites
what_calls_it=true (default) → See all callers
what_it_calls=true → See all dependencies
Include code examples with include_usage_examples=true
Filter by usage_type: source, tests, or all

Git History (Unified Tool)

git_history - All git operations in one tool

Single line: git_history("file.ex", start_line=42) → blame + PR
Line range: git_history("file.ex", start_line=40, end_line=60) → grouped blame
Function tracking: git_history("file.ex", function_name="create_user") → evolution
File history: git_history("file.ex") → all PRs/commits
Time filtering: recent=true (14d), recent=false (>14d), recent=null (all)
Author filtering: author="john"
Automatic PR index integration when available

Additional Tools

expand_result - Drill down from query results

Auto - detects module vs function
Shows complete details with usage examples
Configure what to include: code, dependencies, callers
Convenient wrapper around search_module and search_function

find_dead_code - Code cleanup analysis

Three confidence levels (high, medium, low)
Smart detection of callbacks and behaviors
Recognition of dynamic call patterns
Module - level grouping with line numbers
Excludes test files and @impl functions

query_jq - Advanced index queries

Direct jq queries against the index
Schema discovery with | schema
Compact (default) or pretty output
Sample mode for large results

Detailed parameters + output formats: MCP_TOOLS_REFERENCE.md.

Token - Friendly Responses

All tools return structured Markdown/JSON snippets (signatures, call sites, PR metadata) instead of full files, keeping prompts lean.

New in v0.5.1: All tools now use compact output by default to minimize token usage. Use verbose=true for detailed output with full docs and specs.

📚 Documentation

docs/17-WORKFLOW_EXAMPLES.md
docs/12-TOOL_DISCOVERABILITY_TASKS.md.
CHANGELOG.md – release notes.
docs/01-KEYWORD_EXTRACTION_ANALYSIS.md – semantic search internals.
docs/09-PR_INDEXING.md – GitHub integration details.
docs/16-MCP_TOOL_CALL_BENCHMARKING.md – token/time benchmarks.

🗺️ Roadmap

Current Status

✅ Elixir
✅ Python
🚧 Erlang - Beta
🧪 TypeScript - Experimental

What's Next

Stabilize Erlang support based on user feedback
TypeScript/JavaScript support via SCIP
Shared/team indexes for collaborative environments
Performance optimizations for large codebases

🤝 Contributing

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

Before submitting a PR:

Run black cicada tests
Ensure tests + coverage pass (pytest --cov=cicada --cov-report=term-missing)
Update docs if behaviour changes

We welcome issues/PRs for:

New language grammars
Tool output improvements
Better onboarding docs and tutorials

📄 License

MIT – see LICENSE.

Stop wasting context on blind searches. Give your AI CICADA.

Get Started · Report Issues

Notion Api MCP

Certified

A Python-based MCP Server that provides advanced to-do list management and content organization functions through the Notion API, enabling seamless integration between AI models and Notion.

Markdownify is a multi-functional file conversion service that supports converting multiple formats such as PDFs, images, audio, and web page content into Markdown format.

TypeScript

30.7K

5 points

Duckduckgo MCP Server

Certified

The DuckDuckGo Search MCP Server provides web search and content scraping services for LLMs such as Claude.

The GitLab MCP server is a project based on the Model Context Protocol that provides a comprehensive toolset for interacting with GitLab accounts, including code review, merge request management, CI/CD configuration, and other functions.

UnityMCP is a Unity editor plugin that implements the Model Context Protocol (MCP), providing seamless integration between Unity and AI assistants, including real - time state monitoring, remote command execution, and log functions.

27.4K

5 points

Figma Context MCP

Framelink Figma MCP Server is a server that provides access to Figma design data for AI programming tools (such as Cursor). By simplifying the Figma API response, it helps AI more accurately achieve one - click conversion from design to code.

A Gmail automatic authentication MCP server designed for Claude Desktop, supporting Gmail management through natural language interaction, including complete functions such as sending emails, label management, and batch operations.

Context7 MCP is a service that provides real-time, version-specific documentation and code examples for AI programming assistants. It is directly integrated into prompts through the Model Context Protocol to solve the problem of LLMs using outdated information.

TypeScript

87.0K

4.7 points

Zhiqi Future, Your AI Solution Think Tank

English 简体中文繁體中文にほんご

Cicada

Overview

Installation

Content Details

Alternatives

What is CICADA?

How to use CICADA?

Applicable scenarios

Main features

How to use

Usage examples

Frequently asked questions

Related resources

Installation

🚀 CICADA

🚀 Quick Start

✨ Features

The Context Compaction Approach

What You Get

📦 Installation

🔒 Privacy & Security

👨‍💻 For Developers

Install & Configure

Enable PR Attribution (optional)

Automatic Re - indexing with Watch Mode

CLI Cheat Sheet

Troubleshooting

🤖 For AI Assistants

🧭 Which Tool Should You Use?

Core Tools

Git History (Unified Tool)

Additional Tools

Token - Friendly Responses

📚 Documentation

🗺️ Roadmap

Current Status

What's Next

🤝 Contributing

📄 License

Alternatives