FileScopeMCP-Server (Model Context Protocol)

✨ Verstehen und visualisieren Sie sofort die Struktur und Abhängigkeiten Ihrer Codebasis! ✨

Ein TypeScript-basiertes Tool zum Sortieren von Dateien in Ihrer Codebasis nach Wichtigkeit, zum Verfolgen von Abhängigkeiten und zum Bereitstellen von Zusammenfassungen zum besseren Verständnis der Codestruktur.

Überblick

Dieser MCP-Server analysiert Ihre Codebasis, um die wichtigsten Dateien anhand von Abhängigkeitsbeziehungen zu identifizieren. Er generiert Wichtigkeitsbewertungen (0–10) für jede Datei, verfolgt bidirektionale Abhängigkeiten und ermöglicht Ihnen das Hinzufügen benutzerdefinierter Zusammenfassungen für Dateien. Alle diese Informationen werden KI-Tools über das Model Context Protocol von Cursor zur Verfügung gestellt.

Merkmale

🚀 Steigern Sie Ihr Code-Verständnis! FileScopeMCP liefert Einblicke direkt an Ihren KI-Assistenten:

• 🎯 Dateiwichtigkeitsanalyse

  • Ordnen Sie Dateien auf einer Skala von 0 bis 10 basierend auf ihrer Rolle in der Codebasis.

  • Berechnen Sie die Wichtigkeit anhand eingehender/ausgehender Abhängigkeiten.

  • Identifizieren Sie sofort die wichtigsten Dateien in Ihrem Projekt.

  • Bei der intelligenten Berechnung werden Dateityp, Speicherort und Bedeutung des Namens berücksichtigt.

• 🔗 Abhängigkeitsverfolgung

  • Ordnen Sie bidirektionale Abhängigkeitsbeziehungen zwischen Dateien zu.

  • Identifizieren Sie, welche Dateien eine bestimmte Datei importieren (abhängige Dateien).

  • Sehen Sie, welche Dateien von einer bestimmten Datei importiert werden (Abhängigkeiten).

  • Unterscheiden Sie zwischen lokalen und Paketabhängigkeiten.

  • Mehrsprachige Unterstützung: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.

• 📊 Visualisierung

  • Generieren Sie Mermaid-Diagramme zur Visualisierung von Dateibeziehungen.

  • Farbcodierte Visualisierung basierend auf Wichtigkeitsbewertungen.

  • Unterstützung für Abhängigkeitsdiagramme, Verzeichnisbäume oder Hybridansichten.

  • HTML-Ausgabe mit eingebettetem Rendering, einschließlich Themenumschaltung und reaktionsfähigem Design.

  • Passen Sie die Diagrammtiefe an, filtern Sie nach Wichtigkeit und passen Sie die Layoutoptionen an.

• 📝 Dateizusammenfassungen

  • Fügen Sie jeder Datei von Menschen oder KI erstellte Zusammenfassungen hinzu.

  • Rufen Sie gespeicherte Zusammenfassungen ab, um den Dateizweck schnell zu erfassen.

  • Zusammenfassungen bleiben auch nach Serverneustarts bestehen.

• 📚 Unterstützung mehrerer Projekte

  • Erstellen und verwalten Sie mehrere Dateibäume für verschiedene Projektbereiche.

  • Konfigurieren Sie separate Bäume mit unterschiedlichen Basisverzeichnissen.

  • Wechseln Sie mühelos zwischen verschiedenen Dateibäumen.

  • Zwischengespeicherte Bäume für schnellere nachfolgende Vorgänge.

• 💾 Dauerhafter Speicher

  • Alle Daten werden automatisch im JSON-Format auf der Festplatte gespeichert.

  • Laden Sie vorhandene Dateibäume, ohne das Dateisystem erneut zu scannen.

  • Verfolgen Sie, wann Dateibäume zuletzt aktualisiert wurden.

Installation

1. Dieses Repository klonen

