MCP Tree-sitter Server

Сервер протокола контекста модели (MCP), предоставляющий возможности анализа кода с использованием tree-sitter, разработанный для предоставления ИИ-ассистентам интеллектуального доступа к кодовым базам с соответствующим управлением контекстом. Claude Desktop является эталонной реализацией.

Возможности

• 🔍 Гибкое исследование: Изучайте код на разных уровнях детализации

• 🧠 Управление контекстом: Предоставляет ровно столько информации, сколько нужно, не перегружая контекстное окно

• 🌐 Языковая независимость: Поддерживает множество языков программирования, включая Python, JavaScript, TypeScript, Go, Rust, C, C++, C#, Swift, Java, Kotlin, Dart, Julia и APL через tree-sitter-language-pack

• 🌳 Понимание структуры: Использует анализ на основе AST с эффективным обходом с помощью курсора

• 🔎 Поиск: Находите конкретные шаблоны с помощью текстового поиска и запросов tree-sitter

• 🔄 Кэширование: Оптимизированная производительность за счет кэширования деревьев разбора

• 🔑 Извлечение символов: Извлекайте и анализируйте функции, классы и другие символы кода

• 📊 Анализ зависимостей: Идентифицируйте и анализируйте зависимости и связи в коде

• 🧩 Сохранение состояния: Поддерживает регистрацию проектов и кэшированные данные между вызовами

• 🔒 Безопасность: Встроенные границы безопасности и проверка входных данных

Полный список всех доступных команд, их текущий статус реализации и подробную матрицу функций см. в документе FEATURES.md.

Related MCP server: code-index-mcp

Установка

Предварительные требования

• Python 3.10+

• Парсеры языков Tree-sitter для предпочитаемых вами языков

Базовая установка

pip install mcp-server-tree-sitter

Установка для разработки

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

Быстрый старт

Запуск с Claude Desktop

Вы можете сделать сервер доступным в Claude Desktop либо через MCP CLI, либо путем ручной настройки Claude Desktop.

Использование MCP CLI

Зарегистрируйте сервер в Claude Desktop:

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

Ручная настройка

Альтернативно, вы можете настроить Claude Desktop вручную:

1. Откройте файл конфигурации Claude Desktop:

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

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

   Создайте файл, если он не существует.

2. Добавьте сервер в раздел mcpServers:

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

   Альтернативно, если вы используете uv или другой менеджер пакетов:

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

   Примечание: Обязательно замените /ABSOLUTE/PATH/TO/YOUR/PROJECT на фактический абсолютный путь к директории вашего проекта.

3. Сохраните файл и перезапустите Claude Desktop.

Значок инструментов MCP (молоток) появится в интерфейсе Claude Desktop, как только вы правильно настроите хотя бы один сервер MCP. После этого вы сможете получить доступ к функциональности сервера tree_sitter, нажав на этот значок.

Настройка с выпущенной версией

Если вы предпочитаете не устанавливать пакет вручную из PyPI (выпущенная версия) или клонировать репозиторий, просто используйте следующую конфигурацию для Claude Desktop:

1. Откройте файл конфигурации Claude Desktop (тот же путь, что и выше).

2. Добавьте сервер tree-sitter в раздел mcpServers:

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

3. Сохраните файл и перезапустите Claude Desktop.

Этот метод использует uvx для прямого запуска установленного пакета PyPI, что является рекомендуемым подходом для выпущенной версии. Сервер не требует дополнительных параметров для запуска в базовой конфигурации.

Сохранение состояния

MCP Tree-sitter Server сохраняет состояние между вызовами. Это означает:

• Проекты остаются зарегистрированными до тех пор, пока они не будут явно удалены или сервер не будет перезапущен

• Деревья разбора кэшируются в соответствии с настройками конфигурации

• Информация о языке сохраняется в течение всего времени работы сервера

Это состояние поддерживается в оперативной памяти во время работы сервера с использованием паттерна «одиночка» (singleton) для ключевых компонентов.

Запуск в качестве автономного сервера

Существует несколько способов запуска сервера:

Использование MCP CLI напрямую:

python -m mcp run mcp_server_tree_sitter.server

Использование целей 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"

Использование установленного скрипта:

# 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

Использование с MCP Inspector

Использование MCP CLI напрямую:

python -m mcp dev mcp_server_tree_sitter.server

Или использование цели Makefile:

make mcp-dev

Вы также можете передавать аргументы:

make mcp-dev ARGS="--debug"

Использование

Регистрация проекта

Сначала зарегистрируйте проект для анализа:

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

Исследование файлов

Список файлов в проекте:

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

Просмотр содержимого файла:

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

Анализ структуры кода

Получение дерева синтаксиса:

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

Извлечение символов:

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

Поиск кода

Поиск текста:

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

