MCP Tree-sitter Server

Um servidor para análise de código usando Tree-sitter, com capacidades de gerenciamento de contexto.

GitHub
310
Experimente este MCPPatrocinado

Documentação

Servidor MCP Tree-sitter

Um servidor Model Context Protocol (MCP) que fornece capacidades de análise de código usando tree-sitter, projetado para dar a assistentes de IA acesso inteligente a bases de código com gerenciamento adequado de contexto. O Claude Desktop é o alvo de implementação de referência.

Recursos

  • 🔍 Exploração Flexível: Examine código em múltiplos níveis de granularidade
  • 🧠 Gerenciamento de Contexto: Fornece informação suficiente sem sobrecarregar a janela de contexto
  • 🌐 Agnóstico de Linguagem: Suporta muitas linguagens de programação incluindo Python, JavaScript, TypeScript, Go, Rust, C, C++, C#, Swift, Java, Kotlin, Dart, Julia e APL via tree-sitter-language-pack
  • 🌳 Ciente da Estrutura: Usa compreensão baseada em AST com travessia eficiente baseada em cursor
  • 🔎 Pesquisável: Encontre padrões específicos usando busca de texto e consultas tree-sitter
  • 🔄 Cache: Desempenho otimizado através de cache de árvores de análise
  • 🔑 Extração de Símbolos: Extraia e analise funções, classes e outros símbolos de código
  • 📊 Análise de Dependências: Identifique e analise dependências e relacionamentos de código
  • 🧩 Persistência de Estado: Mantém registros de projetos e dados em cache entre invocações
  • 🔒 Seguro: Limites de segurança integrados e validação de entrada

Para uma lista abrangente de todos os comandos disponíveis, seu status atual de implementação e matriz detalhada de recursos, consulte o documento FEATURES.md.

Instalação

Pré-requisitos

  • Python 3.10+
  • Parsers de linguagem Tree-sitter para suas linguagens preferidas

Instalação Básica

pip install mcp-server-tree-sitter

Instalação para Desenvolvimento

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

Início Rápido

Executando com Claude Desktop

Você pode disponibilizar o servidor no Claude Desktop através do MCP CLI ou configurando manualmente o Claude Desktop.

Usando MCP CLI

Registre o servidor com o Claude Desktop:

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

Configuração Manual

Alternativamente, você pode configurar manualmente o Claude Desktop:

  1. Abra seu arquivo de configuração do Claude Desktop:

    • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    Crie o arquivo se ele não existir.

  2. Adicione o servidor à seção mcpServers:

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

    Alternativamente, se estiver usando uv ou outro gerenciador de pacotes:

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

    Nota: Certifique-se de substituir /ABSOLUTE/PATH/TO/YOUR/PROJECT pelo caminho absoluto real para o diretório do seu projeto.

  3. Salve o arquivo e reinicie o Claude Desktop.

O ícone de ferramentas MCP (martelo) aparecerá na interface do Claude Desktop assim que você configurar corretamente pelo menos um servidor MCP. Você pode então acessar a funcionalidade do servidor tree_sitter clicando neste ícone.

Configurando com Versão Publicada

Se você preferir não instalar manualmente o pacote do PyPI (versão publicada) ou clonar o repositório, simplesmente use a seguinte configuração para o Claude Desktop:

  1. Abra seu arquivo de configuração do Claude Desktop (mesmo local acima).

  2. Adicione o servidor tree-sitter à seção mcpServers:

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

  3. Salve o arquivo e reinicie o Claude Desktop.

Este método usa uvx para executar o pacote PyPI instalado diretamente, que é a abordagem recomendada para a versão publicada. O servidor não requer parâmetros adicionais para executar em sua configuração básica.

Persistência de Estado

O Servidor MCP Tree-sitter mantém estado entre invocações. Isso significa:

  • Projetos permanecem registrados até serem explicitamente removidos ou o servidor ser reiniciado
  • Árvores de análise são armazenadas em cache de acordo com as configurações
  • Informações de linguagem são retidas durante toda a vida útil do servidor

Esta persistência é mantida em memória durante a vida útil do servidor usando padrões singleton para componentes-chave.

Executando como servidor autônomo

Existem várias maneiras de executar o servidor:

Usando o MCP CLI diretamente:

python -m mcp run mcp_server_tree_sitter.server

Usando alvos do 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 o 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

Usando com o MCP Inspector

Usando o MCP CLI diretamente:

python -m mcp dev mcp_server_tree_sitter.server

Ou usando o alvo do Makefile:

make mcp-dev

Você também pode passar argumentos:

make mcp-dev ARGS="--debug"

Uso

Registrar um Projeto

Primeiro, registre um projeto para analisar:

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

Explorar Arquivos

Liste arquivos no projeto:

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

Veja o conteúdo do arquivo:

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

Analisar Estrutura de Código

Obtenha a árvore sintática:

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

Extraia símbolos:

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

Buscar Código

