cicada (Wende)

蝉

mcp名称：io.github.wende/cacada

C颂歌 一、智能： C原文 A.分析， D发现，以及 A.分配

AI代码助手的上下文压缩 让你的AI结构化、令牌高效地访问17多种语言，包括Elixir、Python、TypeScript、JavaScript、Rust等。

等待时间减少高达50%·代币减少高达70%·要做的解释减少高达99% 更紧密的上下文=更好的质量

](https://www.python.org/downloads/)   

     


快速安装 · 安全 · 开发者 · 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归因 –表面 *为什么* 代码存在，而不仅仅是什么
• 依赖性分析 双向跟踪（这叫什么，这叫什么）
• 自动语言检测 –跨多语言代码库无缝工作

______________________________________________________________________

安装

# 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

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

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服务器，以便对所有MCP工具进行HTTP访问
• 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 Code代理安装到 ./.claude/ 目录
• cicada link [parent_dir] -将当前存储库链接到现有索引
• cicada clean -从文件夹中完全删除蝉集成以及所有设置

问你的助手：

# 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//
  ├─ 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/"
      }
    }
  }
}

启用监视模式时：

• 单独的进程监视器 .ex, .exs （Elixir）和 .py 用于更改的（Python）文件
• 更改会自动重新索引（增量、快速）
• 2秒去抖动可防止在快速编辑过程中过度重新索引
• 当MCP服务器停止时，监视过程会自动停止
• 排除的目录： deps, _build, node_modules, .git, assets, priv, .venv, venv

CLI备忘单

注： 语言检测是自动的——CICADA会自动检测Elixir（mix.exs）和Python（pyproject.toml）项目。

故障排除

"Index file not found"

首先运行索引器：

cicada index /path/to/project

确保索引成功完成。检查 ~/.cicada/projects//index.json.

"Module not found"

使用代码中出现的确切模块名称（例如。， MyApp.User，不 User).

如果模块是最近添加的，请重新索引：

cicada index .

MCP Server Won't Connect

故障排除清单：

1. 验证配置文件是否存在：

   # For Claude Code
   ls -la .mcp.json

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

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

1. 检查路径是绝对的：

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

1. 确保索引存在：

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

1. 完全重新启动编辑器 （不仅仅是重新加载窗口）

1. 检查编辑器MCP日志：

- 克劳德代码：--debug - 光标：设置→ MCP → 查看日志 - VS代码：输出面板→ MCP

PR Features Not Working

设置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索引”→ Run cicada index-pr .
• “不是GitHub存储库”→ 确保仓库有GitHub远程
• 索引速度慢→ 首次索引获取所有PR；后续运行是递增的
• 速率限制→ GitHub API有费率限制；如果达到限制，请等待并重试

部队重建：

cicada index-pr --clean

Keyword Search Not Working

错误： “关键字搜索不可用”

原因： 索引是在没有提取关键字的情况下构建的。

解决方案：

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

验证：

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

更多细节： 公关索引, 增量索引.

Python Indexing

要求：

• Node.js（用于scip-python索引器）
• 使用pyproject.toml的Python项目

首次设置： CICADA通过npm在第一个索引上自动安装scip-python。这可能需要一分钟。

已知限制（Beta）：

• 第一次索引可能比Elixir慢（SCIP生成步骤）
• 大型虚拟环境（.vnv）会自动排除在外
• 一些动态Python模式可能无法捕获

性能提示：

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

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

报告问题： 带有“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)
• 按可见性筛选（公共/私有/全部）

search_function -功能使用跟踪

• 查找定义和所有呼叫站点
• what_calls_it=true （默认）→ 查看所有来电者
• what_it_calls=true → 查看所有依赖项
• 包含以下代码示例 include_usage_examples=true
• 筛选依据 usage_type：来源、测试或全部

Git历史记录（统一工具）

git_history -一个工具中的所有git操作

• 单行: git_history("file.ex", start_line=42) → 责备+PR
• 行范围: git_history("file.ex", start_line=40, end_line=60) → 集体责备
• 功能跟踪: 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 -从查询结果向下搜索

• 自动检测模块与功能
• 显示使用示例的完整详细信息
• 配置要包含的内容：代码、依赖关系、调用者
• 方便地包装search_module和search_function

query_jq -高级索引查询

• 直接对索引进行jq查询
• 通过以下方式发现架构 | schema
• 紧凑（默认）或美观的输出
• 大结果的采样模式

详细参数+输出格式： MCP_TOOLS_REFERNCE.md.

令牌友好响应

所有工具都返回结构化的Markdown/JSON片段（签名、调用站点、PR元数据），而不是完整的文件，从而保持提示简洁。

v0.5.1中的新功能： 现在，所有工具默认使用紧凑输出，以最大限度地减少令牌使用。使用 verbose=true 获取包含完整文档和规格的详细输出。

______________________________________________________________________

______________________________________________________________________

文档

• 电码本 –完整的功能参考和用户指南
• 工作流 –现实世界的例子将工具链接在一起
• 安装 –为所有编辑器逐步设置
• 贡献 –开发指南和架构
• 更改日志.md –发行说明

深度潜水：

• 关键词提取分析 –语义搜索内部
• 公关索引 –GitHub集成详细信息
• MCP工具调用基准测试 –令牌/时间基准
• 工具可发现性 用户体验改进研究

______________________________________________________________________

路线图

当前状态

生产就绪：

• ✅ Elixir（树保姆）
• ✅ Python（SCIP）
• ✅ TypeScript（SCIP）
• ✅ JavaScript（SCIP）
• ✅ 锈蚀（SCIP）

贝塔：

• 🚧 二郎（树保姆）
• 🚧 Go（SCIP）
• 🚧 Java/Kotlin/Scala（SCIP）
• 🚧 C/C++（SCIP）
• 🚧 Ruby（SCIP）
• 🚧 C#/Visual Basic（SCIP）
• 🚧 飞镖（SCIP）
• 🚧 PHP（SCIP）

______________________________________________________________________

与备选方案的比较

|---------|--------|--------|---------| | 分析方法 |SCIP（静态索引）|LSP（实时服务器）|LLM摘要+嵌入| | 代码编辑 | ❌ | ✅ | ❌ | | Git上下文 | ✅ 公关历史、责任、演变|❌ | ❌ | | 资源使用情况 |低（从磁盘读取）|高（持久服务器进程）|中等（API调用）| | 隐私 |100%本地| 100%本地|需要外部LLM API| | 语义搜索 |当地Ollama或关键字|❌ | OpenAI/人类嵌入| | 调用图 |双向别名解析|基于LSP |❌ |

何时选择CICADA： 您需要具有丰富git上下文（PR归因、责备、函数演化跟踪）和高效令牌使用的本地优先操作。

何时选择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)
• 如果行为发生变化，则更新文档

我们欢迎以下问题/PR：

• 新语言语法
• 工具输出改进
• 更好的入职文档和教程

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

不要在盲目搜索中浪费上下文。给你的AI CICADA。