STARWARCLOUD STARWAR.AI
返回市场
蝉服务器

蝉服务器

作者：wende13 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img src="https://gips3.baidu.com/it/u=1289267674,1653206419&fm=3081&app=3081&f=PNG?w=800&h=495" alt="CICADA Logo" width="360"/>

CICADA

Code Intelligence: Contextual Analysis, Discovery, 和 Attribution

为您的AI助手提供对Elixir和Python代码库的结构化访问。

Python支持处于测试阶段 – 完整的代码智能功能，自动检测语言。即将支持TypeScript。

Python 版本 许可证: MIT codecov MCP 兼容

Elixir 支持 Python 支持 TypeScript 支持

安装 MCP 服务器

快速安装 · 安全 · 开发者 · AI 助手 · 文档

</div>

为什么选择 CICADA？

传统的AI助手将你的仓库视为一堆文本。这会导致：

  • 令牌浪费： 盲目搜索会消耗3000多个令牌。
  • 虚构编辑： 别名/导入隐藏了调用位置，重构时可能会遗漏实际使用。
  • 无历史上下文： 设计意图和PR权衡从未进入提示。

CICADA是一个MCP服务器，它为Elixir和Python（测试阶段）提供了AST级别的知识：

  • 模块和函数定义，包括签名、规格、文档和所属文件。
  • 对于Python，跟踪类和方法；对于Elixir，跟踪模块和函数。
  • 完全的调用位置跟踪（别名、导入、动态引用）。
  • 语义/关键词搜索，即使函数名为verify_credentials/2或AuthService.check()，你也可以通过“认证”来查找。
  • Git和PR归属，揭示代码存在的原因。
  • 死代码检测和模块依赖视图，以确保安全重构。
  • 自动检测语言 – 无缝支持两种语言。

结果： 在我们的比较中，同样的问题从3,127个令牌 / 52.8秒减少到550个令牌 / 35秒，并且答案正确。

安装

# 1. 安装uv（如果需要）
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# 在你的仓库中
cicada claude   # 或者：cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode
<div align="left"> <summary><strong>在永久安装前试用</strong></summary> 按需运行CICADA（索引质量较差，但无需安装）。 
uvx cicada-mcp claude   # 或者 cursor, vs

或者

claude mcp add uvx cicada-mcp

gemini mcp add uvx cicada-mcp

codex mcp add uvx cicada-mcp

使用编辑器内置的MCP管理来安装CICADA。

</details> </div>

安装后可用的命令：

  • cicada [claude|cursor|vs|gemini|codex|opencode] - 每个项目的一键交互式设置
  • cicada-mcp - MCP服务器（由编辑器自动启动）
  • cicada watch - 监控文件更改并自动重新索引
  • cicada index - 使用自定义选项重新索引代码（-f/--force + --fast/--regular/--max, --watch）
  • cicada index-pr - 索引拉取请求以进行PR归属
  • cicada find-dead-code - 查找可能未使用的函数
  • cicada link [parent_dir] - 将当前仓库链接到现有的索引
  • cicada clean - 完全移除cicada集成及其所有设置

询问您的助手：

# Elixir
"显示MyApp.User中的函数"
"authenticate/2在哪里被调用？"

# Python
"显示AuthService类的方法"
"login()在代码库中哪里被使用？"

# 两种语言
"找到与API认证相关的代码"

隐私与安全

  • 100%本地化： 解析和索引在您的机器上进行；没有外部访问。
  • 无遥测： CICADA不收集使用情况或任何遥测数据。
  • 只读工具： MCP端点仅读取索引；它们不能更改您的仓库。
  • 可选GitHub访问： PR功能依赖于gh和您现有的OAuth令牌。
  • 数据布局： 
    ~/.cicada/projects/<repo_hash>/
├─ index.json      # 模块、函数、调用位置、元数据
├─ config.yaml     # 索引选项 + 关键词层级
├─ hashes.json     # 增量索引缓存
└─ pr_index.json   # 可选的PR元数据 + 审查
    您的仓库只会获得一个编辑器配置（.mcp.json, .cursor/mcp.json, .vscode/settings.json, .gemini/settings.json, .codex/mcp.json, 或 .opencode.json）。

为开发者

一次将CICADA接入您的编辑器，每次助手会话都会继承上下文。

安装与配置

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

启用PR归属（可选）

brew install gh    # 或 apt install gh
gh auth login
cicada index-pr .     # 增量
cicada index-pr . --clean   # 完全重建

解锁诸如“哪次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 claude配置MCP + 增量重新索引第一次设置，本地更改后
cicada watch监控文件并自动重新索引开发活跃期间
cicada index --force --regular .完全重建，带语义关键词大规模重构或启用AI层级后
cicada index-pr .同步PR元数据/审查新PR合并后
cicada find-dead-code --min-confidence high列出未使用的公共函数清理冲刺