Выполнение запросов tree-sitter:

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

Анализ сложности

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

Прямое использование в Python

Хотя основное использование предполагается через сервер MCP, вы также можете использовать библиотеку напрямую в коде 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

Конфигурация

Создайте файл конфигурации 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

Загрузите его с помощью:

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

Настройка логирования

Уровень детализации логирования сервера можно контролировать с помощью переменных окружения:

# 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

Для получения полной информации о настройке логирования, пожалуйста, обратитесь к документации по логированию. Подробности о интерфейсе командной строки см. в документации CLI.

О параметре preferred_languages

Настройка preferred_languages определяет, какие парсеры языков будут предварительно загружены при запуске сервера, а не по требованию. Это дает несколько преимуществ:

• Более быстрый начальный анализ: Отсутствие задержки при первом анализе файла на предварительно загруженном языке

• Раннее обнаружение ошибок: Проблемы с парсерами обнаруживаются при запуске, а не во время использования

• Предсказуемое выделение памяти: Память для часто используемых парсеров выделяется заранее

По умолчанию все парсеры загружаются по требованию при первом обращении. Для оптимальной производительности укажите языки, которые вы используете в своих проектах чаще всего.

Вы также можете настроить специфические параметры:

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

Или использовать переменные окружения:

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

Переменные окружения используют формат MCP_TS_SECTION_SETTING (например, MCP_TS_CACHE_MAX_SIZE_MB) для настроек секций или MCP_TS_SETTING (например, MCP_TS_LOG_LEVEL) для настроек верхнего уровня.

Значения конфигурации применяются в следующем порядке приоритета:

1. Переменные окружения (наивысший)

2. Значения, установленные через вызовы configure()

3. Файл конфигурации YAML

4. Значения по умолчанию (наинизший)

Сервер будет искать конфигурацию в:

1. Пути, указанном в вызове configure()

2. Пути, указанном переменной окружения MCP_TS_CONFIG_PATH

3. Расположении по умолчанию: ~/.config/tree-sitter/config.yaml

Для разработчиков

Диагностические возможности

MCP Tree-sitter Server включает диагностическую структуру, помогающую выявлять и исправлять проблемы:

# Run diagnostic tests
make test-diagnostics

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

Диагностические тесты предоставляют подробную информацию о поведении сервера и могут помочь изолировать конкретные проблемы. Для получения дополнительной информации о диагностической структуре, пожалуйста, ознакомьтесь с документацией по диагностике.

Вопросы безопасности типов

MCP Tree-sitter Server поддерживает безопасность типов при взаимодействии с библиотеками tree-sitter благодаря тщательно продуманным паттернам проектирования и протоколам. Если вы расширяете кодовую базу, пожалуйста, ознакомьтесь с руководством по безопасности типов для получения важной информации об обработке вариаций API tree-sitter.

Доступные ресурсы

Сервер предоставляет следующие ресурсы MCP:

• project://{project}/files - Список всех файлов в проекте

• project://{project}/files/{pattern} - Список файлов, соответствующих шаблону

• project://{project}/file/{path} - Получить содержимое файла

• project://{project}/file/{path}/lines/{start}-{end} - Получить определенные строки из файла

• project://{project}/ast/{path} - Получить AST для файла

• project://{project}/ast/{path}/depth/{depth} - Получить AST с пользовательской глубиной

Доступные инструменты

Сервер предоставляет инструменты для:

• Управления проектами: register_project_tool, list_projects_tool, remove_project_tool

• Управления языками: list_languages, check_language_available

• Операций с файлами: list_files, get_file, get_file_metadata

• Анализа AST: get_ast, get_node_at_position

• Поиска кода: find_text, run_query

• Извлечения символов: get_symbols, find_usage

• Анализа проекта: analyze_project, get_dependencies, analyze_complexity

• Создания запросов: get_query_template_tool, list_query_templates_tool, build_query, adapt_query, get_node_types

• Обнаружения похожего кода: find_similar_code

• Управления кэшем: clear_cache

• Диагностики конфигурации: diagnose_config

См. FEATURES.md для получения подробной информации о статусе реализации каждого инструмента, зависимостях и примерах использования.

Доступные промпты

Сервер предоставляет следующие промпты MCP:

• code_review - Создать промпт для проверки кода

• explain_code - Создать промпт для объяснения кода

• explain_tree_sitter_query - Объяснить синтаксис запросов tree-sitter

• suggest_improvements - Создать промпт для предложения улучшений кода

• project_overview - Создать промпт для анализа обзора проекта

Обратная связь и сообщество

Мы будем рады узнать, как вы используете mcp-server-tree-sitter и что сделало бы его более полезным для вашего рабочего процесса.

• Вопросы и запросы функций: GitHub Discussions

• Отчеты об ошибках: GitHub Issues

Лицензия

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