Code Flow MCP

🚀 CodeFlow: 認知負荷を最適化したコード分析ツール

CodeFlowは、Pythonベースの強力なコード分析ツールです。開発者や自律エージェントが最小限の認知負荷で複雑なコードベースを理解できるように設計されています。詳細な呼び出しグラフを生成し、重要なコード要素を特定し、意味検索機能を提供します。これらの機能は、人間の理解を優先する原則に基づいています。

抽象構文木（AST）から豊富なメタデータを抽出し、永続的なベクトルストア（ChromaDB）を活用することで、CodeFlowはコード構造と動作の効率的なクエリと可視化を可能にします。

このツールには2つの主要なインターフェースがあります。

• CLIツール：コードベースの直接分析とクエリを行うためのコマンドラインインターフェース。
• MCPサーバー：AIアシスタントやIDEと統合して、リアルタイムのコード分析を行うためのモデルコンテキストプロトコルサーバー。

✨ 主な機能

コア分析機能

• 深いASTメタデータ抽出（Python）：関数やクラスに関する包括的な詳細を収集します。
  • パラメータ、戻り値の型、ドキュメント文字列
  • 循環的複雑度とコメント以外のコード行数（NLOC）
  • 適用されたデコレータ（例：@app.route、@transactional）
  • 明示的に捕捉された例外
  • ローカルで宣言された変数
  • 推測される外部ライブラリ/モジュールの依存関係
  • 効率的な変更検出のためのソース本文のハッシュ
• インテリジェントな呼び出しグラフ生成：
  • 関数間の呼び出しグラフを構築します。
  • 複数のヒューリスティックを使用して、コードベース内の潜在的なエントリポイントを特定します。
• 永続的なベクトルストア（ChromaDB）：
  • 抽出されたすべてのコード要素と呼び出しエッジを意味埋め込みとして保存します。
  • コードベースの関数とそのメタデータに対する迅速な意味検索とフィルター付きクエリを可能にします。
  • 分析結果をディスクに保存するため、以前に分析したプロジェクトを再解析することなく即座にクエリできます。

可視化と出力

• Mermaid図の可視化：
  • 呼び出しグラフのためのテキストベースのMermaidフローチャート構文を生成します。
  • 意味クエリに関連する関数を強調表示します。
  • LLM最適化モードを含み、大規模言語モデルに適した簡潔でトークン効率の良いグラフ表現を提供し、明確なエイリアスと完全修飾名（FQN）のマッピングを含みます。

MCPサーバーの機能

• リアルタイム分析：動的なコードベースに対するファイル監視と増分更新。
• ツールベースのAPI：AIアシスタント用のMCPツールを介して分析機能を公開します。
• セッションコンテキスト：複雑な分析ワークフローのためのセッションごとの状態を維持します。
• 包括的なツール：意味検索、呼び出しグラフ生成、関数メタデータの取得、エントリポイントの特定、およびMermaidグラフの生成。

CLIツールの機能

• バッチ分析：レポートを生成しながら、コードベース全体を分析します。
• インタラクティブなクエリ：分析済みのコードベースに対する意味検索。
• 柔軟な出力：JSONレポート、Mermaid図、およびコンソール出力。
• 増分更新：完全な再処理なしで既存の分析をクエリできます。

認知負荷の最適化

• ツールの出力とコードベース自体が理解しやすく使いやすいように設計されています。
• 思考モデルの単純化：コードと出力に明確で予測可能なパターンを持ちます。
• 明示的な動作：簡潔さよりも明確さを優先し、暗黙的なアクションを可視化します（例：デコレータ）。
• 情報隠蔽と局所性：明確に定義されたモジュールで、関連するコードをまとめます。
• 最小限の背景知識：自己記述的なデータ、一般的なパターンを使用し、記憶する必要を減らします。
• 戦略的な抽象化：全体的な複雑さを真に減らす場合にのみレイヤーを導入します。
• 線形的な理解：コードと出力が上から下に読みやすいように構造化されています。

📦 インストール

ソースからのインストール

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/yourusername/codeflow.git
cd codeflow
pip install -e .

これにより、パッケージが編集可能モードでインストールされ、CLIツールとMCPサーバーの両方が使用可能になります。

CLIツール

CLIツールはモジュールとして利用できます。

python -m code_flow_graph.cli.code_flow_graph --help

MCPサーバー

MCPサーバーはスクリプトとして利用できます。

code_flow_graph_mcp_server --help

💻 使用例

CLIツール

