Python 코드베이스 분석 RAG 시스템

이 시스템은 추상 구문 트리(AST)를 사용하여 Python 코드를 분석하고, 추출된 정보(함수, 클래스, 호출, 변수 등)를 Weaviate 벡터 데이터베이스에 저장하며, 모델 컨텍스트 프로토콜(MCP) 서버를 통해 코드베이스를 쿼리하고 이해하는 도구를 제공합니다. 임베딩 및 자연어 설명/답변을 생성하기 위해 Google의 Gemini 모델을 활용합니다.

특징

• 코드 스캐닝: Python 파일을 구문 분석하여 코드 요소(함수, 클래스, 임포트, 호출, 할당)와 그 관계를 식별합니다. 추출 항목:
  • 기본 정보: 이름, 유형, 파일 경로, 줄 번호, 코드 조각, 문서 문자열.
  • 함수/메서드 세부 정보: 매개변수, 반환 유형, 시그니처, 데코레이터.
  • 범위 정보: 부모 범위(클래스/함수) UUID, 읽을 수 있는 ID(예: file:type:name:line ), 기본 클래스 이름.
  • 사용 정보: 범위 내의 속성 액세스, 호출 관계(부분적으로 추적됨).
• 벡터 저장소: Weaviate를 사용하여 코드 요소와 벡터 임베딩을 저장합니다(LLM 생성이 활성화된 경우).
• LLM 강화(선택 사항 및 배경 지식): Gemini를 사용하여 함수 및 클래스에 대한 의미적 설명과 임베딩을 생성합니다. 이제 스캐닝 후 또는 수동으로 트리거되는 백그라운드 작업으로 실행됩니다. .env 파일을 통해 활성화/비활성화할 수 있습니다.
• 자동 세분화(선택 사항 및 백그라운드): LLM 생성이 활성화된 경우 백그라운드 처리의 일부로 컨텍스트(호출자, 피호출자, 형제, 관련 변수)를 사용하여 새 함수/업데이트된 함수에 대한 설명을 자동으로 세분화합니다.
• RAG Q&A: 검색 증강 생성을 사용하여 코드베이스에 대한 자연어 질문에 답합니다(LLM 기능 활성화 및 백그라운드 처리 완료 필요).
• 사용자 설명: 사용자가 특정 코드 요소에 수동 메모를 추가할 수 있습니다.
• 시각화: 저장된 관계에 따라 MermaidJS 호출 그래프를 생성합니다.
• MCP 서버: MCP 도구를 통해 분석 및 쿼리 기능을 제공하고 코드베이스와 활성 코드베이스 컨텍스트를 관리합니다.
• 파일 감시기(통합): 코드베이스가 스캔될 때( scan_codebase ) 자동으로 시작되고, 다른 코드베이스가 선택될 때( select_codebase ) 또는 코드베이스가 삭제될 때( delete_codebase ) 자동으로 중지됩니다. 활성 코드베이스의 파일이 변경되면 해당 코드베이스에 대한 재분석 및 데이터베이스 업데이트를 트리거합니다. start_watcher 및 stop_watcher 도구를 통해 수동으로 제어할 수도 있습니다.
• 코드베이스 종속성: 스캔된 코드베이스 간의 종속성을 정의할 수 있습니다( add_codebase_dependency , remove_codebase_dependency ).
• 코드베이스 간 쿼리: 활성 코드베이스와 선언된 종속성에서 검색( find_element ) 및 질문( ask_question )이 가능합니다.

설정

1. 환경: Python 3.10 이상과 Docker가 설치되어 있는지 확인하세요.
2. Weaviate: Docker Compose를 사용하여 Weaviate 인스턴스를 시작합니다.지엑스피1
3. 종속성: Python 패키지 설치:
   pip install -r requirements.txt
