星战科技xingzhan.cloud
返回市场
代码库MCP

代码库MCP

作者：shervinemp5 星标更新：2025-09-23
安装使用来源：spider==github.com

项目介绍

Python 代码库分析 RAG 系统

该系统使用抽象语法树（AST）分析Python代码，将提取的信息（函数、类、调用、变量等）存储在Weaviate向量数据库中，并通过模型上下文协议（MCP）服务器提供查询和理解代码库的工具。它利用Google的Gemini模型生成嵌入式表示和自然语言描述/答案。

功能

  • 代码扫描： 解析Python文件以识别代码元素（函数、类、导入、调用、赋值）及其关系。提取：
    • 基本信息：名称、类型、文件路径、行号、代码片段、文档字符串。
    • 函数/方法详情：参数、返回类型、签名、装饰器。
    • 范围信息：父级作用域（类/函数）UUID、可读ID（例如，file:type:name:line）、基类名称。
    • 使用信息：作用域内的属性访问、调用关系（部分跟踪）。
  • 向量存储： 使用Weaviate存储代码元素及其向量嵌入（当启用LLM生成时）。
  • LLM增强（可选及后台运行）： 使用Gemini生成函数和类的语义描述和嵌入。现在作为扫描后或手动触发的后台任务运行。可以通过.env文件启用或禁用。
  • 自动精炼（可选及后台运行）： 当启用LLM生成时，根据上下文（调用者、被调用者、兄弟节点、相关变量）自动精炼新/更新函数的描述，作为后台处理的一部分。
  • RAG 问答： 使用检索增强生成回答关于代码库的自然语言问题（需要启用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实例：

    docker-compose up -d

  3. 依赖项： 安装Python包：

    pip install -r requirements.txt

  4. API密钥与配置： 在项目根目录创建一个.env文件，并添加您的Gemini API密钥。您还可以配置其他设置：

    # --- 必需 ---
GEMINI_API_KEY=YOUR_API_KEY_HERE

# --- 可选 ---
# 设置为true以启用背景LLM描述生成和精炼
GENERATE_LLM_DESCRIPTIONS=true
# 最大并发背景LLM任务（嵌入/描述/精炼）
LLM_CONCURRENCY=5
# ANALYZE_ON_STARTUP不再使用。扫描是通过scan_codebase工具进行的。

# 如果不使用默认设置，请指定Weaviate连接详情
# WEAVIATE_HOST=localhost
# WEAVIATE_PORT=8080
# WEAVIATE_GRPC_PORT=50051

# 如有需要，指定替代Gemini模型
# GENERATION_MODEL_NAME="models/gemini-pro"
# EMBEDDING_MODEL_NAME="models/embedding-001"

# 调整Weaviate批处理大小
# WEAVIATE_BATCH_SIZE=100

# SEMANTIC_SEARCH_LIMIT=5
# SEMANTIC_SEARCH_DISTANCE=0.7
# 监视器轮询间隔（秒）
# WATCHER_POLLING_INTERVAL=5

  5. 运行MCP服务器： 在单独的终端中启动服务器：

    python src/code_analysis_mcp/mcp_server.py

    (确保此终端保持运行以便工具可用)

架构概述

该系统分析Python代码，将提取的信息存储在Weaviate向量数据库中，并通过模型上下文协议（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调用图。

该系统使用Weaviate的多租户功能来处理CodeFile和CodeElement集合，其中租户ID是用户定义的codebase_name。一个独立的非多租户CodebaseRegistry集合跟踪代码库元数据（名称、目录、状态、摘要、监视器状态、依赖项）。服务器中的全局变量ACTIVE_CODEBASE_NAME确定查询的主要代码库租户。查询工具（find_element，ask_question）可以选择性地搜索活动代码库及其注册表中声明的依赖项。list_codebases工具可用于查看所有代码库的状态和依赖项。

后台LLM处理用于生成代码元素的语义描述和嵌入。这是一个可选功能，可以通过.env文件启用或禁用。

一旦服务器运行，可以使用标准的MCP内省方法直接从MCP服务器获取有关可用工具及其参数的详细信息。