bartolli/codanna

Codanna – AI 코딩 에이전트를 위한 로컬 코드 인텔리전스 서버

개요 – Codanna는 Rust 기반 도구로, 자신의 머신에서 코드베이스의 검색 가능한 시맨틱 인덱스를 구축합니다. 그런 다음 Claude Code, Google Gemini, OpenAI Codex, Cursor, Windsurf 같은 AI 코딩 어시스턴트가 사용하는 경량 프로토콜인 MCP(Model-Client-Protocol) 를 통해 그 지식을 노출합니다. 한 번의 MCP 호출로 심볼의 정의, 문서, 호출자와 피호출자, 그리고 영향 분석(심볼이 변경될 경우의 "폭발 반경")을 얻을 수 있습니다. 전체 과정은 로컬에서 실행되며, 원격 임베딩 모델을 명시적으로 활성화하지 않는 한 소스 코드나 쿼리가 외부 서비스로 전송되지 않습니다.

작동 방식

• 인덱싱 – codanna init이 .codanna/ 디렉터리를 생성하고, codanna index <path>가 파일을 파싱하여(15개 언어 지원) 심볼, 호출 그래프 엣지, 시맨틱 검색용 임베딩을 저장합니다.
• MCP 인터페이스 – Codanna와 통신하는 두 가지 방법:
  1. 상시 서버 (codanna serve / codanna serve --http): 전체 개발 세션 동안 계속 실행됩니다.
  2. 일회성 CLI (codanna mcp …): 셸 스크립트, CI 파이프라인 또는 AI 어시스턴트 스킬에서 직접 호출할 수 있습니다.
• 주요 명령 – codanna mcp semantic_search_with_context는 각 일치 항목에 대해 심볼 ID, 시그니처, docstring, 호출자 목록, 피호출자 목록(정확한 호출 위치 포함), 재귀적 영향 분석을 반환합니다. 출력은 일반 텍스트 또는 JSON(--json)입니다.

주요 기능

기능	제공 내용
시맨틱 검색	코드와 markdown 문서에 대한 자연어 쿼리. 이름뿐 아니라 의도로 함수를 찾습니다.
관계 추적	호출 그래프, 구현, 모듈 간 의존성으로 "이 함수는 어디에서 호출되나?", "변경하면 무엇이 깨지나?" 같은 쿼리를 가능하게 합니다.
문서 RAG	프로젝트 문서(markdown, 텍스트)를 인덱싱하여 AI 에이전트가 코드와 함께 관련 문서를 검색할 수 있습니다.
MCP 프로토콜	Claude, Gemini, Codex, Cursor, Windsurf 또는 외부 명령을 호출할 수 있는 모든 클라이언트와 바로 호환됩니다.
프로필 / 스킬	프로젝트 유형별로 미리 패키징된 명령 세트. 플러그인 마켓플레이스를 통해 Claude Code에 추가할 수 있습니다.
로컬 우선	모든 인덱싱과 임베딩이 온디바이스에서 수행됩니다. 선택적 원격 OpenAI 호환 임베딩은 옵트인 방식입니다.
성능	최대 약 초당 250k 심볼 파싱. 웜 조회는 10ms 미만. 인덱스 구축 후 시맨틱 쿼리는 몇 밀리초입니다.

일반적인 워크플로

# 설치 (macOS/Linux/WSL) – 원라이너 또는 Homebrew/Nix/PowerShell
curl -fsSL https://install.codanna.sh | sh

# 워크스페이스 초기화
codanna init
codanna index src            # 소스 트리에 대한 인덱스 구축

# AI 어시스턴트(또는 CLI)에 컨텍스트 질의
codanna mcp semantic_search_with_context query:"extract function calls" limit:1

# RAG용 프로젝트 문서 추가
codanna documents add-collection docs ./docs
codanna documents index
codanna mcp search_documents query:"authentication flow"

CLI 출력에는 file:line 위치, 심볼 ID, 그리고 에이전트가 후속 쿼리로 연결할 수 있는 짧은 안내 힌트가 포함됩니다.

통합 – 프로젝트 루트에 .mcp.json 파일을 추가하면 Claude Code, Cursor 또는 기타 MCP 호환 도구가 Codanna를 자동으로 실행합니다:

{ "mcpServers": { "codanna": { "command": "codanna", "args": ["--config", ".codanna/settings.toml", "serve", "--watch"] } } }

전송 방식은 stdio, HTTP 또는 HTTPS입니다.

설치 옵션

• 원라인 스크립트 (curl … | sh)
• Homebrew (brew install codanna)
• Nix (nix run github:bartolli/codanna)
• Windows용 PowerShell 스크립트 (실험적 지원)
• Rust 1.85+로 소스에서 빌드하고 cargo install codanna

시스템 요구 사항

• 기본 ONNX 임베딩 모델용 약 150 MiB 다운로드.
• macOS: Apple Silicon 전용 (현재 ONNX Runtime 빌드는 Intel을 지원하지 않음).
• Linux: glibc 2.38+ 및 GCC 13+ 런타임 라이브러리 (사전 빌드된 바이너리는 Ubuntu 24.04 대상).
• Windows: 실험적.

라이선스 – Apache 2.0 (저작자 표시 필요). 일반적인 GitHub 워크플로를 통한 기여를 환영합니다.

---

결론 – Codanna는 AI 코딩 어시스턴트에게 빠르고 로컬이며 구조화된 코드베이스 뷰를 제공하여, 흔한 "grep 후 읽기" 루프를 단일한 컨텍스트 인식 MCP 요청으로 바꿉니다. "이 함수는 어디에서 사용되나?", "X를 수정하면 무엇이 깨지나?", "인증 로직을 찾아라" 같은 질문에 독점 코드를 클라우드로 보내지 않고 답해야 하는 에이전트에 특히 유용합니다.