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 brindarle a Claude acceso inteligente a las bases de código con administración de contexto adecuada.

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
- Windows: %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" ] } } }
Alternativamente, si usa uv u otro administrador de paquetes:
{ "mcpServers": { "tree_sitter": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT", "run", "-m", "mcp_server_tree_sitter.server" ] } } }
Nota: asegúrese de reemplazar /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

mcp run mcp_server_tree_sitter.server

Uso con el Inspector MCP

mcp dev mcp_server_tree_sitter.server

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")

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

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

Recursos disponibles

El servidor proporciona los siguientes recursos MCP:

project://{project}/files - Lista todos los archivos de un proyecto
project://{project}/files/{pattern} - Lista de archivos que coinciden con un patrón
project://{project}/file/{path} - Obtener el contenido del archivo
project://{project}/file/{path}/lines/{start}-{end} - Obtener líneas específicas de un archivo
project://{project}/ast/{path} - Obtener el AST de un archivo
project://{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ódigo
explain_code - Crea un mensaje para explicar el código
explain_tree_sitter_query - Explica la sintaxis de la consulta del cuidador de árboles
suggest_improvements - Crea un mensaje para sugerir mejoras en el código
project_overview - Crea una solicitud para un análisis general del proyecto

Licencia

Instituto Tecnológico de Massachusetts (MIT)

mcp-server-tree-sitter

Integrations