故障排除

<details> <summary><b>"索引文件未找到"</b></summary>

先运行索引器：

cicada index /path/to/project

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

</details> <details> <summary><b>"模块未找到"</b></summary>

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

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

cicada index .
</details> <details> <summary><b>MCP服务器无法连接</b></summary>

故障排查清单：

  1. 验证配置文件存在：

    # 对于Claude Code
ls -la .mcp.json

# 对于Cursor
ls -la .cursor/mcp.json

# 对于VS Code
ls -la .vscode/settings.json

  2. 检查路径是否为绝对路径：

    cat .mcp.json
# 应该包含：/absolute/path/to/project
# 不应为：./project 或 ../project

  3. 确保索引存在：

    ls -la ~/.cicada/projects/
# 应该显示您的项目的目录

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

  5. 检查编辑器MCP日志：

    • Claude Code: --debug
    • Cursor: 设置 → MCP → 查看日志
    • VS Code: 输出面板 → MCP
</details> <details> <summary><b>PR功能不起作用</b></summary>

设置GitHub CLI：

# 安装GitHub CLI
brew install gh  # macOS
sudo apt install gh  # Ubuntu
# 或访问 https://cli.github.com/

# 认证
gh auth login

# 索引PR
cicada index-pr

常见问题：

  • “未找到PR索引” → 运行 cicada index-pr .
  • “不是GitHub仓库” → 确保仓库有GitHub远程
  • 索引速度慢 → 第一次索引获取所有PR；后续运行是增量
  • 达到速率限制 → GitHub API有速率限制；如果达到限制，请等待并重试

强制重建：

cicada index-pr --clean
</details> <details> <summary><b>关键词搜索不起作用</b></summary>

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

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

解决方案：

# 使用关键词提取重新索引
cicada index .  # 或 --fast 或 --max

验证：

cat ~/.cicada/projects/<hash>/config.yaml
# 应该显示 keyword_extraction: enabled
</details>

更多详情：docs/PR_INDEXING.md，docs/08-INCREMENTAL_INDEXING.md。

<details> <summary><b>Python索引（测试阶段）</b></summary>

需求：

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

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

已知限制（测试阶段）：

  • 首次索引可能比Elixir慢（SCIP生成步骤）
  • 大型虚拟环境（.venv）会自动排除
  • 一些动态Python模式可能不会被捕获

性能提示：

# 确保 .venv 被排除
echo "/.venv/" >> .gitignore

# 使用 --fast 层级进行更快的索引
cicada index --fast .

报告问题： GitHub Issues 标签为“Python”

</details>

为AI助手

CICADA提供了7种专注于MCP工具，旨在高效地探索Elixir和Python（测试阶段）代码库。

🧭 应该使用哪种工具？

需求工具备注
开始探索query🚀 从这里开始 - 智能发现，关键词/模式 + 过滤器（范围、近期、路径）
查看模块的完整APIsearch_module函数、签名、规格、文档。使用what_calls_it/what_it_calls进行双向分析
查找函数的使用位置search_function定义 + 所有调用位置。支持通配符（*）和OR（|）模式
跟踪git历史git_history统一工具：blame、提交、PR、函数演变（取代4个旧工具）
查找死代码find_dead_code识别潜在未使用的函数，具有信心级别
深入结果expand_result自动展开查询结果中的模块或函数
高级索引查询query_jq为高级用户定制jq查询

想看看这些工具的实际操作吗？ 查看完整工作流程示例以及专业技巧和现实场景。

核心工具

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

  • 自动检测关键词 vs 模式
  • 过滤器：scope（公开/私有），recent（最近14天），filter_type（模块/函数），match_source（文档/字符串）
  • 返回片段，并提供智能下一步建议
  • 使用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）
  • 按可见性过滤（公开/私有/全部）

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) → 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 - 从查询结果深入

  • 自动检测模块 vs 函数
  • 显示完整细节及使用示例
  • 配置要包含的内容：代码、依赖项、调用者
  • search_module和search_function的便捷包装

find_dead_code - 代码清理分析

  • 三种信心级别（高、中、低）
  • 智能检测回调和行为
  • 识别动态调用模式
  • 按模块分组，附带行号
  • 排除测试文件和@impl函数

query_jq - 高级索引查询

  • 直接针对索引的jq查询
  • 使用| schema发现架构
  • 紧凑（默认）或美化输出
  • 大结果集的样本模式

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

令牌友好响应

所有工具返回结构化的Markdown/JSON片段（签名、调用位置、PR元数据），而不是完整的文件，使提示更简洁。