MCP Tree-sitter Server

Un servidor para análisis de código usando Tree-sitter, con capacidades de gestión de contexto.

GitHub
310
Prueba este MCPPatrocinado

Documentación

Servidor MCP Tree-sitter

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de análisis de código utilizando tree-sitter, diseñado para dar a los asistentes de IA acceso inteligente a 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: Examina código en múltiples niveles de granularidad
  • 🧠 Gestión de Contexto: Proporciona información suficiente sin abrumar la ventana de contexto
  • 🌐 Independiente del Lenguaje: Soporta muchos lenguajes de programación incluyendo Python, JavaScript, TypeScript, Go, Rust, C, C++, C#, Swift, Java, Kotlin, Dart, Julia y APL mediante tree-sitter-language-pack
  • 🌳 Consciente de la Estructura: Utiliza comprensión basada en AST con recorrido eficiente basado en cursores
  • 🔎 Búsqueda: Encuentra patrones específicos usando búsqueda de texto y consultas tree-sitter
  • 🔄 Caché: Rendimiento optimizado mediante caché de árboles de análisis
  • 🔑 Extracción de Símbolos: Extrae y analiza funciones, clases y otros símbolos de código
  • 📊 Análisis de Dependencias: Identifica y analiza dependencias y relaciones de código
  • 🧩 Persistencia de Estado: Mantiene registros de proyectos y datos en caché entre invocaciones
  • 🔒 Seguro: Límites de seguridad integrados y validación de entrada

Para una lista completa de todos los comandos disponibles, su estado de implementación actual y la matriz de características detallada, consulta el documento FEATURES.md.

Instalación

Requisitos previos

  • Python 3.10+
  • Analizadores de lenguaje Tree-sitter para tus lenguajes preferidos

Instalación básica

pip install mcp-server-tree-sitter

Instalación para desarrollo

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

Inicio rápido

Ejecutar con Claude Desktop

Puedes hacer que el servidor esté disponible en Claude Desktop mediante el CLI de MCP o configurando Claude Desktop manualmente.

Usando el CLI de MCP

Registra el servidor con Claude Desktop:

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

Configuración manual

Alternativamente, puedes configurar Claude Desktop manualmente:

  1. Abre tu 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.

  2. Añade el servidor a la sección mcpServers:

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

    Alternativamente, si usas uv u otro gestor de paquetes:

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

    Nota: Asegúrate de reemplazar /ABSOLUTE/PATH/TO/YOUR/PROJECT con la ruta absoluta real a tu directorio de proyecto.

  3. Guarda el archivo y reinicia Claude Desktop.

El icono de herramientas MCP (martillo) aparecerá en la interfaz de Claude Desktop una vez que hayas configurado correctamente al menos un servidor MCP. Puedes acceder a la funcionalidad del servidor tree_sitter haciendo clic en este icono.

Configuración con la versión publicada

Si prefieres no instalar manualmente el paquete desde PyPI (versión publicada) ni clonar el repositorio, simplemente usa la siguiente configuración para Claude Desktop:

  1. Abre tu archivo de configuración de Claude Desktop (misma ubicación que arriba).

  2. Añade 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"
            ]
        }
    }
}

  3. Guarda el archivo y reinicia Claude Desktop.

Este método usa uvx para ejecutar directamente el paquete PyPI instalado, que es el enfoque recomendado para la versión publicada. El servidor no requiere parámetros adicionales para ejecutarse en su configuración básica.

Persistencia de Estado

El Servidor MCP Tree-sitter mantiene el estado entre invocaciones. Esto significa:

  • Los proyectos permanecen registrados hasta que se eliminan explícitamente o se reinicia el servidor
  • Los árboles de análisis se almacenan en caché según la configuración
  • La información del lenguaje se conserva durante toda la vida del servidor

Esta persistencia se mantiene en memoria durante la vida del servidor utilizando patrones singleton para componentes clave.

Ejecutar como servidor independiente