2. Erstellen Sie das Projekt:

   Das Build-Skript installiert alle Knotenabhängigkeiten und generiert mcp.json für Sie.

   Windows:

   build.bat

   Kopieren Sie die generierte mcp.json-Konfiguration in das .cursor -Verzeichnis Ihres Projekts:

   { "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: (Cursor in Windows, aber Ihr Projekt ist in Linux WSL, dann setzen Sie das MCP in Linux und erstellen Sie es)

   build.sh
   { "mcpServers": { "FileScopeMCP": { "command": "wsl", "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }

3. Aktualisieren Sie den Argumentpfad --base-dir auf den Basispfad Ihres Projekts.

Wie es funktioniert

Abhängigkeitserkennung

Das Tool durchsucht den Quellcode nach Importanweisungen und anderen sprachspezifischen Mustern:

• Python: import und from ... import Importanweisungen

• JavaScript/TypeScript: import und require() -Aufrufe

• C/C++: # #include Direktiven

• Rust: use und mod -Anweisungen

• Lua: require -Anweisungen

• Zig: @import -Direktiven

Wichtigkeitsberechnung

Den Dateien werden Wichtigkeitsbewertungen (0–10) auf Grundlage einer gewichteten Formel zugewiesen, die Folgendes berücksichtigt:

• Anzahl der Dateien, die diese Datei importieren (Abhängige)

• Anzahl der Dateien, die diese Datei importiert (Abhängigkeiten)

• Dateityp und Erweiterung (wobei TypeScript-/JavaScript-Dateien höhere Basiswerte erzielen)

• Position in der Projektstruktur (Dateien in src/ werden höher gewichtet)

• Dateibenennung (Dateien wie „Index“, „Main“, „Server“ usw. erhalten zusätzliche Punkte)

Eine Datei, die für die Codebasis von zentraler Bedeutung ist (von vielen Dateien importiert), erhält eine höhere Punktzahl.

Diagrammgenerierung

Das System verwendet einen dreiphasigen Ansatz, um eine gültige Mermaid-Syntax zu generieren:

1. Erfassungsphase: Alle Knoten und Beziehungen registrieren

2. Knotendefinitionsphase: Generierung von Definitionen für alle Knoten vor allen Referenzen

3. Kantengenerierungsphase: Erstellen Sie Kanten zwischen definierten Knoten

Dadurch wird sichergestellt, dass alle Diagramme eine gültige Syntax aufweisen und korrekt dargestellt werden. Die HTML-Ausgabe umfasst:

• Responsive Design, das auf jedem Gerät funktioniert

• Umschalten zwischen hellem und dunklem Design mit Erkennung der Systemeinstellungen

• Clientseitiges Mermaid-Rendering für optimale Leistung

• Zeitstempel der Generierung

Pfadnormalisierung

Um eine einheitliche Dateiidentifizierung zu gewährleisten, verarbeitet das System verschiedene Pfadformate:

• Windows- und Unix-Pfadformate

• Absolute und relative Pfade

• URL-codierte Pfade

• Plattformübergreifende Kompatibilität

Dateispeicherung

Alle Dateibaumdaten werden in JSON-Dateien mit der folgenden Struktur gespeichert:

• Konfigurationsmetadaten (Dateiname, Basisverzeichnis, Zeitstempel der letzten Aktualisierung)

• Vollständiger Dateibaum mit Abhängigkeiten, abhängigen Objekten, Wichtigkeitsbewertungen und Zusammenfassungen

Technische Details

• TypeScript/Node.js : Erstellt mit TypeScript für Typsicherheit und moderne JavaScript-Funktionen

• Model Context Protocol : Implementiert die MCP-Spezifikation für die Integration mit Cursor

• Mermaid.js : Verwendet die Mermaid-Syntax zur Diagrammerstellung

• JSON-Speicher : Verwendet einfache JSON-Dateien zur Persistenz

• Pfadnormalisierung : Plattformübergreifende Pfadverarbeitung zur Unterstützung von Windows und Unix

• Caching : Implementiert Caching für schnellere wiederholte Vorgänge

Verfügbare Tools

Der MCP-Server stellt die folgenden Tools bereit:

Dateibaumverwaltung

• list_saved_trees : Listet alle gespeicherten Dateibäume auf

• create_file_tree : Erstellen Sie eine neue Dateibaumkonfiguration für ein bestimmtes Verzeichnis

• select_file_tree : Wählen Sie einen vorhandenen Dateibaum aus, mit dem Sie arbeiten möchten

• delete_file_tree : Löscht eine Dateibaumkonfiguration

Dateianalyse

• list_files : Listet alle Dateien im Projekt mit ihrer Wichtigkeitsbewertung auf

• get_file_importance : Erhalten Sie detaillierte Informationen zu einer bestimmten Datei, einschließlich Abhängigkeiten und abhängigen Elementen

• find_important_files : Finden Sie die wichtigsten Dateien im Projekt anhand konfigurierbarer Kriterien

• read_file_content : Liest den Inhalt einer bestimmten Datei

• recalculate_importance : Berechnen Sie die Wichtigkeitswerte für alle Dateien basierend auf Abhängigkeiten neu

Dateizusammenfassungen

• get_file_summary : Ruft die gespeicherte Zusammenfassung einer bestimmten Datei ab

• set_file_summary : Setzt oder aktualisiert die Zusammenfassung einer bestimmten Datei

Dateiüberwachung

• toggle_file_watching : Dateiüberwachung ein-/ausschalten

• get_file_watching_status : Ruft den aktuellen Status der Dateiüberwachung ab

• update_file_watching_config : Dateiüberwachungskonfiguration aktualisieren

Diagrammgenerierung

• generate_diagram : Erstellen Sie Mermaid-Diagramme mit anpassbaren Optionen

  • Ausgabeformate: Mermaid-Text ( .mmd ) oder HTML mit eingebettetem Rendering

  • Diagrammstile: Standard-, Abhängigkeits-, Verzeichnis- oder Hybridansichten

  • Filteroptionen: maximale Tiefe, minimale Wichtigkeitsschwelle

  • Layoutoptionen: Richtung (TB, BT, LR, RL), Knotenabstand, Rangabstand

Anwendungsbeispiele

Der einfachste Weg, loszulegen, besteht darin, diesen MCP im Cursor zu aktivieren und ihn anzuweisen, ihn zu erkennen und zu verwenden. Sobald der MCP startet, erstellt er einen initialen JSON-Baum. Weisen Sie einen LLM an, Zusammenfassungen aller wichtigen Dateien zu erstellen und verwenden Sie die set_file_summary des MCP, um diese hinzuzufügen.

Analysieren eines Projekts

1. Erstellen Sie einen Dateibaum für Ihr Projekt:

   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")

2. Finden Sie die wichtigsten Dateien:

   find_important_files(limit: 5, minImportance: 5)

3. Erhalten Sie detaillierte Informationen zu einer bestimmten Datei:

   get_file_importance(filepath: "/path/to/project/src/main.ts")

Arbeiten mit Zusammenfassungen

1. Lesen Sie den Inhalt einer Datei, um ihn zu verstehen:

   read_file_content(filepath: "/path/to/project/src/main.ts")

2. Fügen Sie der Datei eine Zusammenfassung hinzu:

   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. Rufen Sie die Zusammenfassung später ab:

   get_file_summary(filepath: "/path/to/project/src/main.ts")

Diagramme erstellen

1. Erstellen Sie ein grundlegendes Projektstrukturdiagramm:

   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")

2. Generieren Sie ein HTML-Diagramm mit Abhängigkeitsbeziehungen:

   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")

3. Passen Sie das Diagrammlayout an:

   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

Verwenden der Dateiüberwachung

1. Aktivieren Sie die Dateiüberwachung für Ihr Projekt:

   toggle_file_watching()

2. Überprüfen Sie den aktuellen Dateiüberwachungsstatus:

   get_file_watching_status()

3. Dateiüberwachungskonfiguration aktualisieren:

   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

Zukünftige Verbesserungen

• Unterstützung für weitere Programmiersprachen hinzufügen

• Fügen Sie anspruchsvollere Algorithmen zur Berechnung der Wichtigkeit hinzu

• Erweiterte Diagrammanpassungsoptionen

• Unterstützung für den Export von Diagrammen in zusätzliche Formate

Lizenz

Dieses Projekt ist unter der GNU General Public License v3 (GPL-3.0) lizenziert. Den vollständigen Lizenztext finden Sie in der Datei LICENSE .