FileScopeMCP（モデルコンテキストプロトコル）サーバー

✨ コードベースの構造と依存関係を即座に理解し、視覚化します! ✨

コードベース内のファイルを重要度でランク付けし、依存関係を追跡し、コード構造を理解するのに役立つ概要を提供する TypeScript ベースのツールです。

概要

このMCPサーバーは、コードベースを分析し、依存関係に基づいて最も重要なファイルを特定します。各ファイルの重要度スコア（0～10）を生成し、双方向の依存関係を追跡し、ファイルにカスタムサマリーを追加できます。これらの情報はすべて、Cursorのモデルコンテキストプロトコルを介してAIツールに提供されます。

特徴

🚀コード理解を強化！ FileScopeMCP は AI アシスタントに直接洞察を提供します。

• 🎯 ファイルの重要度分析
  • コードベースでの役割に基づいて、ファイルを 0 ～ 10 のスケールでランク付けします。
  • 入ってくる/出ていく依存関係を使用して重要度を計算します。
  • プロジェクト内で最も重要なファイルを即座に特定します。
  • スマート計算では、ファイルの種類、場所、名前の重要性を考慮します。
• 🔗 依存関係の追跡
  • ファイル間の双方向の依存関係をマップします。
  • 特定のファイルをインポートするファイル (依存関係) を識別します。
  • 特定のファイルによってインポートされるファイル (依存関係) を確認します。
  • ローカル依存関係とパッケージ依存関係を区別します。
  • 多言語サポート: Python、JavaScript、TypeScript、C/C++、Rust、Lua、Zig。
• 📊 視覚化
  • ファイルの関係を視覚化するために Mermaid ダイアグラムを生成します。
  • 重要度スコアに基づいて色分けされた視覚化。
  • 依存関係グラフ、ディレクトリ ツリー、ハイブリッド ビューのサポート。
  • テーマの切り替えやレスポンシブ デザインなどのレンダリングが埋め込まれた HTML 出力。
  • 図の深さをカスタマイズし、重要度でフィルタリングし、レイアウト オプションを調整します。
• 📝 ファイルの概要
  • 人間または AI によって生成された要約を任意のファイルに追加します。
  • 保存された要約を取得して、ファイルの目的をすぐに把握します。
  • 概要はサーバーの再起動後も保持されます。
• 📚 複数プロジェクトのサポート
  • さまざまなプロジェクト領域に対して複数のファイル ツリーを作成および管理します。
  • 異なるベース ディレクトリを持つ個別のツリーを構成します。
  • さまざまなファイル ツリー間を簡単に切り替えます。
  • 後続の操作を高速化するためにツリーをキャッシュします。
• 💾 永続ストレージ
  • すべてのデータは JSON 形式で自動的にディスクに保存されます。
  • ファイルシステムを再スキャンせずに既存のファイルツリーをロードします。
  • ファイル ツリーが最後に更新された日時を追跡します。

インストール

