CICADA

mcp-name: io.github.wende/cicada

代码智能：上下文分析、发现和归属

面向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] - 直接从CLI执行7个MCP工具中的任意一个

• cicada agents install - 在./.claude/目录中安装Claude Code代理

• 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说了什么？”之类的问题

使用监视模式自动重新索引

当文件发生变化时，通过使用--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。这可能需要一分钟。

已知限制（测试版）：

• 首次索引可能比Elixir慢（SCIP生成步骤）

• 大型虚拟环境（.venv）会被自动排除

• 某些动态Python模式可能无法被捕获

性能建议：

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

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

报告问题： GitHub问题，并带有“Python”标签

面向AI助手

CICADA提供了7个专注于MCP工具，旨在跨Elixir、Python和Erlang代码库进行高效代码探索。

🧭 你应该使用哪个工具？

想看看这些工具的实际效果？ 查看完整工作流示例，包含专业提示和真实场景。

核心工具

query - 智能代码发现（你的起点）

• 自动检测关键词与模式

• 过滤器：scope（公开/私有）、recent（最近14天）、filter_type（模块/函数）、match_source（文档/字符串）

• 返回带有智能下一步建议的代码片段

• 使用path_pattern按位置过滤

search_module - 深度模块分析

• 查看完整 API：函数、签名、规格、文档

• 对于 Python：显示带有方法数量和签名的类

• 对于 Elixir：显示带有 arity 表示法的函数

• 双向分析：

  • 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 历史（统一工具）

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 – 完整功能参考和用户指南

• 工作流 – 将工具串联起来的真实示例

• 安装 – 所有编辑器的逐步设置

• 贡献 – 开发指南和架构

• CHANGELOG.md – 发布说明

深入阅读：

• 关键词提取分析 – 语义搜索内部机制

• PR 索引 – GitHub 集成详情

• MCP 工具调用基准测试 – 令牌/时间基准

• 工具可发现性 – UX 改进研究

路线图

当前状态

生产就绪：

• ✅ 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）

与替代方案对比

何时选择 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。

开始使用 · 报告问题