Mason — построитель контекста для LLM 👷

npm version npm downloads license issues

Mason предоставляет LLM постоянную карту вашей кодовой базы, чтобы они перестали исследовать её с нуля в каждой сессии.

Проблема: Каждый раз, когда LLM начинает новый разговор о вашем коде, она использует grep, читает файлы и собирает архитектуру по частям — тратя токены на контекст, который она уже поняла вчера. В проекте из 164 файлов ответ на вопрос «какие функции есть в этом приложении?» требует чтения 8+ файлов с помощью нескольких вызовов инструментов.

Решение Mason: Концептуальная карта, которая сохраняется между сессиями. Один вызов инструмента возвращает таблицу поиска «функция-файл» — LLM точно знает, где искать, без необходимости исследования.

Измеренный результат (deepeval, Claude Sonnet, проект KMP из 164 файлов):

Вопрос	С Mason	Без Mason	Экономия токенов
Перечислить все функции	10 258 ток.	31 346 ток.	67%
Отследить поток данных	12 010 ток.	15 258 ток.	21%
Сравнить платформы	10 897 ток.	19 353 ток.	44%
Поток онбординга	10 271 ток.	11 432 ток.	10%
Среднее			36%

Качество ответов одинаковое (0.9/1.0 во всех тестах для обоих путей). Воспроизведение: bench/.

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

claude mcp add mason --scope user -- npx -p mason-context mason-mcp

Перезапустите Claude Code, затем спросите: "use mason to analyze this project and create a snapshot."

Это всё — Mason проанализирует вашу кодовую базу и создаст концептуальную карту. В следующей сессии он загрузит карту вместо того, чтобы переисследовать всё заново.

Related MCP server: ontomics

Как это работает

Концептуальная карта

Основная функция Mason. Она сохраняет карту «функция-файл» в .mason/snapshot.json, которая сохраняется между разговорами. Когда LLM нужно понять ваш проект, она читает эту карту вместо того, чтобы использовать grep по всей кодовой базе:

{
  "features": {
    "home screen": {
      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
    }
  },
  "flows": {
    "weather fetch": {
      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
    }
  }
}

Карта генерируется самой LLM — Mason предоставляет инструменты анализа, а LLM интерпретирует ваш код, чтобы определить, что представляют собой функции и потоки. Это означает, что карта отражает архитектурное понимание, а не просто список файлов.

Создайте её, попросив своего ИИ-ассистента "create a mason snapshot", или через CLI:

mason set-llm gemini          # configure a provider (no API key needed)
mason snapshot ~/my-project   # generate concept map
mason snapshot --install-hook # auto-update on every commit

Анализ влияния изменений

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

История совместных изменений — файлы, которые исторически меняются вместе в коммитах git
Ссылки — файлы, которые импортируют или упоминают цель по имени
Связанные тесты — тестовые файлы, сопоставленные с целью по соглашению об именовании

mason impact WeatherRepository.kt -d ~/my-project

Также доступно как инструмент MCP get_impact — спросите своего ассистента "what would be affected if I changed WeatherRepository?"

Анализ истории Git

Mason агрегирует сотни коммитов в полезную статистику: какие файлы меняются чаще всего (горячие файлы, с которыми нужно быть осторожными), какие директории не трогали месяцами (потенциально устаревший код) и какие соглашения о коммитах приняты в команде. Это тот тип анализа, для вычисления которого вручную потребовались бы десятки вызовов git log.

mason analyze ~/my-project

Инструменты MCP

Mason предоставляет 6 инструментов через протокол Model Context Protocol. Любой MCP-совместимый клиент (Claude Code, Cursor и т.д.) может их использовать:

Инструмент	Что он делает
`get_snapshot`	Загрузить концептуальную карту — сопоставляет функции/потоки с файлами
`save_snapshot`	Сохранить концептуальную карту для будущих сессий
`get_impact`	Влияние изменений: история совместных изменений, ссылки, связанные тесты
`analyze_project`	История Git: паттерны коммитов, горячие файлы, устаревшие директории
`full_analysis`	Комплексный первый визит: статистика git + структура + примеры кода + карта тестов
`get_code_samples`	Умные превью файлов, выбранные по архитектурной роли

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

Mason также работает как автономный CLI для генерации файлов CLAUDE.md и запуска анализа без MCP-клиента. Настройте провайдера LLM один раз, затем используйте любую команду:

mason set-llm claude|gemini|ollama|openai  # configure provider
mason generate                # analyze codebase + LLM -> CLAUDE.md
mason analyze                 # git stats only (no LLM needed)
mason impact File.kt          # change impact analysis
mason snapshot                # create/update concept map

Большинство провайдеров работают без API-ключа — claude, gemini и ollama используют свои соответствующие CLI напрямую.

Безопасность

Что содержит снимок: Имена функций, относительные пути к файлам и описания потоков. Никакого исходного кода, секретов или бизнес-логики.

Чего он не касается: Mason соблюдает .gitignore (через git ls-files) и имеет список запрещенных файлов (deny-list), который блокирует .env, .pem, .key, учетные данные и другие конфиденциальные файлы от выборки. Защита от обхода путей (path traversal) гарантирует, что весь доступ к файлам остается внутри корня проекта.

Поток данных LLM: Генерация снимка через CLI отправляет содержимое выбранных файлов вашему настроенному провайдеру LLM — так же, как любой ИИ-ассистент читает ваш код. Используйте ollama для полностью локальной генерации. Инструменты сервера MCP (get_snapshot, get_impact и т.д.) читают только локальные файлы.

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

Mason полностью не зависит от языка программирования. Он использует паттерны именования файлов и историю git, а не парсинг конкретного языка, поэтому он работает с любым проектом, у которого есть исходные файлы и репозиторий git — TypeScript, Kotlin, Python, Go, Rust, Swift, Java, C#, Dart и другие.

Лицензия

MIT

mason