Codebasemcp

🚀 Python コードライブラリ分析 RAG システム

このシステムは、Python ファイルの抽象構文木 (AST) を解析してコードを分析し、抽出した情報（関数、クラス、呼び出し、変数など）を Weaviate ベクトルデータベースに保存します。また、Model Context Protocol (MCP) サーバーを通じてコードライブラリをクエリし、理解するためのツールを提供します。システムは Google の Gemini モデルを利用して、埋め込み表現と自然言語の説明/回答を生成します。

✨ 主な機能

• コードスキャン：Python ファイルを解析して、コード要素（関数、クラス、インポート、呼び出し、代入）とその関係を識別します。以下の情報を抽出します。

  • 基本情報：名前、タイプ、ファイルパス、行番号、コード断片、ドキュメント文字列。
  • 関数/メソッドの詳細：パラメータ、戻り値の型、シグネチャ、デコレータ。
  • スコープ情報：親スコープ（クラス/関数）の UUID、読みやすい ID（例：file:type,name）、位置情報（開始と終了の行/列）。
  • メタデータ：コードファイルのハッシュ値（バージョン管理用）、スキャンタイムスタンプ（分析時刻の記録）。

• ベクトルデータベースの統合：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 ファイルを通じてオプションで有効/無効にできます。