code_flow_graph.cli.code_flow_graphモジュールは、コマンドライン分析の主要なエントリポイントです。すべてのコマンドは以下の形式で始まります。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY]

[YOUR_CODE_DIRECTORY]をあなたのプロジェクトのパスに置き換えてください。省略した場合、現在のディレクトリ（.）が使用されます。

1. コードベースを分析してレポートを生成する

このコマンドは、コードベースを解析し、呼び出しグラフを構築し、ChromaDBベクトルストア（<YOUR_CODE_DIRECTORY>/code_vectors_chroma/に保存されます）を作成し、JSONレポートを生成します。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --language python --output my_analysis_report.json

2. コードベースをクエリする（分析 + クエリ）

完全な分析を実行し、直ちに意味検索を行います。コードが変更された場合、ベクトルストアが更新されます。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --language python --query "functions that handle user authentication"

3. 既存の分析をクエリする（クエリのみ）

コードベースが分析された後（つまり、[YOUR_CODE_DIRECTORY]にcode_vectors_chroma/ディレクトリが存在する場合）、完全な分析を再実行することなく、はるかに高速にクエリできます。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --no-analyze --query "functions related to data serialization"

4. Mermaid呼び出しグラフを生成する

クエリに関連する関数のMermaid図を生成できます。

標準のMermaid（視覚的なレンダリング用）：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "database connection pooling" --mermaid

出力はMermaid構文であり、Mermaidビューア（例：VS Code拡張機能、Mermaid.live）にコピーして可視化できます。

LLM最適化Mermaid（AIエージェント用）：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "main entry point setup" --llm-optimized

この出力は視覚的なスタイリングが削除され、ノードIDに短いエイリアスが使用され、明示的な%% Alias: ShortID = Fully.Qualified.Nameコメントが含まれます。これにより、LLMのトークン数が最小限に抑えられ、必要なすべての構造情報が提供されます。

コマンドライン引数

• <directory>：（位置指定、オプション）コードベースディレクトリのパス（デフォルト：現在のディレクトリ.）。これは永続的なChromaDBストアのベースでもあります（<directory>/code_vectors_chroma/）。
• --language：プログラミング言語（pythonまたはtypescript、デフォルト：python）。
• --output：分析レポートの出力ファイル（デフォルト：code_analysis_report.json）。完全な分析時のみ使用されます。
• --query <QUESTION>：意味クエリを実行します。
• --no-analyze：（フラグ）AST抽出とグラフ構築をスキップします。--queryが必要です。既存のベクトルストアを前提とします。
• --mermaid：（フラグ）クエリ結果のMermaidグラフを生成します。--queryが必要です。
• --llm-optimized：（フラグ）LLMのトークン数に最適化されたMermaidグラフを生成します（スタイリングを削除します）。--mermaidを意味します。

レポート出力の例

code_analysis_report.jsonは、要約、特定されたエントリポイント、クラスの要約、および詳細な呼び出しグラフ（すべてのメタデータを持つ関数とエッジ）を含む包括的なJSON構造を提供します。

MCPサーバー

MCPサーバーは、モデルコンテキストプロトコルを介してCodeFlowの分析機能にプログラムからアクセスできるようにします。AIアシスタント、IDE、および他のMCP互換ツールと統合できます。

サーバーの起動

デフォルト設定でMCPサーバーを起動します。

python -m code_flow_graph.mcp_server

または、カスタム設定ファイルを使用して起動します。

python -m code_flow_graph.mcp_server --config path/to/config.yaml

利用可能なツール

サーバーは、MCPプロトコルを介して以下のツールを公開します。

• ping：サーバーの接続性をテストします。
• semantic_search：自然言語クエリを使用して関数を意味検索します。
• get_call_graph：JSONまたはMermaid形式で呼び出しグラフを取得します。
• get_function_metadata：特定の関数の詳細なメタデータを取得します。
• query_entry_points：コードベース内のすべての特定されたエントリポイントを取得します。
• generate_mermaid_graph：呼び出しグラフの可視化のためのMermaid図を生成します。
• update_context：セッションコンテキストをキーバリューペアで更新します。
• get_context：現在のセッションコンテキストを取得します。

クライアントを使用したテスト

含まれているクライアントを使用してサーバーの機能をテストします。

python client.py

これにより、ハンドシェイクが行われ、基本的なツール機能がテストされます。

📚 ドキュメント

MCPサーバーの設定

MCPサーバーはYAML設定ファイル（デフォルト：code_flow_graph/mcp_server/config/default.yaml）を使用します。