Busque por texto:

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

Execute consultas tree-sitter:

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

Analisar Complexidade

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

Uso Direto em Python

Embora o uso principal pretendido seja através do servidor MCP, você também pode usar a biblioteca diretamente em 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

Configuração

Crie um arquivo de configuração 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

Carregue-o com:

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

Configuração de Logging

A verbosidade de logging do servidor pode ser controlada usando variáveis de ambiente:

# 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 informações abrangentes sobre configuração de logging, consulte a documentação de logging. Para detalhes sobre a interface de linha de comando, veja a documentação do CLI.

Sobre preferred_languages

A configuração preferred_languages controla quais parsers de linguagem são pré-carregados na inicialização do servidor em vez de sob demanda. Isso fornece vários benefícios:

  • Análise inicial mais rápida: Sem atraso ao analisar pela primeira vez um arquivo de uma linguagem pré-carregada
  • Detecção precoce de erros: Problemas com parsers são descobertos na inicialização, não durante o uso
  • Alocação de memória previsível: Memória para parsers usados com frequência é alocada antecipadamente

Por padrão, todos os parsers são carregados sob demanda quando necessário pela primeira vez. Para desempenho ideal, especifique as linguagens que você usa com mais frequência em seus projetos.

Você também pode configurar configurações específicas:

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

Ou usar variáveis de ambiente:

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

Variáveis de ambiente usam o formato MCP_TS_SECTION_SETTING (ex.: MCP_TS_CACHE_MAX_SIZE_MB) para configurações de seção, ou MCP_TS_SETTING (ex.: MCP_TS_LOG_LEVEL) para configurações de nível superior.

Os valores de configuração são aplicados nesta ordem de precedência:

  1. Variáveis de ambiente (maior)
  2. Valores definidos via chamadas configure()
  3. Arquivo de configuração YAML
  4. Valores padrão (menor)

O servidor procurará configuração em:

  1. Caminho especificado na chamada configure()
  2. Caminho especificado pela variável de ambiente MCP_TS_CONFIG_PATH
  3. Localização padrão: ~/.config/tree-sitter/config.yaml

Para Desenvolvedores

Capacidades de Diagnóstico

O Servidor MCP Tree-sitter inclui uma estrutura de diagnóstico para ajudar a identificar e corrigir problemas:

# Run diagnostic tests
make test-diagnostics

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

Testes de diagnóstico fornecem informações detalhadas sobre o comportamento do servidor e podem ajudar a isolar problemas específicos. Para mais informações sobre a estrutura de diagnóstico, consulte a documentação de diagnósticos.

Considerações de Segurança de Tipos

O Servidor MCP Tree-sitter mantém segurança de tipos ao interagir com bibliotecas tree-sitter através de padrões de design e protocolos cuidadosos. Se você está estendendo a base de código, revise o guia de segurança de tipos para informações importantes sobre como lidar com variações da API tree-sitter.

Recursos Disponíveis

O servidor fornece os seguintes recursos MCP:

  • project://{project}/files - Listar todos os arquivos em um projeto
  • project://{project}/files/{pattern} - Listar arquivos que correspondem a um padrão
  • project://{project}/file/{path} - Obter conteúdo do arquivo
  • project://{project}/file/{path}/lines/{start}-{end} - Obter linhas específicas de um arquivo
  • project://{project}/ast/{path} - Obter o AST para um arquivo
  • project://{project}/ast/{path}/depth/{depth} - Obter o AST com profundidade personalizada

Ferramentas Disponíveis

O servidor fornece ferramentas para:

  • Gerenciamento de projetos: register_project_tool, list_projects_tool, remove_project_tool
  • Gerenciamento de linguagens: list_languages, check_language_available
  • Operações de arquivo: list_files, get_file, get_file_metadata
  • Análise AST: get_ast, get_node_at_position
  • Busca de código: find_text, run_query
  • Extração de símbolos: get_symbols, find_usage
  • Análise de projetos: analyze_project, get_dependencies, analyze_complexity
  • Construção de consultas: get_query_template_tool, list_query_templates_tool, build_query, adapt_query, get_node_types
  • Detecção de código similar: find_similar_code
  • Gerenciamento de cache: clear_cache
  • Diagnósticos de configuração: diagnose_config

Veja FEATURES.md para informações detalhadas sobre o status de implementação de cada ferramenta, dependências e exemplos de uso.

Prompts Disponíveis

O servidor fornece os seguintes prompts MCP:

  • code_review - Criar um prompt para revisar código
  • explain_code - Criar um prompt para explicar código
  • explain_tree_sitter_query - Explicar sintaxe de consulta tree-sitter
  • suggest_improvements - Criar um prompt para sugerir melhorias de código
  • project_overview - Criar um prompt para análise de visão geral do projeto

Feedback e Comunidade

Adoraríamos saber como você está usando mcp-server-tree-sitter e o que o tornaria mais útil para seu fluxo de trabalho.

Licença

MIT