CocoIndex-Code: 70% 토큰을 절약하는 AST 기반 코드 검색 MCP

“코드를 찾는데 얼마나 많은 토큰을 쓰고 있는가?”

grep은 빠르지만 의미를 이해하지 못한다. 스크린샷 기반 검색은 토큰을 잔뜩 쓴다. 기존 RAG 솔루션은 설정이 복잡하다. CocoIndex-Code는 이 모든 문제를 단 한 줄로 해결한다.

claude mcp add cocoindex-code -- cocoindex-code

API 키도, 데이터베이스도 없이. 그냥 작동한다.

무엇이 특별한가

CocoIndex-Code는 AST(추상 구문 트리) 기반의 초경량 임베디드 코드 검색 MCP다.

핵심 가치:

• 70% 토큰 절감 — 불필요한 코드를 읽지 않는다
• 1분 설정 — claude mcp add 한 줄이면 끝
• 완전 무료 — 로컬 SentenceTransformers, API 키 불필요
• 초고속 — Rust 기반 CocoIndex 엔진, 변경 파일만 재인덱싱
• 임베디드 — 데이터베이스 설정 불필요, 그냥 작동

왜 AST인가: 라인 기반 vs 구문 기반

기존 코드 검색의 문제를 이해해야 한다.

라인 기반 청킹의 한계

전통적인 접근은 코드를 N줄 단위로 자른다. 하지만 코드는 줄 단위가 아니다:

def process_user(user_id: int) -> User:
    """사용자 정보를 조회합니다."""
    user = db.query(User).filter_by(id=user_id).first()
    if not user:
        raise UserNotFoundError(user_id)
    return user

이 함수를 3줄씩 자르면? 문맥이 끊긴다. 함수의 시작은 있고 끝은 없다. 임베딩 품질이 떨어진다.

AST 기반 청킹의 강력함

CocoIndex-Code는 Tree-sitter로 코드를 파싱한다. 함수, 클래스, 메서드 단위로 정확히 청킹한다.

[함수] process_user (line 1-7)
  └─ 사용자 조회 + 에러 처리 로직
  
[클래스] UserRepository (line 10-45)
  └─ CRUD 메서드 모음

결과:

• 의미 단위 보존 → 더 정확한 검색
• 불필요한 코드 제외 → 70% 토큰 절감
• 문맥 유지 → 더 나은 이해

핵심 기능: 5가지

1. 시맨틱 코드 검색

search(
    query: str,        # 자연어 또는 코드 스니펫
    limit: int = 10,   # 최대 결과 수
    offset: int = 0,   # 페이지네이션
    refresh_index: bool = True  # 인덱스 새로고침
)

사용 예시:

“사용자 세션 관리 코드 찾아줘” “에러 핸들링하는 부분이 어디야?” “비슷한 패턴의 API 호출 코드 보여줘”

grep으로는 찾기 힘든 것들. 의미로 찾는다.

2. Rust 기반 초고속 인덱싱

CocoIndex는 Rust로 작성된 초고속 데이터 변환 엔진이다.

인크리멘탈 인덱싱:

• 전체 재인덱싱 없음
• 변경된 파일만 업데이트
• 대규모 코드베이스에서도 빠름

에디터에서 파일 저장 → 백그라운드에서 자동 인덱싱. 기다릴 필요 없다.

3. 20+ 언어 지원

추가 언어는 COCOINDEX_CODE_EXTRA_EXTENSIONS로 확장 가능.

4. 자동 제외 디렉토리

생성된 코드 디렉토리는 자동 제외:

• node_modules/
• __pycache__/
• target/
• dist/
• vendor/

설정할 필요 없다. 알아서 한다.

5. 유연한 임베딩 옵션

기본값: 완전 무료

로컬 SentenceTransformers (all-MiniLM-L6-v2) 사용. API 키 없이 완전 무료.

100+ 클라우드 프로바이더 지원:

CodeRankEmbed으로 더 나은 검색:

GPU가 있다면 nomic-ai/CodeRankEmbed을 권장한다. 137M 파라미터, 1GB VRAM, 8192 토큰 컨텍스트. 코드 검색에 특화되어 있다.

빠른 시작: 1분 설정

설치

pipx:

