Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

Octocode – AI 에이전트를 위한 구조적 코드 인텔리전스

무엇인가요 – Octocode는 코드베이스를 실시간으로 쿼리 가능한 지식 그래프로 변환하는 오픈소스 Rust 도구입니다. Claude Desktop, Cursor, Windsurf 등에서 사용하는 Model-Center-Protocol (MCP)를 내장한 MCP 서버를 제공하여 AI 어시스턴트가 프로젝트 구조를 인간처럼 검색, 탐색, 추론할 수 있도록 합니다.

왜 중요한가요 – 일반적인 검색 증강 생성(RAG)은 소스 파일을 평면 텍스트 조각으로만 다루며, import, 함수 호출, 상속, 모듈 경계 간의 관계를 잃어버립니다. Octocode는 AST 기반의 심볼 그래프를 추출하여 결정론적 엣지(imports, calls, extends, implements 등)를 유지하고, 이 그래프와 의미 검색 기능을 MCP 호환 에이전트에 제공합니다. 그 결과, "인증은 어디서 처리되나요?" 또는 "결제 모듈에 의존하는 파일은 무엇인가요?"와 같은 코드 인식 답변이 가능해지며, AI가 키워드 매칭에서 추측할 필요가 없습니다.

핵심 기능

기능	제공되는 기능
의미 검색	자연어 질의를 통해 BM25 키워드 매칭과 벡터 임베딩(Voyage, OpenAI, Jina 등)의 하이브리드 방식으로 가장 관련성 높은 파일을 반환합니다.
실시간 AST 그래프	Tree-sitter가 현재 소스 트리를 노드(파일, 심볼)와 엣지(`imports`, `calls` 등)로 파싱하여 항상 최신 상태를 유지 – 별도의 인덱스 필요 없음.
GraphRAG (옵션)	선택적 지속화 그래프를 통해 결정론적 그래프 위에 LLM이 생성한 설명과 더 넓은 아키텍처적 관계를 추가할 수 있습니다.
LSP 통합	`--with-lsp`로 시작하면, 언어 서버(rust-analyzer 등)를 사용하여 `goto-definition`, `find-references`, `hover`, `completion` 등을 전달합니다.
구조적 검색	AST 패턴 매칭을 통해 특정 코드 패턴(예: 모든 `.unwrap()` 호출)을 찾을 수 있습니다.
다중 언어 지원	16개 언어가 기본으로 지원됨 (Rust, Python, TypeScript/JS, Go, PHP, C++, Ruby, Elixir, Java, Swift, Svelte, Lua, CSS, JSON, Bash, Markdown).
로컬 우선 및 프라이버시 우선	fastembed를 통해 로컬에서 임베딩 생성 가능; 클라우드 제공업체는 선택 사항이며, 명시적으로 전송하는 청크만 볼 수 있음.

작동 방식 (개요)

Tree-sitter가 각 소스 파일을 파싱 → 파일, 함수, 클래스 등의 노드로 변환.
실시간 심볼 그래프가 이러한 노드에서 결정론적 엣지(contains, imports, calls 등)로 구성.
옵션 인덱싱: 각 파일(또는 심볼)에 대해 임베딩을 계산하고 저장; 선택적 LLM이 텍스트 설명을 추가할 수 있음.
MCP 서버가 RPC 도구(semantic_search, view_signatures, graphrag, structural_search, LSP 헬퍼)를 노출하여 AI 에이전트가 호출.
하이브리드 검색은 BM25 키워드 점수와 벡터 유사도(RRF 융합)를 결합하여 결과를 순위 매김.

빠른 시작 (설치 → 인덱스 → 질의)

# 설치 (curl 설치기, Homebrew, 또는 cargo)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# 또는: brew install muvon/tap/octocode
# 또는: cargo install octocode

# 임베딩 제공자 설정 (Voyage AI 키 예시)
export VOYAGE_API_KEY="your-key"

# 프로젝트 인덱싱
cd /path/to/your/project
octocode index   # 모든 파일을 처리하고 실시간 그래프를 구축

# 자연어 검색
octocode search "authentication middleware"

AI 어시스턴트 연결 (MCP 클라이언트)

클라이언트의 mcpServers 설정에 서버 엔트리 추가, 예: Claude Desktop

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

이제 어시스턴트는 `semantic_search` 또는 `graphrag`와 같은 도구를 호출하고, 구체적인 위치와 콜 그래프를 포함한 코드베이스 질문에 답변할 수 있습니다.

검색 품질 (벤치마크)

Octocode는 자체 소스 트리에서 실행되는 재현 가능한 벤치마크(127개 코드 검색 질의)를 제공합니다. 단순한 하이브리드(BM25 0.3 + 벡터 0.7)로 다음과 같은 성능 달성:

Hit@5 = 0.732
Hit@10 = 0.835
MRR = 0.572
Recall@10 = 0.807 키워드 중심 가중치는 밀도 중심 검색 대비 Hit@5를 +22% 향상시킵니다. 벤치마크는 일반적인 코드 리랭커(bge-reranker-base)가 성능을 저하시킨다는 점을 보여주며, 코드 전용 리랭커의 필요성을 시사합니다.

누가 사용할 수 있나요

개발자 – LLM 기반 어시스턴트(Claude, Cursor 등)가 리포지토리의 실제 아키텍처를 이해하도록 하고 싶은 사람.
팀 – 신뢰성 있고 프라이버시를 보장하는 코드 탐색이 필요한 내부 AI 에이전트를 구축하는 사람.
도구 제작자 – AST 파싱을 다시 구현하지 않고도 LSP 수준의 정밀도를 제공하는 즉시 사용 가능한 MCP 서버를 찾는 사람.

라이선스 및 커뮤니티

라이선스: Apache 2.0 (허용성 높고 상용 사용에 적합).
리포지토리 활동: CI 배지, 커버리지 배지, crates.io 릴리스, 증가하는 스타 수.
지원: GitHub Issues, Discussions, 연락처 이메일 (opensource@muvon.io).

결론: Octocode는 실제 프로덕션 수준의 Rust 프로젝트로, AI 에이전트에게 코드의 구조적이고 그래프 기반의 시각을 제공하여 정확하고 문맥 인식 가능한 지원을 가능하게 하며, 모든 것을 로컬에서 관리하고 완전히 자신이 통제할 수 있도록 합니다.