ContextTree MCP 🌳

Глубокий семантический поиск по коду для ИИ-ассистентов — на основе AST-парсинга и локальных эмбеддингов. Полностью офлайн.

ContextTree MCP — это локальный сервер Model Context Protocol, который даёт вашему ИИ-ассистенту для написания кода структурное понимание кодовой базы. Он объединяет два мира:

• tree-sitter разбирает исходные файлы в AST и извлекает логические блоки — функции, методы, сигнатуры классов с docstring.

• sentence-transformers (all-MiniLM-L6-v2) превращает каждый блок — дополненный путём к файлу, именем класса, именем метода и docstring — в вектор внутри локального векторного хранилища ChromaDB.

В итоге ваш ассистент находит код по смыслу, а не по ключевым словам, и каждый результат поиска содержит точный путь к файлу и номера строк.

🔒 Приватность прежде всего. Всё выполняется на вашей машине: разбор, модель эмбедов, векторный индекс. Никаких облачных вызовов, никакой телеметрии, код никогда не покидает диск, на котором лежит.

Почему не простой текстовый поиск?

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

Related MCP server: CodeGrok MCP

Возможности

• 🌲 AST-сегментация — индексирует функции, методы и сигнатуры классов через tree-sitter, а не произвольные текстовые окна.

• 🧩 Контекстно-обогащённые логические блоки — каждый индексируемый документ включает свой путь к файлу, владельца-класс, имя метода, docstring и тело, так что запросы вроде «логика повтора платежей» попадают точно в нужный метод.

• ⚡ Инкрементальная индексация — SHA-256-хэши содержимого на файл; повторно обрабатываются только изменённые/новые/удалённые файлы.

• 🔍 Семантический поиск — запрос на естественном языке → ранжированные фрагменты кода с точными диапазонами строк.

• 📞 Поиск использований на основе AST — находит реальные места вызовов любого символа (функции или класса), отсеивая ложные срабатывания вроде строковых литералов или комментариев.

• 🗄️ Постоянный локальный индекс — ChromaDB хранится в .chroma/, переживает перезапуски и никогда не попадает в Git.

• 🔌 Транспорт MCP stdio — подключается к Claude Desktop, OpenCode, Cursor, Cline или любому MCP-совместимому клиенту.

Технологический стек

Установка

Требуется Python 3.12+. Рекомендуется uv как быстрыйкий современный пакетный менеджер:

git clone https://github.com/<your-org>/mcp-context-tree.git
cd mcp-context-tree

# Option A — uv (recommended): resolves dependencies from pyproject.toml, locks uv.lock
uv sync

# Option B — classic pip + venv
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

💡 При первом запуске модель эмбеддингов (~90 МБ). PyTorch устанавливается как зависимость sentence-transformers; достаточно CPU-сборки — GPU не требуется.

Регистрация в MCP-клиенте

Примерконфигурации (Claude Desktop / любой клиент с поддержкой stdio-серверов):

{
  "mcpServers": {
    "context-tree": {
      "command": "<path-to-venv>/bin/python",
      "args": ["-m", "context_tree"],
      "env": {}
    }
  }
}

(В Windows используйте <path-to-venv>\Scripts\python.exe.)

Инструменты, доступные ассистенту

Типичный рабочий процесс:

1. index_workspace("D:/projects/my-app")
2. semantic_search("where do we handle payment retries", limit=8)
3. find_ast_usages("PaymentGateway.retry")

Поддерживаемые языки

Документация

• 🏛️ ARCHITECTURE.md — структура проекта, схема данных ChromaDB, логика AST-извлечения, дизайн инкрементальной индексации.

• 🇷🇺 README.ru.md — документация на русском языке.

Дорожная карта

• Режим наблюдения — автоматическая переиндексация при изменении файлов (fs-watcher)

• Больше языков через tree-sitter-биндинги

• Гибридный поиск (BM25 + переранжирование по векторам)

• Ранжирование с учётом графа вызово » («кто это вызывает?»)

• Релиз на PyPI (context-tree-mcp)

Участие в разработке

Приветствуются issue и пулл-реквесты. Пожалуйста, поддерживайте согласованность с ARCHITECTURE.md.

Лицензия

MIT — см. LICENSE.