Servidor Tree-sitter de MCP
Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de análisis de código mediante tree-sitter, diseñado para brindar a los asistentes de IA acceso inteligente a las bases de código con una gestión de contexto adecuada. Claude Desktop es el objetivo de implementación de referencia.
Características
- 🔍 Exploración flexible : Examine el código en múltiples niveles de granularidad
- 🧠 Gestión de contexto : proporciona la información justa sin saturar la ventana de contexto
- 🌐 Agnóstico del lenguaje : admite muchos lenguajes de programación, incluidos Python, JavaScript, TypeScript, Go, Rust, C, C++, Swift, Java, Kotlin, Julia y APL a través de tree-sitter-language-pack
- 🌳 Consciente de la estructura : utiliza comprensión basada en AST con un recorrido eficiente basado en cursor
- 🔎 Buscable : encuentre patrones específicos usando la búsqueda de texto y consultas de treesitter
- 🔄 Almacenamiento en caché : rendimiento optimizado mediante el almacenamiento en caché del árbol de análisis
- 🔑 Extracción de símbolos : extrae y analiza funciones, clases y otros símbolos de código
- 📊 Análisis de dependencias : identificar y analizar las dependencias y relaciones del código
- 🧩 Persistencia del estado : mantiene los registros del proyecto y los datos almacenados en caché entre invocaciones
- 🔒 Seguro : límites de seguridad integrados y validación de entrada
Para obtener una lista completa de todos los comandos disponibles, su estado de implementación actual y una matriz de características detallada, consulte el documento FEATURES.md .
Instalación
Prerrequisitos
- Python 3.10+
- Analizadores de idiomas Tree-sitter para tus idiomas preferidos
Instalación básica
pip install mcp-server-tree-sitter
Instalación de desarrollo
git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev,languages]"
Inicio rápido
Ejecutando con Claude Desktop
Puede hacer que el servidor esté disponible en Claude Desktop a través de la CLI de MCP o configurando manualmente Claude Desktop.
Uso de la CLI de MCP
Registrar el servidor con Claude Desktop:
mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"
Configuración manual
Alternativamente, puede configurar manualmente Claude Desktop:
- Abra el archivo de configuración de Claude Desktop:
- macOS/Linux:
~/Library/Application Support/Claude/claude_desktop_config.json - Ventanas:
%APPDATA%\Claude\claude_desktop_config.json
Crea el archivo si no existe.
- Agregue el servidor a la sección
mcpServers :{
"mcpServers": {
"tree_sitter": {
"command": "python",
"args": [
"-m",
"mcp_server_tree_sitter.server"
]
}
}
}
{
"mcpServers": {
"tree_sitter": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/YOUR/PROJECT",
"run",
"-m",
"mcp_server_tree_sitter.server"
]
}
}
}
/ABSOLUTE/PATH/TO/YOUR/PROJECT con la ruta absoluta real al directorio de su proyecto. - Guarde el archivo y reinicie Claude Desktop.
El icono de herramientas MCP (martillo) aparecerá en la interfaz de Claude Desktop una vez que haya configurado correctamente al menos un servidor MCP. A continuación, podrá acceder a las funciones del servidor tree_sitter haciendo clic en este icono.
Configuración con la versión lanzada
Si prefiere no instalar manualmente el paquete desde PyPI (versión lanzada) o clonar el repositorio, simplemente use la siguiente configuración para Claude Desktop:
- Abra el archivo de configuración de Claude Desktop (la misma ubicación que arriba).
- Agregue el servidor tree-sitter a la sección
mcpServers :{
"mcpServers": {
"tree_sitter": {
"command": "uvx",
"args": [
"--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
"mcp-server-tree-sitter"
]
}
}
}
- Guarde el archivo y reinicie Claude Desktop.
Este método utiliza uvx para ejecutar directamente el paquete PyPI instalado, lo cual es el enfoque recomendado para la versión publicada. El servidor no requiere parámetros adicionales para funcionar con su configuración básica.
Persistencia del Estado
El servidor Tree-sitter de MCP mantiene el estado entre invocaciones. Esto significa:
- Los proyectos permanecen registrados hasta que se eliminen explícitamente o se reinicie el servidor
- Los árboles de análisis se almacenan en caché según la configuración
- La información del idioma se conserva durante toda la vida útil del servidor.
Esta persistencia se mantiene en la memoria durante la vida útil del servidor utilizando patrones singleton para componentes clave.
Ejecutándose como un servidor independiente
Hay varias formas de ejecutar el servidor:
Usando la CLI de MCP directamente:
python -m mcp run mcp_server_tree_sitter.server
Usando objetivos Makefile:
# 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"
Usando el script instalado:
# 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
Uso con el Inspector MCP
Usando la CLI de MCP directamente:
python -m mcp dev mcp_server_tree_sitter.server
O usando el objetivo Makefile:
También puedes pasar argumentos:
make mcp-dev ARGS="--debug"
Uso
Registrar un proyecto
Primero, registre un proyecto para analizar:
register_project_tool(path="/path/to/your/project", name="my-project")
Explorar archivos
Lista de archivos en el proyecto:
list_files(project="my-project", pattern="**/*.py")
Ver el contenido del archivo:
get_file(project="my-project", path="src/main.py")
Analizar la estructura del código
Obtener el árbol de sintaxis:
get_ast(project="my-project", path="src/main.py", max_depth=3)
Extraer símbolos:
get_symbols(project="my-project", path="src/main.py")
Código de búsqueda
Buscar texto:
find_text(project="my-project", pattern="function", file_pattern="**/*.py")
Ejecutar consultas de tree-sitter:
run_query(
project="my-project",
query='(function_definition name: (identifier) @function.name)',
language="python"
)
Analizar la complejidad
analyze_complexity(project="my-project", path="src/main.py")
Uso directo de Python
Si bien el uso principal previsto es a través del servidor MCP, también puedes usar la biblioteca directamente en el código Python:
# 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
Configuración
Crear un archivo de configuración YAML:
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
Cargarlo con:
configure(config_path="/path/to/config.yaml")
Configuración de registro
El nivel de detalle del registro del servidor se puede controlar mediante variables de entorno:
# 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
Para obtener información completa sobre la configuración del registro, consulte la documentación de registro . Para obtener más información sobre la interfaz de línea de comandos, consulte la documentación de la CLI .
Acerca de preferred_languages
La configuración preferred_languages controla qué analizadores de idiomas se precargan al iniciar el servidor en lugar de cuando se solicitan. Esto ofrece varias ventajas:
- Análisis inicial más rápido : no hay demora al analizar por primera vez un archivo de un idioma precargado
- Detección temprana de errores : los problemas con los analizadores se descubren al inicio, no durante el uso
- Asignación de memoria predecible : la memoria para los analizadores utilizados con frecuencia se asigna por adelantado
De forma predeterminada, todos los analizadores se cargan bajo demanda cuando se necesitan. Para un rendimiento óptimo, especifique los idiomas que usa con más frecuencia en sus proyectos.
También puedes configurar ajustes específicos:
configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")
O utilice variables de entorno:
export MCP_TS_CACHE_MAX_SIZE_MB=256
export MCP_TS_LOG_LEVEL=DEBUG
export MCP_TS_CONFIG_PATH=/path/to/config.yaml
Las variables de entorno utilizan el formato MCP_TS_SECTION_SETTING (por ejemplo, MCP_TS_CACHE_MAX_SIZE_MB ) para configuraciones de sección, o MCP_TS_SETTING (por ejemplo, MCP_TS_LOG_LEVEL ) para configuraciones de nivel superior.
Los valores de configuración se aplican en este orden de precedencia:
- Variables de entorno (más altas)
- Valores establecidos mediante llamadas
configure() - Archivo de configuración YAML
- Valores predeterminados (más bajos)
El servidor buscará la configuración en:
- Ruta especificada en la llamada
configure() - Ruta especificada por la variable de entorno
MCP_TS_CONFIG_PATH - Ubicación predeterminada:
~/.config/tree-sitter/config.yaml
Para desarrolladores
Capacidades de diagnóstico
El servidor MCP Tree-sitter incluye un marco de diagnóstico para ayudar a identificar y solucionar problemas:
# Run diagnostic tests
make test-diagnostics
# CI-friendly version (won't fail the build on diagnostic issues)
make test-diagnostics-ci
Las pruebas de diagnóstico proporcionan información detallada sobre el comportamiento del servidor y pueden ayudar a identificar problemas específicos. Para obtener más información sobre el marco de diagnóstico, consulte la documentación de diagnóstico .
Consideraciones de seguridad de tipos
El servidor MCP Tree-sitter mantiene la seguridad de tipos al interactuar con bibliotecas de Tree-sitter mediante patrones y protocolos de diseño rigurosos. Si amplía el código base, consulte la guía de seguridad de tipos para obtener información importante sobre el manejo de las variaciones de la API de Tree-sitter.
Recursos disponibles
El servidor proporciona los siguientes recursos MCP:
project://{project}/files - Lista todos los archivos de un proyectoproject://{project}/files/{pattern} - Lista de archivos que coinciden con un patrónproject://{project}/file/{path} - Obtener el contenido del archivoproject://{project}/file/{path}/lines/{start}-{end} - Obtener líneas específicas de un archivoproject://{project}/ast/{path} - Obtener el AST de un archivoproject://{project}/ast/{path}/depth/{depth} - Obtener el AST con profundidad personalizada
Herramientas disponibles
El servidor proporciona herramientas para:
- Gestión de proyectos:
register_project_tool , list_projects_tool , remove_project_tool - Gestión de idiomas:
list_languages , check_language_available - Operaciones de archivo:
list_files , get_file , get_file_metadata - Análisis AST:
get_ast , get_node_at_position - Búsqueda de código:
find_text , run_query - Extracción de símbolos:
get_symbols , find_usage - Análisis del proyecto:
analyze_project , get_dependencies , analyze_complexity - Creación de consultas:
get_query_template_tool , list_query_templates_tool , build_query , adapt_query , get_node_types - Detección de código similar:
find_similar_code - Gestión de caché:
clear_cache - Diagnóstico de configuración:
diagnose_config
Consulte FEATURES.md para obtener información detallada sobre el estado de implementación, las dependencias y los ejemplos de uso de cada herramienta.
Indicaciones disponibles
El servidor proporciona las siguientes indicaciones MCP:
code_review - Crea un mensaje para revisar el códigoexplain_code - Crea un mensaje para explicar el códigoexplain_tree_sitter_query - Explica la sintaxis de la consulta del cuidador de árbolessuggest_improvements - Crea un mensaje para sugerir mejoras en el códigoproject_overview - Crea una solicitud para un análisis general del proyecto
Licencia
Instituto Tecnológico de Massachusetts (MIT)