1. このリポジトリをクローンする
2. プロジェクトをビルドします。ビルド スクリプトはすべてのノード依存関係をインストールし、mcp.json を生成します。ウィンドウズ:
   build.bat
   生成された mcp.json 構成をプロジェクトの.cursorディレクトリにコピーします。
   { "mcpServers": { "FileScopeMCP": { "command": "node", "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }
   Linux: (カーソルは Windows ですが、プロジェクトは Linux WSL にあるので、MCP を Linux に置いてビルドします)
   build.sh
   { "mcpServers": { "FileScopeMCP": { "command": "wsl", "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }
3. 引数パス --base-dir をプロジェクトのベース パスに更新します。

仕組み

依存関係の検出

このツールは、ソース コードをスキャンして、import ステートメントやその他の言語固有のパターンを探します。

• Python: importおよびfrom ... importステートメント
• JavaScript/TypeScript: import文とrequire()呼び出し
• C/C++: #includeディレクティブ
• Rust: useとmod文
• Lua: require文
• Zig: @importディレクティブ

重要度の計算

ファイルには、次の要素を考慮した重み付けの式に基づいて重要度スコア (0 ～ 10) が割り当てられます。

• このファイルをインポートするファイルの数（依存）
• このファイルがインポートするファイルの数（依存関係）
• ファイルの種類と拡張子（TypeScript/JavaScript ファイルはより高い基本スコアを獲得します）
• プロジェクト構造内の場所（ src/内のファイルは重みが高くなります）
• ファイルの命名（「index」、「main」、「server」などのファイルは追加ポイントを獲得します）

コードベースの中心となるファイル (多くのファイルによってインポートされるファイル) は、スコアが高くなります。

ダイアグラム生成

システムは、3 段階のアプローチを使用して、有効な Mermaid 構文を生成します。

1. 収集フェーズ: すべてのノードと関係を登録する
2. ノード定義フェーズ: 参照の前にすべてのノードの定義を生成する
3. エッジ生成フェーズ: 定義されたノード間にエッジを作成する

これにより、すべての図の構文が有効になり、正しくレンダリングされます。HTML 出力には以下が含まれます。

• あらゆるデバイスで動作するレスポンシブデザイン
• システム設定検出によるライト/ダークテーマの切り替え
• 最適なパフォーマンスを実現するクライアント側 Mermaid レンダリング
• 生成のタイムスタンプ

パスの正規化

システムは、一貫したファイル識別を確保するためにさまざまなパス形式を処理します。

• WindowsとUnixのパス形式
• 絶対パスと相対パス
• URLエンコードされたパス
• クロスプラットフォームの互換性

ファイルストレージ

すべてのファイル ツリー データは、次の構造の JSON ファイルに保存されます。

• 構成メタデータ（ファイル名、ベースディレクトリ、最終更新タイムスタンプ）
• 依存関係、従属関係、重要度スコア、要約を含む完全なファイルツリー

技術的な詳細

• TypeScript/Node.js : 型安全性と最新のJavaScript機能のためにTypeScriptで構築されています
• モデルコンテキストプロトコル:カーソルとの統合のためのMCP仕様を実装します
• Mermaid.js : 図生成に Mermaid 構文を使用します
• JSONストレージ: 永続化のためにシンプルなJSONファイルを使用する
• パスの正規化: Windows と Unix をサポートするクロスプラットフォームのパス処理
• キャッシュ: 繰り返し操作を高速化するためにキャッシュを実装します

利用可能なツール

MCP サーバーは次のツールを公開します。

ファイルツリー管理

• list_saved_trees : 保存されたすべてのファイルツリーを一覧表示する
• create_file_tree : 特定のディレクトリの新しいファイルツリー構成を作成する
• select_file_tree : 作業する既存のファイルツリーを選択する
• delete_file_tree : ファイルツリー構成を削除する

ファイル分析

• list_files : プロジェクト内のすべてのファイルを重要度ランキングとともに一覧表示します
• get_file_importance : 依存関係や従属ファイルを含む特定のファイルに関する詳細情報を取得します。
• find_important_files : 設定可能な基準に基づいてプロジェクト内で最も重要なファイルを検索します
• read_file_content : 特定のファイルの内容を読み取る
• recalculate_importance : 依存関係に基づいてすべてのファイルの重要度値を再計算します

ファイルの概要

• get_file_summary : 特定のファイルの保存された要約を取得する
• set_file_summary : 特定のファイルの概要を設定または更新する

ファイル監視

• toggle_file_watching : ファイルの監視のオン/オフを切り替える
• get_file_watching_status : ファイル監視の現在のステータスを取得する
• update_file_watching_config : ファイル監視設定の更新

ダイアグラム生成

• generate_diagram : カスタマイズ可能なオプションでマーメイドダイアグラムを作成する
  • 出力形式: マーメイドテキスト ( .mmd ) またはレンダリングが埋め込まれた HTML
  • ダイアグラムのスタイル: デフォルト、依存関係、ディレクトリ、またはハイブリッド ビュー
  • フィルターオプション: 最大深度、最小重要度しきい値
  • レイアウト オプション: 方向 (TB、BT、LR、RL)、ノード間隔、ランク間隔

使用例

最も簡単な方法は、カーソルでこのMCPを有効にし、カーソルにMCPを認識させて使用させることです。MCPは起動するとすぐに、初期のJSONツリーを構築します。LLMに重要なファイルすべてのサマリーを作成するように指示し、MCPのset_file_summaryを使ってサマリーを追加します。

プロジェクトの分析

1. プロジェクトのファイルツリーを作成します。
   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
2. 最も重要なファイルを見つけます:
   find_important_files(limit: 5, minImportance: 5)
3. 特定のファイルに関する詳細情報を取得します。
   get_file_importance(filepath: "/path/to/project/src/main.ts")

要約の操作

1. ファイルの内容を読んで理解します。
   read_file_content(filepath: "/path/to/project/src/main.ts")
2. ファイルに要約を追加します。
   set_file_summary(filepath: "/path/to/project/src/main.ts", summary: "Main entry point that initializes the application, sets up routing, and starts the server.")
3. 後で要約を取得します:
   get_file_summary(filepath: "/path/to/project/src/main.ts")

図表の生成

1. 基本的なプロジェクト構造図を作成します。
   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
2. 依存関係を含む HTML ダイアグラムを生成します。
   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
3. 図のレイアウトをカスタマイズします。
   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

ファイル監視の使用

1. プロジェクトのファイル監視を有効にします。
   toggle_file_watching()
2. 現在のファイル監視ステータスを確認します。
   get_file_watching_status()
3. ファイル監視設定を更新します:
   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

今後の改善

• より多くのプログラミング言語のサポートを追加する
• より洗練された重要度計算アルゴリズムを追加する
• 図のカスタマイズオプションの強化
• ダイアグラムを追加形式にエクスポートするためのサポート

ライセンス

このプロジェクトは、GNU General Public License v3 (GPL-3.0) に基づいてライセンスされています。ライセンスの全文については、 LICENSEファイルをご覧ください。