Codebasemcp

🚀 Python 代碼庫分析 RAG 系統

本系統專注於 Python 代碼庫的分析，通過解析 Python 文件中的抽象語法樹（AST），提取函數、類、調用、變量等關鍵信息，並將其存儲到 Weaviate 向量數據庫中。同時，藉助 Google 的 Gemini 模型生成嵌入式表示和自然語言描述，還提供了基於 Model Context Protocol (MCP) 服務器的查詢工具，幫助用戶深入理解代碼庫。

✨ 主要特性

• 代碼掃描：深入解析 Python 文件，精準識別代碼元素（函數、類、導入、調用、賦值）及其關係。提取的信息豐富全面，涵蓋基本信息（名稱、類型、文件路徑、行號、代碼片段、文檔字符串）、函數/方法詳細信息（參數、返回類型、簽名、裝飾器）、作用域信息（父作用域 UUID、可讀 ID、位置信息）以及元數據（代碼文件哈希值用於版本控制，掃描時間戳記錄分析時刻）。
• 向量數據庫集成：充分利用 Weaviate 的多租戶功能，分別存儲代碼文件 (CodeFile) 和代碼元素 (CodeElement)。每個代碼庫以用戶定義的 codebase_name 作為租戶 ID，同時設有獨立的非多租戶集合 CodebaseRegistry 來記錄代碼庫元數據。
• RAG 實現：採用增強檢索（Retrieval-Augmented Generation）技術，有效回答關於代碼庫的問題。先通過語義搜索定位相關代碼元素，再借助大型語言模型 (LLM) 合成答案。
• MCP 服務器：基於 FastMCP 框架搭建服務器，實現代碼庫註冊 (CodebaseRegistry) 的管理，維護活動代碼庫上下文 (ACTIVE_CODEBASE_NAME)，整合文件監控邏輯（支持自動啟動/停止），管理代碼庫依賴關係，並將分析功能作為 MCP 工具對外開放。
• 可視化支持：通過 visualization.py 腳本，依據存儲的關係數據生成 MermaidJS 調用圖，直觀呈現代碼結構。

📦 安裝指南

安裝依賴

pip install weaviate-client python-multipart fastapi uvicorn

初始化配置

創建 .env 文件：

WEAVIATE_URL=http://localhost:5000
WEAVIATE_API_KEY=your_api_key
GENERATE_LLM_DESCRIPTIONS=true  # 可選，默認為 false

啟動服務器

uvicorn mcp_server:app --reload

📚 詳細文檔

系統主要由以下模塊構成：

• 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 調用圖，直觀展示代碼結構。

系統藉助 Weaviate 的多租戶功能存儲 CodeFile 和 CodeElement，租戶 ID 為用戶定義的 codebase_name。獨立的非多租戶集合 CodebaseRegistry 用於記錄代碼庫元數據（名稱、目錄、狀態、摘要、監視器狀態、依賴關係）。MCP 服務器中的全局變量 ACTIVE_CODEBASE_NAME 確定主要代碼庫租戶用於查詢。工具 (find_element, ask_question) 可選擇性地在活動代碼庫及其聲明的依賴項中進行搜索。

背景 LLM 處理用於生成代碼元素的語義描述和嵌入，此功能可通過 .env 文件進行啟用或禁用。