watch_directories: ["code_flow_graph"]  # 変更を監視するディレクトリ
ignored_patterns: ["venv", "**/__pycache__"]  # 分析時に無視するパターン
chromadb_path: "./code_vectors_chroma"  # ChromaDBベクトルストアのパス
max_graph_depth: 3  # グラフトラバーサルの最大深度
embedding_model: "all-MiniLM-L6-v2" # 使用する埋め込みモデル

独自の設定ファイルを作成し、--configで渡すことでこれらの設定をカスタマイズできます。

インストール前の要件

CodeFlowを実行する前に、Python 3.8以上と以下の依存関係がインストールされていることを確認してください。

chromadb
sentence-transformers
mcp[cli]
pyyaml
watchdog>=2.0
pytest
pytest-asyncio
pydantic

🔧 技術詳細

ツールのアーキテクチャ

このツールは、明確性と保守性を考慮して3つの主要なコンポーネントに構造化されています。

コアコンポーネント

1. AST抽出器 (core/ast_extractor.py)
   • ソースコードを抽象構文木に解析します。
   • FunctionElementとClassElementオブジェクトに関する豊富なメタデータ（複雑度、デコレータ、依存関係など）を抽出します。
   • .gitignoreに基づいてファイルをフィルタリングし、関連する分析を行います。
2. 呼び出しグラフビルダー (core/call_graph_builder.py)
   • 抽出されたASTデータに基づいて関数呼び出しの有向グラフを構築します。
   • 複数のヒューリスティックを使用してアプリケーションのエントリポイントを特定します。
   • 豊富なメタデータを含む構造化されたFunctionNodeとCallEdgeオブジェクトを提供します。
3. ベクトルストア (core/vector_store.py)
   • ChromaDBと統合して、永続的でクエリ可能な知識ベースを提供します。
   • 関数とエッジの意味埋め込みを、その詳細なメタデータとともに保存します。
   • 意味検索 (query_functions) とソースコードのハッシュによる効率的な更新を可能にします。

MCPサーバーのアーキテクチャ

• サーバー (mcp_server/server.py)：MCPプロトコルとツール登録を処理するMCP SDKベースのサーバー。
• アナライザー (mcp_server/analyzer.py)：ファイル監視による増分更新を伴うコア分析ロジック。
• ツール (mcp_server/tools.py)：リクエスト/レスポンスモデルを持つMCPツールの実装。
• 設定 (mcp_server/config/)：YAMLベースの設定管理。

CLIツールのアーキテクチャ

• CodeGraphAnalyzer (cli/code_flow_graph.py)：分析パイプラインの主要なオーケストレーター。
• コマンドライン引数の解析と出力のフォーマット。
• 分析とクエリのためのコアコンポーネントとの統合。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

ロードマップ

• TypeScriptの解析を強化し、Pythonとの機能を同等にする。
• 単純なローカル変数を超えた高度なデータフロー分析を行う。
• 他の可視化ツール（例：Graphviz）との統合を行う。
• 様々なフレームワークに対するより洗練されたエントリポイント検出を実装する。
• リアルタイム分析とナビゲーションのための直接的なIDE統合を行う。
• 他のプログラミング言語をサポートする。
• インタラクティブなコード探索のためのWebベースのUIを提供する。
• カスタム分析ルールのためのプラグインシステムを導入する。

謝辞

このプロジェクトは、以下の優れた成果物に基づいて構築されています。

• ChromaDB
• Sentence Transformers
• Python ASTモジュール
• Mermaid.js（図面作成用）
• MCP SDK（MCPサーバーフレームワーク用）
• Watchdog（ファイル監視用）

コントリビューション

コントリビューションを歓迎します！関与する方法の詳細については、Contributing Guide（またはあなたが作成した同様のガイド）を参照してください。

テスト

MCPサーバーのテスト

MCPサーバーのテストスイートを実行します。

pytest tests/mcp_server/

これには以下のテストが含まれます。

• サーバーの初期化とツールの登録
• ツールの機能（意味検索、呼び出しグラフなど）
• 設定の読み込み
• ファイル監視と増分更新

CLIツールのテスト

テストファイルに対して分析を実行してCLIツールをテストします。

# 基本機能のテスト
python -m code_flow_graph.cli.code_flow_graph tests/ --output test_report.json

# クエリのテスト
python -m code_flow_graph.cli.code_flow_graph tests/ --query "test functions"

統合テスト

クライアントスクリプトを使用してエンドツーエンドのテストを行います。

python client.py

これにより、MCPプロトコルのハンドシェイクと基本的なツールの相互作用がテストされます。