Hay varias formas de ejecutar el servidor:

Usando el CLI de MCP directamente:

python -m mcp run mcp_server_tree_sitter.server

Usando objetivos de 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 el CLI de MCP directamente:

python -m mcp dev mcp_server_tree_sitter.server

O usando el objetivo de Makefile:

make mcp-dev

También puedes pasar argumentos:

make mcp-dev ARGS="--debug"

Uso

Registrar un Proyecto

Primero, registra un proyecto para analizar:

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

Explorar Archivos

Lista archivos en el proyecto:

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

Ver contenido del archivo:

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

Analizar Estructura de Código

Obtén el árbol de sintaxis:

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

Extrae símbolos:

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

Buscar Código

Busca texto:

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

Ejecuta consultas tree-sitter:

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

Analizar Complejidad

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

Uso Directo en Python

Aunque el uso principal previsto es a través del servidor MCP, también puedes usar la biblioteca directamente en 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

Crea 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

Cárgalo con:

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

Configuración de Registro

La verbosidad del registro del servidor se puede controlar usando 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 información completa sobre la configuración de registro, consulta la documentación de registro. Para detalles sobre la interfaz de línea de comandos, consulta la documentación del CLI.

Acerca de preferred_languages

La configuración preferred_languages controla qué analizadores de lenguaje se precargan al inicio del servidor en lugar de bajo demanda. Esto proporciona varios beneficios:

  • Análisis inicial más rápido: Sin demora al analizar por primera vez un archivo de un lenguaje 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 analizadores de uso frecuente se asigna por adelantado

Por defecto, todos los analizadores se cargan bajo demanda cuando se necesitan por primera vez. Para un rendimiento óptimo, especifica los lenguajes que usas con más frecuencia en tus proyectos.

También puedes configurar ajustes específicos:

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

O usar 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 usan 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:

  1. Variables de entorno (más alta)
  2. Valores establecidos mediante llamadas configure()
  3. Archivo de configuración YAML
  4. Valores predeterminados (más baja)

El servidor buscará configuración en:

  1. Ruta especificada en la llamada configure()
  2. Ruta especificada por la variable de entorno MCP_TS_CONFIG_PATH
  3. 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 corregir 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 aislar problemas específicos. Para más información sobre el marco de diagnóstico, consulta 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 tree-sitter mediante patrones de diseño y protocolos cuidadosos. Si estás extendiendo la base de código, revisa la guía de seguridad de tipos para información importante sobre el manejo de variaciones de la API tree-sitter.

Recursos Disponibles

El servidor proporciona los siguientes recursos MCP:

  • project://{project}/files - Lista todos los archivos en un proyecto
  • project://{project}/files/{pattern} - Lista archivos que coinciden con un patrón
  • project://{project}/file/{path} - Obtiene el contenido de un archivo
  • project://{project}/file/{path}/lines/{start}-{end} - Obtiene líneas específicas de un archivo
  • project://{project}/ast/{path} - Obtiene el AST de un archivo
  • project://{project}/ast/{path}/depth/{depth} - Obtiene 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 lenguajes: list_languages, check_language_available
  • Operaciones de archivos: 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 de proyectos: analyze_project, get_dependencies, analyze_complexity
  • Construcció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

Consulta FEATURES.md para información detallada sobre el estado de implementación de cada herramienta, dependencias y ejemplos de uso.

Prompts Disponibles

El servidor proporciona los siguientes prompts MCP:

  • code_review - Crea un prompt para revisar código
  • explain_code - Crea un prompt para explicar código
  • explain_tree_sitter_query - Explica la sintaxis de consultas tree-sitter
  • suggest_improvements - Crea un prompt para sugerir mejoras de código
  • project_overview - Crea un prompt para un análisis general del proyecto

Comentarios y Comunidad

Nos encantaría saber cómo estás usando mcp-server-tree-sitter y qué lo haría más útil para tu flujo de trabajo.

Licencia

MIT