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 文件进行启用或禁用。