MCP Tree-sitter Server

Ein Model Context Protocol (MCP) Server, der Code-Analyse-Funktionen mittels tree-sitter bereitstellt und entwickelt wurde, um KI-Assistenten intelligenten Zugriff auf Codebasen mit angemessenem Kontextmanagement zu ermöglichen. Claude Desktop ist das Ziel für die Referenzimplementierung.

Funktionen

• 🔍 Flexible Erkundung: Untersuchen Sie Code auf verschiedenen Granularitätsebenen

• 🧠 Kontextmanagement: Bietet genau die richtige Menge an Informationen, ohne das Kontextfenster zu überlasten

• 🌐 Sprachunabhängig: Unterstützt viele Programmiersprachen, darunter Python, JavaScript, TypeScript, Go, Rust, C, C++, C#, Swift, Java, Kotlin, Dart, Julia und APL via tree-sitter-language-pack

• 🌳 Strukturbewusst: Nutzt AST-basiertes Verständnis mit effizienter cursor-basierter Navigation

• 🔎 Durchsuchbar: Finden Sie spezifische Muster mittels Textsuche und tree-sitter-Abfragen

• 🔄 Caching: Optimierte Leistung durch Caching von Syntaxbäumen

• 🔑 Symbol-Extraktion: Extrahieren und analysieren Sie Funktionen, Klassen und andere Code-Symbole

• 📊 Abhängigkeitsanalyse: Identifizieren und analysieren Sie Code-Abhängigkeiten und Beziehungen

• 🧩 Zustandspersistenz: Behält Projektregistrierungen und zwischengespeicherte Daten zwischen Aufrufen bei

• 🔒 Sicher: Integrierte Sicherheitsgrenzen und Eingabevalidierung

Eine umfassende Liste aller verfügbaren Befehle, deren aktueller Implementierungsstatus und eine detaillierte Funktionsmatrix finden Sie im Dokument FEATURES.md.

Related MCP server: code-index-mcp

Installation

Voraussetzungen

• Python 3.10+

• Tree-sitter Sprach-Parser für Ihre bevorzugten Sprachen

Grundlegende Installation

pip install mcp-server-tree-sitter

Entwicklungsinstallation

git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev]"

Schnellstart

Ausführung mit Claude Desktop

Sie können den Server in Claude Desktop entweder über das MCP CLI oder durch manuelle Konfiguration von Claude Desktop verfügbar machen.

Verwendung des MCP CLI

Registrieren Sie den Server bei Claude Desktop:

mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"

Manuelle Konfiguration

Alternativ können Sie Claude Desktop manuell konfigurieren:

1. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:

   • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Erstellen Sie die Datei, falls sie nicht existiert.

2. Fügen Sie den Server zum Abschnitt mcpServers hinzu:

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "python",
    "args": [
    "-m",
    "mcp_server_tree_sitter.server"
    ]
    }
    }
   }

   Alternativ, wenn Sie uv oder einen anderen Paketmanager verwenden:

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "uv",
    "args": [
    "--directory",
    "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
    "run",
    "-m",
    "mcp_server_tree_sitter.server"
    ]
    }
    }
   }

   Hinweis: Stellen Sie sicher, dass Sie /ABSOLUTE/PATH/TO/YOUR/PROJECT durch den tatsächlichen absoluten Pfad zu Ihrem Projektverzeichnis ersetzen.

3. Speichern Sie die Datei und starten Sie Claude Desktop neu.

Das MCP-Tool-Symbol (Hammer) erscheint in der Benutzeroberfläche von Claude Desktop, sobald Sie mindestens einen MCP-Server ordnungsgemäß konfiguriert haben. Sie können dann auf die Funktionalität des tree_sitter-Servers zugreifen, indem Sie auf dieses Symbol klicken.

Konfiguration mit der veröffentlichten Version

Wenn Sie das Paket nicht manuell von PyPI installieren (veröffentlichte Version) oder das Repository klonen möchten, verwenden Sie einfach die folgende Konfiguration für Claude Desktop:

1. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei (gleicher Speicherort wie oben).

2. Fügen Sie den tree-sitter-Server zum Abschnitt mcpServers hinzu:

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "uvx",
    "args": [
    "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
    "mcp-server-tree-sitter"
    ]
    }
    }
   }

3. Speichern Sie die Datei und starten Sie Claude Desktop neu.

Diese Methode verwendet uvx, um das installierte PyPI-Paket direkt auszuführen, was der empfohlene Ansatz für die veröffentlichte Version ist. Der Server benötigt keine zusätzlichen Parameter, um in seiner grundlegenden Konfiguration zu laufen.

Zustandspersistenz

Der MCP Tree-sitter Server behält den Zustand zwischen Aufrufen bei. Das bedeutet:

• Projekte bleiben registriert, bis sie explizit entfernt oder der Server neu gestartet wird

• Syntaxbäume werden gemäß den Konfigurationseinstellungen zwischengespeichert

• Sprachinformationen bleiben während der gesamten Lebensdauer des Servers erhalten

