TokenScope

Token-fähiger Verzeichnis-Explorer für große Sprachmodelle (LLMs).

Ein Model Context Protocol (MCP) -Server, der LLMs dabei hilft, Codebasen und Verzeichnisstrukturen effizient zu erkunden und zu verstehen.

Überblick

TokenScope bietet intelligente Verzeichnisstrukturanalyse und tokenbasierte Dateiinhaltserkundung für LLMs wie Claude. Es hilft LLMs, Codebasen zu verstehen, indem es:

1. Erkunden von Verzeichnisstrukturen mit tokenbasierter Zusammenfassung

2. Anzeigen von Dateiinhalten unter Berücksichtigung von Token-Einschränkungen

3. Erstellen umfassender Berichte über Verzeichnisse

Related MCP server: Compiler Explorer MCP

Hauptmerkmale

Token-fähige Verzeichniserkundung

• Automatische Zusammenfassung für große Verzeichnisse bei vollständiger Anzeige kleiner Verzeichnisse

• Einhaltung der Token-Grenzen , um nützliche Informationen innerhalb der Einschränkungen zu maximieren

• Integrierte Sicherheit mit Basispfadvalidierung

• Intelligente Filterung mit Standardmustern und .gitignore-Unterstützung

• Genaue Verzeichnisstatistiken selbst für die größten Verzeichnisse

Einfache, intuitive Tools

TokenScope bietet nur drei Kerntools:

1. explore_directory - Verzeichnisstrukturen scannen und verstehen

2. view_content - Zugriff auf Dateiinhalte mit Token-Bewusstsein

3. generate_report - Erstellen Sie umfassende Berichte (mit der Option zum Speichern in einer Datei)

Installation

Voraussetzungen

• Python 3.10 oder höher

• uv (empfohlen für die Abhängigkeitsverwaltung)

Installation (PyPI)

Dies ist die empfohlene Methode für die meisten Benutzer, die nur TokenScope verwenden möchten:

# Install from PyPI using uv (recommended)
uv pip install tokenscope

Ausführen von TokenScope

Das Argument --base-path ist aus Sicherheitsgründen obligatorisch. Es beschränkt alle Dateivorgänge auf das angegebene Verzeichnis.

# Run using the installed package
uv run --with tokenscope tokenscope --base-path /path/to/allowed/directory

Konfigurieren in Claude Desktop

1. Suchen Sie die Konfigurationsdatei von Claude Desktop (normalerweise ~/.config/claude/config.json ).

2. Fügen Sie TokenScope zum Abschnitt mcpServers hinzu:

"mcpServers": {
  "TokenScope": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "tokenscope",
      "tokenscope",
      "--base-path",
      "/your/secure/base/path"
    ]
  }
}

3. Ersetzen Sie /your/secure/base/path durch das Verzeichnis, auf das Sie Operationen beschränken möchten

4. Speichern Sie die Konfigurationsdatei und starten Sie Claude Desktop neu

Verwendung

Ausführen des TokenScope-Servers

Das Argument --base-path ist aus Sicherheitsgründen erforderlich (es beschränkt Dateivorgänge auf das angegebene Verzeichnis):

tokenscope --base-path /path/to/allowed/directory

Tools direkt testen

TokenScope beinhaltet einen Testmodus zum direkten Ausprobieren von Tools:

# Test directory exploration
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory"

# Test with custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory?ignore=cache,*.log,tmp/&gitignore=false"

# Test file viewing
tokenscope --base-path /path/to/allowed/directory --test "view:/path/to/file"

# Test report generation
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory"

# Test report generation with file output and custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory?ignore=*.bak,temp/ > /path/to/output.md"

Beispiel-Eingabeaufforderungen

Hier sind einige Beispiele für die Verwendung von TokenScope mit Claude:

Could you explore my project directory at /path/to/project and tell me about its structure?

Can you show me the content of the file at /path/to/file.py?

Please generate a comprehensive report about my project at /path/to/project and save it to /path/to/report.md

Genaue Verzeichnisstatistiken

TokenScope bietet jetzt zwei Ebenen von Verzeichnisinformationen:

1. Quick Scan-Statistiken : Informationen zu Dateien und Verzeichnissen, die in der Baumansicht sichtbar sind

2. Vollständige Verzeichnisstatistik : Vollständige Zählung ALLER Dateien und Verzeichnisse, auch in sehr großen Repositories

Dieser duale Ansatz stellt sicher, dass Sie selbst bei riesigen Verzeichnissen (mit Tausenden oder Millionen von Dateien) genaue Informationen über die Gesamtzahl der Dateien, Verzeichnisse und die Festplattennutzung erhalten. Dies ist besonders wertvoll bei der Arbeit mit großen Codebasen, bei denen eine vollständige Verzeichnisliste die Token-Grenze überschreiten würde.

Beispielausgabe

QUICK SCAN STATISTICS (files visible in tree):
Files shown in tree: 47
Directories shown in tree: 16
Size shown in tree: 185.9 MB

FULL DIRECTORY STATISTICS (all files):
Total files: 16,059
Total directories: 8
Total disk size: 2.1 GB

Intelligentes Filtern mit Ignoriermustern

TokenScope filtert automatisch allgemeine Verzeichnisse und Dateien heraus, die normalerweise nicht zum Verständnis einer Codebasis beitragen:

• Standardmäßig ignorierte Muster : .git/ , .venv/ , venv/ , __pycache__/ , node_modules/ , build/ , dist/ usw.

• Benutzerdefinierte Ignoriermuster : Sie können zusätzliche zu ignorierende Muster über den Parameter ignore_patterns angeben

• .gitignore-Unterstützung : TokenScope kann .gitignore-Dateien in den gescannten Verzeichnissen automatisch berücksichtigen

Diese Funktionalität hilft, die Token-Verschwendung für irrelevante Dateien und Verzeichnisse zu vermeiden, wie zum Beispiel:

• Abhängigkeitsverzeichnisse (z. B. node_modules , virtuelle Umgebungen)

• Erstellen Sie Artefakte und Cache-Verzeichnisse

• Metadaten zur Versionskontrolle

• IDE-Konfigurationsdateien

Verwenden von Ignoriermustern im CLI-Testmodus

# Ignore specific patterns
tokenscope --base-path /path --test "explore:/code?ignore=*.log,temp/"

# Disable .gitignore processing
tokenscope --base-path /path --test "explore:/code?gitignore=false"

# Both together
tokenscope --base-path /path --test "explore:/code?ignore=*.tmp&gitignore=false"

Sicherheitsfunktionen

TokenScope enthält wichtige Sicherheitsfunktionen:

• Alle Dateivorgänge werden überprüft, um sicherzustellen, dass sie sich im angegebenen Basisverzeichnis befinden

• Versuche, auf Dateien außerhalb des Basispfads zuzugreifen, werden abgelehnt

• Der Basispfad wird einmalig beim Serverstart festgelegt und kann ohne Neustart nicht geändert werden

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE.

Danksagung

• Erstellt mit FastMCP

• Verwendet TikToken für eine genaue Token-Zählung