CICADA

mcp-name: io.github.wende/cicada

Code Intelligence: Contextual Analysis, Discovery, and Attribution

AI 코드 어시스턴트를 위한 컨텍스트 압축 – 구조화되고 토큰 효율적인 방식으로 Elixir, Python, TypeScript, JavaScript, Rust 등 17개 이상의 언어에 접근하세요.

최대 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 - 모든 MCP 도구에 HTTP 접근을 위한 REST API 서버 시작

• 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 - 폴더에서 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

"42번째 줄을 도입한 PR은?" 또는 "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을 자동으로 설치합니다. 1분 정도 걸릴 수 있습니다.

알려진 제한 사항 (베타):

• 첫 인덱싱은 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는 Elixir, Python, Erlang 코드베이스에서 효율적인 코드 탐색을 위해 설계된 7가지 집중 MCP 도구를 제공합니다.

🧭 어떤 도구를 사용해야 하나요?

이 도구들을 실제로 보고 싶으신가요? 전체 워크플로 예제에서 전문가 팁과 실제 시나리오를 확인하세요.

핵심 도구

query - 스마트 코드 검색 (시작점)

• 키워드와 패턴을 자동으로 감지

• 필터: scope (public/private), recent (최근 14일), filter_type (모듈/함수), match_source (문서/문자열)

• 스마트 다음 단계 제안과 함께 스니펫 반환

• path_pattern을 사용하여 위치별 필터링

search_module - 심층 모듈 분석

• 전체 API 보기: 함수, 시그니처, 사양, 문서

• Python: 클래스와 메서드 개수 및 시그니처 표시

• Elixir: 인자 표기법(arity notation)과 함께 함수 표시

• 양방향 분석:

  • 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 – 전체 기능 참조 및 사용자 가이드

• Workflows – 도구를 연결하는 실제 예제

• 설치 – 모든 편집기를 위한 단계별 설정

• 기여하기 – 개발 지침 및 아키텍처

• CHANGELOG.md – 릴리스 노트

심층 탐구:

• 키워드 추출 분석 – 의미 검색 내부

• PR 인덱싱 – GitHub 통합 세부 정보

• MCP 도구 호출 벤치마킹 – 토큰/시간 벤치마크

• 도구 발견 가능성 – 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)

• 동작이 변경되면 문서 업데이트

다음에 대한 이슈/PR을 환영합니다:

• 새로운 언어 문법

• 도구 출력 개선

• 더 나은 온보딩 문서 및 튜토리얼

라이선스

MIT – LICENSE 참조.

블라인드 검색에 컨텍스트를 낭비하지 마세요. AI에 CICADA를 제공하세요.

시작하기 · 이슈 보고