Diese Persistenz wird während der Lebensdauer des Servers mithilfe von Singleton-Mustern für Schlüsselkomponenten im Arbeitsspeicher aufrechterhalten.

Ausführung als eigenständiger Server

Es gibt verschiedene Möglichkeiten, den Server auszuführen:

Verwendung des MCP CLI direkt:

python -m mcp run mcp_server_tree_sitter.server

Verwendung von Makefile-Zielen:

# Show available targets
make

# Run the server with default settings
make mcp-run

# Show help information
make mcp-run ARGS="--help"

# Show version information
make mcp-run ARGS="--version"

# Run with custom configuration file
make mcp-run ARGS="--config /path/to/config.yaml"

# Enable debug logging
make mcp-run ARGS="--debug"

# Disable parse tree caching
make mcp-run ARGS="--disable-cache"

Verwendung des installierten Skripts:

# Run the server with default settings
mcp-server-tree-sitter

# Show help information
mcp-server-tree-sitter --help

# Show version information
mcp-server-tree-sitter --version

# Run with custom configuration file
mcp-server-tree-sitter --config /path/to/config.yaml

# Enable debug logging
mcp-server-tree-sitter --debug

# Disable parse tree caching
mcp-server-tree-sitter --disable-cache

Verwendung mit dem MCP Inspector

Verwendung des MCP CLI direkt:

python -m mcp dev mcp_server_tree_sitter.server

Oder Verwendung des Makefile-Ziels:

make mcp-dev

Sie können auch Argumente übergeben:

make mcp-dev ARGS="--debug"

Verwendung

Ein Projekt registrieren

Registrieren Sie zuerst ein Projekt zur Analyse:

register_project_tool(path="/path/to/your/project", name="my-project")

Dateien erkunden

Listen Sie Dateien im Projekt auf:

list_files(project="my-project", pattern="**/*.py")

Dateiinhalte anzeigen:

get_file(project="my-project", path="src/main.py")

Codestruktur analysieren

Syntaxbaum abrufen:

get_ast(project="my-project", path="src/main.py", max_depth=3)

Symbole extrahieren:

get_symbols(project="my-project", path="src/main.py")

Code durchsuchen

Nach Text suchen:

find_text(project="my-project", pattern="function", file_pattern="**/*.py")

Tree-sitter-Abfragen ausführen:

run_query(
 project="my-project",
 query='(function_definition name: (identifier) @function.name)',
 language="python"
)

Komplexität analysieren

analyze_complexity(project="my-project", path="src/main.py")

Direkte Python-Verwendung

Obwohl die primäre beabsichtigte Verwendung über den MCP-Server erfolgt, können Sie die Bibliothek auch direkt im Python-Code verwenden:

# Import from the API module
from mcp_server_tree_sitter.api import (
 register_project, list_projects, get_config, get_language_registry
)

# Register a project
project_info = register_project(
 path="/path/to/project", 
 name="my-project", 
 description="Description"
)

# List projects
projects = list_projects()

# Get configuration
config = get_config()

# Access components through dependency injection
from mcp_server_tree_sitter.di import get_container
container = get_container()
project_registry = container.project_registry
language_registry = container.language_registry

Konfiguration

Erstellen Sie eine YAML-Konfigurationsdatei:

cache:
 enabled: true # Enable/disable caching (default: true)
 max_size_mb: 100 # Maximum cache size in MB (default: 100)
 ttl_seconds: 300 # Cache entry time-to-live in seconds (default: 300)

security:
 max_file_size_mb: 5 # Maximum file size to process in MB (default: 5)
 excluded_dirs: # Directories to exclude from processing
 - .git
 - node_modules
 - __pycache__
 allowed_extensions: # Optional list of allowed file extensions
 # - py
 # - js
 # Leave empty or omit for all extensions

language:
 default_max_depth: 5 # Default max depth for AST traversal (default: 5)
 preferred_languages: # List of languages to pre-load at startup for faster performance
 - python # Pre-loading reduces latency for first operations
 - javascript

log_level: INFO # Logging level (DEBUG, INFO, WARNING, ERROR)
max_results_default: 100 # Default maximum results for search operations

Laden Sie sie mit:

configure(config_path="/path/to/config.yaml")

Protokollierungskonfiguration

Die Ausführlichkeit der Protokollierung des Servers kann über Umgebungsvariablen gesteuert werden:

# Enable detailed debug logging
export MCP_TS_LOG_LEVEL=DEBUG

# Use normal informational logging (default)
export MCP_TS_LOG_LEVEL=INFO

# Only show warning and error messages
export MCP_TS_LOG_LEVEL=WARNING

Umfassende Informationen zur Protokollierungskonfiguration finden Sie in der Protokollierungsdokumentation. Details zur Befehlszeilenschnittstelle finden Sie in der CLI-Dokumentation.

Über preferred_languages

Die Einstellung preferred_languages steuert, welche Sprach-Parser beim Serverstart vorab geladen werden, anstatt bei Bedarf. Dies bietet mehrere Vorteile:

• Schnellere Erst-Analyse: Keine Verzögerung bei der ersten Analyse einer Datei einer vorab geladenen Sprache