4. API 키 및 구성: 프로젝트 루트에 .env 파일을 생성하고 Gemini API 키를 추가하세요. 다른 설정도 구성할 수 있습니다.
   # --- Required --- GEMINI_API_KEY=YOUR_API_KEY_HERE # --- Optional --- # Set to true to enable background LLM description generation and refinement GENERATE_LLM_DESCRIPTIONS=true # Max concurrent background LLM tasks (embeddings/descriptions/refinements) LLM_CONCURRENCY=5 # ANALYZE_ON_STARTUP is no longer used. Scanning is done via the scan_codebase tool. # Specify Weaviate connection details if not using defaults # WEAVIATE_HOST=localhost # WEAVIATE_PORT=8080 # WEAVIATE_GRPC_PORT=50051 # Specify alternative Gemini models if desired # GENERATION_MODEL_NAME="models/gemini-pro" # EMBEDDING_MODEL_NAME="models/embedding-001" # Adjust Weaviate batch size # WEAVIATE_BATCH_SIZE=100 # SEMANTIC_SEARCH_LIMIT=5 # SEMANTIC_SEARCH_DISTANCE=0.7 # Watcher polling interval (seconds) # WATCHER_POLLING_INTERVAL=5
5. MCP 서버 실행: 별도의 터미널에서 서버를 시작합니다.
   python src/code_analysis_mcp/mcp_server.py
   (도구를 사용할 수 있도록 이 터미널이 계속 실행되도록 하세요)

아키텍처 개요

이 시스템은 Python 코드를 분석하고, 추출된 정보를 Weaviate 벡터 데이터베이스에 저장하며, Model Context Protocol(MCP) 서버를 통해 코드베이스를 쿼리하고 이해하는 도구를 제공합니다. 또한, Google의 Gemini 모델을 활용하여 임베딩 및 자연어 설명/답변을 생성합니다.

주요 모듈은 다음과 같습니다.

• code_scanner.py : Python 파일을 찾고, AST를 사용하여 구문 분석하고, 구조적 요소(함수, 클래스, 가져오기, 호출 등)를 추출하고, Weaviate에 대한 데이터를 준비합니다.
• weaviate_client.py : Weaviate와의 연결을 관리하고, 데이터 스키마( CodeFile , CodeElement , CodebaseRegistry )를 정의하고, 데이터 일괄 업로드, 쿼리, 업데이트, 삭제 기능을 제공합니다.
• rag.py : 코드베이스 관련 질문에 답변하기 위한 검색 증강 생성(RAG)을 구현합니다. 의미론적 검색을 사용하여 관련 코드 요소를 찾고, LLM을 사용하여 답변을 종합합니다.
• mcp_server.py : FastMCP 서버를 설정하고, CodebaseRegistry 컬렉션의 코드베이스를 관리하고, 활성 코드베이스 컨텍스트( ACTIVE_CODEBASE_NAME )를 처리하고, 파일 감시 논리(자동 시작/중지 포함)를 통합하고, 코드베이스 종속성을 관리하고, 자세한 인수 설명이 포함된 MCP 도구로 분석 기능을 노출합니다.
• visualization.py : 저장된 관계에 따라 MermaidJS 호출 그래프를 생성합니다.

시스템은 CodeFile 및 CodeElement 컬렉션에 Weaviate의 멀티 테넌시 기능을 사용하며, 여기서 테넌트 ID는 사용자 정의 codebase_name 입니다. 별도의 비멀티 테넌트 CodebaseRegistry 컬렉션은 코드베이스 메타데이터(이름, 디렉터리, 상태, 요약, 감시자 상태, 종속성)를 추적합니다. 서버의 ACTIVE_CODEBASE_NAME 전역 변수는 쿼리의 기본 코드베이스 테넌트를 결정합니다. 쿼리 도구( find_element , ask_question )는 레지스트리에 저장된 활성 코드베이스와 해당 선언된 종속성을 선택적으로 검색할 수 있습니다. list_codebases 도구를 사용하면 모든 코드베이스의 상태와 종속성을 확인할 수 있습니다.

백그라운드 LLM 처리는 코드 요소에 대한 의미적 설명과 임베딩을 생성하는 데 사용됩니다. 이는 .env 파일을 통해 활성화/비활성화할 수 있는 선택적 기능입니다.

사용 가능한 도구와 해당 인수에 대한 자세한 정보는 서버가 실행되면 표준 MCP 내부 검사 방법을 사용하여 MCP 서버에서 직접 검색할 수 있습니다.