pipx install cocoindex-code
pipx upgrade cocoindex-code  # 업그레이드

uv:

uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"

Claude Code 연동

claude mcp add cocoindex-code -- cocoindex-code

끝이다. 정말로.

Codex 연동

codex mcp add cocoindex-code -- cocoindex-code

OpenCode 연동

opencode.json에 추가:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": ["cocoindex-code"]
    }
  }
}

실제 사용 시나리오

1. 낯선 코드베이스 탐색

“이 프로젝트에서 인증 로직이 어디 있어?”

에이전트가 search()를 호출. 관련 코드를 즉시 찾는다. 파일 하나씩 열어볼 필요 없다.

2. 유사 코드 패턴 찾기

“비슷한 API 호출 패턴 있는지 찾아줘”

코드 스니펫을 쿼리로 사용. 의미적으로 유사한 코드를 찾는다.

3. 리팩토링 영향 범위 파악

“이 함수와 비슷한 로직이 다른 곳에도 있나?”

함수 이름을 몰라도 된다. 구현 내용으로 검색.

4. 코드 리뷰 지원

“에러 처리가 누락된 부분 찾아줘”

패턴으로 검색. 일관성 체크 자동화.

고급 설정

환경 변수

루트 경로 자동 감지

COCOINDEX_CODE_ROOT_PATH가 없으면:

1. .cocoindex_code/가 있는 가장 가까운 부모 디렉토리
2. .git/가 있는 가장 가까운 부모 디렉토리
3. 현재 작업 디렉토리

클라우드 임베딩 사용

OpenAI:

claude mcp add cocoindex-code \
  -e COCOINDEX_CODE_EMBEDDING_MODEL=text-embedding-3-small \
  -e OPENAI_API_KEY=your-api-key \
  -- cocoindex-code

Gemini:

claude mcp add cocoindex-code \
  -e COCOINDEX_CODE_EMBEDDING_MODEL=gemini/text-embedding-004 \
  -e GEMINI_API_KEY=your-api-key \
  -- cocoindex-code

Voyage (코드 최적화):

claude mcp add cocoindex-code \
  -e COCOINDEX_CODE_EMBEDDING_MODEL=voyage/voyage-code-3 \
  -e VOYAGE_API_KEY=your-api-key \
  -- cocoindex-code

에이전트에게 지시하기

프로젝트의 AGENTS.md 또는 CLAUDE.md에 추가:

Use the cocoindex-code MCP server for semantic code search when:
- Searching for code by meaning or description rather than exact text
- Exploring unfamiliar parts of the codebase
- Looking for implementations without knowing exact names
- Finding similar code patterns or related functionality

이제 에이전트가 자동으로 시맨틱 검색을 사용한다.

트러블슈팅: macOS

일부 macOS 파이썬은 SQLite 확장을 비활성화한다.

해결책: Homebrew로 설치

brew install python3
pipx install cocoindex-code

엔터프라이즈: CocoIndex

CocoIndex-Code의 엔진인 CocoIndex는 엔터프라이즈급 인덱싱 엔진이다.

• 대규모 코드베이스 (XXX GB) 지원
• 팀원 간 인덱스 공유
• 브랜치 중복 제거
• 원격 설정 지원

엔터프라이즈 설정 도움이 필요하면 linghua@cocoindex.io로 연락.

마치며: “그냥 작동한다”의 힘

CocoIndex-Code는 복잡한 설정을 요구하지 않는다.

• API 키? 없어도 된다
• 데이터베이스? 필요 없다
• 긴 설정 가이드? 1분이면 끝

그냥 작동한다. 이것이 진정한 개발자 도구가 가져야 할 품질이다.

70% 토큰 절감. 1분 설정. 완전 무료.

Claude Code, Codex, Cursor, 어떤 코딩 에이전트든. 이제 시맨틱 코드 검색을 1분 만에 추가할 수 있다.

🔗 관련 정보

• GitHub: https://github.com/cocoindex-io/cocoindex-code
• CocoIndex 엔진: https://github.com/cocoindex-io/cocoindex
• 지원 임베딩: https://docs.litellm.ai/docs/embedding/supported_embedding
• CodeRankEmbed: https://huggingface.co/nomic-ai/CodeRankEmbed
• 라이선스: Apache-2.0