• Frühe Fehlererkennung: Probleme mit Parsern werden beim Start entdeckt, nicht während der Verwendung

• Vorhersehbare Speicherzuweisung: Speicher für häufig verwendete Parser wird im Voraus zugewiesen

Standardmäßig werden alle Parser bei Bedarf geladen, wenn sie zum ersten Mal benötigt werden. Für eine optimale Leistung geben Sie die Sprachen an, die Sie in Ihren Projekten am häufigsten verwenden.

Sie können auch spezifische Einstellungen konfigurieren:

configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")

Oder verwenden Sie Umgebungsvariablen:

export MCP_TS_CACHE_MAX_SIZE_MB=256
export MCP_TS_LOG_LEVEL=DEBUG
export MCP_TS_CONFIG_PATH=/path/to/config.yaml

Umgebungsvariablen verwenden das Format MCP_TS_SECTION_SETTING (z. B. MCP_TS_CACHE_MAX_SIZE_MB) für Abschnittseinstellungen oder MCP_TS_SETTING (z. B. MCP_TS_LOG_LEVEL) für Einstellungen auf oberster Ebene.

Konfigurationswerte werden in dieser Rangfolge angewendet:

1. Umgebungsvariablen (höchste)

2. Werte, die über configure()-Aufrufe gesetzt wurden

3. YAML-Konfigurationsdatei

4. Standardwerte (niedrigste)

Der Server sucht nach der Konfiguration in:

1. Pfad, der im configure()-Aufruf angegeben ist

2. Pfad, der durch die Umgebungsvariable MCP_TS_CONFIG_PATH angegeben ist

3. Standardspeicherort: ~/.config/tree-sitter/config.yaml

Für Entwickler

Diagnosefunktionen

Der MCP Tree-sitter Server enthält ein Diagnose-Framework, das bei der Identifizierung und Behebung von Problemen hilft:

# Run diagnostic tests
make test-diagnostics

# CI-friendly version (won't fail the build on diagnostic issues)
make test-diagnostics-ci

Diagnosetests liefern detaillierte Informationen über das Verhalten des Servers und können helfen, spezifische Probleme zu isolieren. Weitere Informationen zum Diagnose-Framework finden Sie in der Diagnosedokumentation.

Überlegungen zur Typsicherheit

Der MCP Tree-sitter Server wahrt die Typsicherheit bei der Schnittstelle zu tree-sitter-Bibliotheken durch sorgfältige Designmuster und Protokolle. Wenn Sie die Codebasis erweitern, lesen Sie bitte den Leitfaden zur Typsicherheit für wichtige Informationen zum Umgang mit Variationen der tree-sitter-API.

Verfügbare Ressourcen

Der Server stellt die folgenden MCP-Ressourcen bereit:

• project://{project}/files - Alle Dateien in einem Projekt auflisten

• project://{project}/files/{pattern} - Dateien auflisten, die einem Muster entsprechen

• project://{project}/file/{path} - Dateiinhalte abrufen

• project://{project}/file/{path}/lines/{start}-{end} - Bestimmte Zeilen aus einer Datei abrufen

• project://{project}/ast/{path} - Den AST für eine Datei abrufen

• project://{project}/ast/{path}/depth/{depth} - Den AST mit benutzerdefinierter Tiefe abrufen

Verfügbare Tools

Der Server stellt Tools bereit für:

• Projektmanagement: register_project_tool, list_projects_tool, remove_project_tool

• Sprachmanagement: list_languages, check_language_available

• Dateivorgänge: list_files, get_file, get_file_metadata

• AST-Analyse: get_ast, get_node_at_position

• Codesuche: find_text, run_query

• Symbol-Extraktion: get_symbols, find_usage

• Projektanalyse: analyze_project, get_dependencies, analyze_complexity

• Abfrageerstellung: get_query_template_tool, list_query_templates_tool, build_query, adapt_query, get_node_types

• Erkennung ähnlichen Codes: find_similar_code

• Cache-Management: clear_cache

• Konfigurationsdiagnose: diagnose_config

Siehe FEATURES.md für detaillierte Informationen zum Implementierungsstatus, zu Abhängigkeiten und Anwendungsbeispielen jedes Tools.

Verfügbare Prompts

Der Server stellt die folgenden MCP-Prompts bereit:

• code_review - Einen Prompt für die Code-Überprüfung erstellen

• explain_code - Einen Prompt für die Code-Erklärung erstellen

• explain_tree_sitter_query - Die Syntax von tree-sitter-Abfragen erklären

• suggest_improvements - Einen Prompt für Verbesserungsvorschläge für Code erstellen

• project_overview - Einen Prompt für eine Projektübersichtsanalyse erstellen

Feedback & Community

Wir würden gerne erfahren, wie Sie mcp-server-tree-sitter verwenden und was es für Ihren Arbeitsablauf nützlicher machen würde.

• Fragen & Funktionsanfragen: GitHub Discussions

• Fehlerberichte: GitHub Issues

Lizenz

MIT

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• adapt_queryC
• analyze_complexityC
• analyze_projectC
• build_queryC
• check_language_availableC
• clear_cacheC
• configureC
• diagnose_configC