Booster MCP

Документация: English | Русский | 简体中文

Booster — это локальный сервер Model Context Protocol (MCP) и когнитивная среда выполнения для ИИ-агентов кодирования. Он строит ограниченную, запрашиваемую модель мира репозитория, чтобы агент мог изучить архитектуру, историю, диагностику, правила проекта и требования валидации перед изменением кода.

Большинство агентов уже имеют руки: они быстро пишут патчи. Booster даёт им уровень восприятия, которого обычно не хватает.

Почему существует Booster

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

Без Booster агент часто следует этому циклу:

request -> grep/search -> read a few files -> write a patch -> stop

Такой цикл может упускать:

• вызывающих и вызываемых целевого символа;

• файлы и тесты, затронутые изменением интерфейса;

• историческую причину удивительного кода;

• специфичные для проекта правила и сохранённые архитектурные решения;

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

• команду валидации, которую следует запустить после патча.

Booster добавляет эти сигналы в цикл:

request
  -> project memory
  -> repository map and hybrid search
  -> AST impact graph
  -> git history and blame
  -> diagnostics and security checks
  -> validation plan
  -> focused patch
  -> validation and repair

Related MCP server: SRC (Structured Repo Context)

Возможности

Архитектура

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

• Плоскость управления MCP: индексация репозитория, семантический поиск, графы, память, диагностика, навыки и инструменты валидации.

• Плоскость данных Booster Home: необязательный локальный шлюз, совместимый с OpenAI, который компилирует контекст, хранит восстанавливаемые артефакты и пересылает запросы локальному или удалённому бэкенду моделей.

Существующий индекс репозитория и когнитивная среда выполнения переиспользуются. Home не создаёт второй индекс репозитория, шлюз или векторную базу данных.

Плоскость управления MCP

Основной сервер предоставляет:

• нормализованный косинусный поиск FAISS, лексический поиск BM25 и слияние взаимных рангов через hybrid_search;

• ограниченное сканирование репозитория с воспроизводимыми профилями сканирования;

• создаваемые артефакты .agents/booster/, такие как repo_map_architecture.md, repo_map_symbols.md, index_health.json, repo_map.md, code_city.html, scan_config.json и scan_report.json;

• ресурсы контекста по адресам repo://map, repo://stack, repo://conventions и repo://artifacts;

• символы, графы импортов и вызовов, флипчарты, Code City и диагностику репозитория;

• анализ влияния, git-интеллект, структурированную память проекта, проверки безопасности и циклы валидации;

• двенадцать встроенных навыков рабочих процессов, синхронизированных с ~/.agents/skills;

• booster control — межплатформенную панель управления для MCP-клиентов, настроек сканирования, диагностики и управления лаунчером.

Среда выполнения Booster Home

Home — это необязательная локальная плоскость данных. Она сохраняет плоскость управления MCP нетронутой и добавляет шлюз, совместимый с OpenAI, с детерминированной компиляцией контекста, ограниченными локальными воркерами, необработанными артефактами в рамках сессии и целевой интеграцией с существующим индексом Booster и когнитивной средой выполнения.

Запустите его на loopback:

booster home \
  --base-url http://127.0.0.1:1234/v1 \
  --model nvidia/nemotron-3-nano-4b \
  --api-key lm-studio \
  --project .

Home предоставляет:

• /v1/models;

• /v1/chat/completions;

• /v1/responses;

• /health;

• /booster/status.

Идентификатор вышестоящей модели обнаруживается из /v1/models; замените его идентификатором, сообщённым локальным сервером, совместимым с OpenAI. Развёртывания Nemotron могут возвращать специфичный для провайдера reasoning_content вместо message.content, когда бюджет вывода потребляется рассуждениями. Home сохраняет это поле и не преобразовывает молча неполный ответ с рассуждениями в успешный ответ.

Потоковые ответы пересылаются чанками. Перед вытеснением блока его необработанное содержимое сохраняется как неизменяемый артефакт и проверяется по хэшу содержимого. Если сохранение не удаётся, запрос завершается ошибкой, а не молча теряет контекст.

Индексация репозитория основана на заданиях. add_repo(wait=true) по-прежнему принимается для совместимости, но больше не блокирует запрос MCP. Используйте index_status, cancel_index и ограниченный wait_until_ready для наблюдения за заданием. Каждый статус содержит job_id, фазу, обработано/всего, затраченное время, ETA, последний прогресс, идентификатор поколения, состояние устаревания и последний готовый снимок. Методы-только-для-чтения репозитория продолжают возвращать этот готовый снимок, пока строится новое поколение.

Создаваемые артефакты разделены по назначению:

• repo_map_architecture.md — ограниченная макро-карта с разнообразием модулей верхнего уровня, покрытием точек входа/конфигурации/контрактов и сводкой покрытия;

• repo_map_symbols.md — подробная карта символов с лимитом на файл;

• index_health.json — записывает поколение, устаревшие пути, выбранные/пропущенные файлы и полноту карты;

• repo_map.md — остаётся совместимой копией карты архитектуры.

Приоритет конфигурации:

defaults
  -> ~/.booster/home.toml
  -> <project>/.agents/booster/home.toml
  -> explicit --config
  -> CLI flags

Ключи API используются только в заголовках вышестоящих запросов и редактируются в статусе, телеметрии, временных линиях, журналах и тексте исключений. Эти команды проверяют Home без запуска второго сервера или индекса репозитория:

booster home status
booster home doctor --json
booster home inspect-context --input request.json --json
booster home sessions delete <session-id>

Loopback — значение по умолчанию и не требует токена шлюза. Привязка не к loopback отклоняется, если не настроен home.auth_token — в TOML, через BOOSTER_HOME_AUTH_TOKEN или с помощью --auth-token. Удалённые запросы должны отправлять Authorization: Bearer <token>; токен никогда не возвращается в статусе или журналах.

Доказательство: Booster + Nemotron 4B

Самый сильный способ понять Booster — увидеть цикл на сложной задаче. В ручном запуске LM Studio с той же моделью Nemotron класса 4B правдоподобное первое решение провалило скрытые тесты. После контекста Booster, явных ограничений и цикла исправления и повторной отправки тот же рабочий процесс дал принятые решения:

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

• 689. Maximum Sum of 3 Non-Overlapping Subarrays: сбой при разрешении tie-breaking -> 43/43 принято;

• 123. Best Time to Buy and Sell Stock III: 214/214 принято;

• записанные принятые запуски показывают локальное время выполнения 36 мс и 170 мс.

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

См. полное исследование LeetCode для исходного решения, шагов исправления, скриншотов и чек-листа воспроизведения.

Сжатие контекста

Home рассматривает сжатие как компиляцию контекста, а не необратимое забывание:

1. Классифицирует сообщения по роли и типу содержимого.

2. Нормализует детерминированный шум, такой как дублирующиеся строки, вывод прогресса и ANSI-последовательности.

3. Сохраняет исходный блок до того, как он может быть вытеснен.

4. Оценивает релевантность и распределяет доступный входной бюджет по приоритету.

5. Опционально запускает ограниченные семантические воркеры и целевое извлечение из модели мира.

6. Упаковывает выбранные сообщения, сохраняя защищённый контекст и целостность вызовов инструментов.

Компилятор сообщает original_tokens, compiled_tokens, removed_tokens, compression_ratio, операции, предупреждения и ссылки на артефакты. Основные инварианты:

• системный и активный пользовательский контекст защищены;

• известные жёсткие лимиты завершаются ошибкой, если защищённый контекст не помещается;

• необработанные данные сохраняются перед вытеснением;

• содержимое артефактов проверяется по хэшу после записи и чтения;

• сжатие можно отключить, но policy=off по-прежнему отклоняет запрос выше известного жёсткого входного бюджета;

• специфичные для провайдера поля, включая reasoning_content, сохраняются.

Запустите включённый стресс-бенчмарк:

uv run python benchmarks/home_context_benchmark.py

Бенчмарк выводит количество исходных, детерминированных, извлечённых и финальных токенов, коэффициент сжатия, задержку компилятора, точное восстановление артефактов и результаты целевого обогащения. Успешный запуск должен включать:

exact_artifact_recovery=True

Исследовательский копроцессор

Home также включает ограниченный исследовательский копроцессор для локальных экспериментов. Он читает данные из research_state.json, memory_bank.md или memory-bank/*.md, метрики и файлы отчётов. Он возвращает структурированный JSON, а не представляет непрозрачную сгенерированную моделью сводку как истину.

Тела бинарных контрольных точек никогда не читаются, не индексируются и не передаются модели. Доступны только метаданные, такие как имя файла, размер, шаг, родитель, метрики, эксперимент, статус, флаг keep и ветка. Метаданные бокового файла ищутся рядом с контрольной точкой с использованием соглашений .pt.json, .json, _metadata.json и .metadata.json.

Пакет контекста организован следующим образом:

L0  current task
L1  current experiment and active hypotheses
L2  recent evidence and relevant code
L3  project invariants and runtime contract
L4  archive

Обычный вывод использует L0, L1 и соответствующие части L2 и L3. Дублирующиеся журналы, старые неудачные версии, бинарные артефакты и нерелевантная история исключаются политикой. Содержимое репозитория, метрики, отчёты и память являются ненадёжными данными и не выполняются как конфигурация.

Допустимые роли работников:

log_analyst
code_search
benchmark_reader
artifact_indexer
summarizer

Состояние исследования и реестр атомарно записываются в <project>/research_state.json. Артефакты домашней сессии остаются отдельными в .agents/booster/runtime/sessions/; состояние исследования не смешивается с таймлайнами чата или устаревшим .agents/booster/memory.json.

Структура репозитория

.
├── booster_home/              # Optional OpenAI-compatible data plane
├── assets/                    # README and Code City visual assets
├── algocheck/                 # Customer-facing LeetCode validation evidence
├── benchmarks/                # Reproducible context and runtime benchmarks
├── docs/                      # Architecture and maintainer documentation
├── skills/                    # Bundled agent workflow skills
├── tests/                     # Pytest suite, including Home regressions
├── server.py                 # MCP server entrypoint
├── cli.py                    # `booster` CLI entrypoint
├── cognitive_runtime.py      # Impact, memory, diagnostics, and validation tools
├── indexer.py                # Repository indexing and graph construction
├── visualizer.py             # Code City generation
├── AGENTS.md                 # Agent-first bootstrap and project instructions
├── RECOMENDET_PROMPT.md      # Repository-wide engineering prompt for agents
├── CONTRIBUTING.md           # Development and contribution workflow
├── CHANGELOG.md              # Release history
├── pyproject.toml            # Package metadata and tool configuration
├── MANIFEST.in               # Source distribution contents
└── uv.lock                   # Reproducible dependency lockfile

Устаревшие модули плоскости управления MCP намеренно остаются в корне репозитория. Точки входа пакета (server:main и cli:main) и существующие интеграции полагаются на эти стабильные имена модулей. Перемещение их в src/ следует рассматривать как отдельную миграцию совместимости, а не смешивать с рутинной работой над функциями.

Рекомендуемый системный промпт агента

Этот репозиторий включает выделенный инженерный системный промпт: RECOMENDET_PROMPT.md.

Загрузите его в начале нетривиальной сессии кодирования, когда агенту нужно работать как инженеру, а не как генератору патчей. Промпт определяет правила маршрутизации контекста проекта, рабочий процесс PERCEIVE -> MODEL -> PLAN -> ACT -> VERIFY -> LEARN, извлечение контекста в первую очередь через Booster, анализ первопричин, проверки безопасности, требования к валидации и дисциплину памяти.

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

Установка

Требования

• Python 3.11, 3.12 или 3.13. Рекомендуется Python 3.12.

• Git.

• Доступ в интернет при первом запуске для загрузки модели эмбеддингов.

Windows

Invoke-WebRequest https://raw.githubusercontent.com/NeuroGhostDev/Booster-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

macOS и Linux

curl -fsSL https://raw.githubusercontent.com/NeuroGhostDev/Booster-mcp/main/install.sh | bash

Каждый установщик создаёт лаунчер booster в пользовательском локальном каталоге bin:

• Windows: %USERPROFILE%\.local\bin\booster.cmd;

• macOS и Linux: ~/.local/bin/booster.

Установщик добавляет этот каталог в PATH. Откройте новый терминал, если текущая оболочка ещё не видит лаунчер.

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

git clone https://github.com/NeuroGhostDev/Booster-mcp.git
cd Booster-mcp
uv sync --locked --extra dev

Без uv используйте виртуальное окружение Python 3.12:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

В Windows активируйте с помощью \.venv\Scripts\Activate.ps1 и используйте \.venv\Scripts\booster.exe, пока лаунчер не установлен.

Загрузка агента: вставьте ссылку GitHub, получите рабочий процесс

Когда этот репозиторий открывается из URL GitHub в ИИ-агенте кодирования, агент должен рассматривать AGENTS.md как контракт начальной загрузки проекта. Он должен установить локальные зависимости, синхронизировать навыки Booster, загрузить инженерные рекомендации, создать ограниченные артефакты репозитория и подключить MCP-сервер перед редактированием кода.

Выполните это один раз из корня репозитория:

# 1. Install the project and its development dependencies.
uv sync --locked --extra dev

# 2. Install or update the bundled Booster skills for the current agent.
uv run python -c "from skill_installer import install_bundled_skills; print(install_bundled_skills())"

# 3. Load the repository into the bounded Booster world model.
uv run booster expand --profile balanced .

# 4. Connect the current repository to VS Code MCP.
uv run booster control connect \
  --client vscode \
  --scope workspace \
  --project . \
  --with-repository \
  --force

# 5. Verify the environment and generated artifacts.
uv run booster control doctor --project .
uv run booster control status --client vscode --scope workspace --project .

Для Claude Desktop используйте вместо этого подключение на уровне пользователя:

uv run booster control connect \
  --client claude \
  --scope user \
  --project . \
  --with-repository \
  --force

Если uv недоступен, используйте python -m pip install -e ".[dev]" и замените uv run booster на python -m cli или установленный лаунчер booster.

Затем агент должен начинать каждую нетривиальную задачу с:

Read AGENTS.md and RECOMENDET_PROMPT.md.
Call inject_context(include_map=true, include_stack=true, include_conventions=true).
Use preflight_analysis and impact_analysis before editing code.
Use run_validation_checks after the patch.
Call booster.task_complete(task_id="<task-id>") before the final response.

Это намеренно проектно-уровневое и переносимое. Репозиторий не должен молча перезаписывать скрытый системный промпт хост-приложения или несвязанную глобальную конфигурацию клиента. AGENTS.md — это файл инструкций, который могут обнаружить хосты агентов; booster control connect изменяет только выбранную запись MCP-клиента и сохраняет другие серверы.

Подключение к VS Code

Запустите меню управления из репозитория, которым хотите управлять:

booster control

Используйте подключение рабочей области для одного репозитория:

cd path/to/project
booster control connect --client vscode --scope workspace --project .
booster expand --profile balanced

Используйте подключение пользователя, когда Booster должен появляться в каждой рабочей области VS Code:

booster control connect --client vscode --scope user --project .

После запуска сервера на уровне пользователя попросите агента вызвать add_repo для репозитория, который в данный момент редактируется. Индексация по умолчанию выполняется в фоне; index_status сообщает фазу и прогресс. add_repo(wait=true) по-прежнему принимается для совместимости, но также не блокирует. При необходимости используйте cancel_index или ограниченный wait_until_ready. Используйте --with-repository, чтобы привязать сервер уровня пользователя к одному репозиторию.

VS Code хранит конфигурацию MCP рабочей области и пользователя отдельно. После изменения сервера выполните MCP: List Servers, выберите Booster, запустите или перезапустите его и примите запрос доверия. Если он всё ещё отсутствует, выполните Developer: Reload Window и проверьте MCP: List Servers -> Booster -> Show Output.

Управление Booster

booster control предоставляет интерактивное управление подключениями, профили сканирования, обновление артефактов, диагностику, удаление серверов и обновление лаунчера. Те же операции доступны в неинтерактивном режиме:

# Show the active runtime, client entry, scan policy, and artifacts.
booster control status --client vscode --scope workspace --project .

# Add or remove a client entry.
booster control connect --client vscode --scope workspace --project .
booster control disconnect --client vscode --scope workspace --project .

# Connect another desktop client in the user profile.
booster control connect --client claude --scope user --project .

# Inspect and persist the bounded scan policy.
booster control scan --project .
booster control scan --project . --profile deep --max-files 2000

# Verify Python, FastMCP, FAISS, BM25, and embedding dependencies.
booster control doctor --project .

Ограниченное сканирование репозитория

Запустите booster expand перед подключением большого репозитория. Он сохраняет политику сканирования и генерирует начальную карту без необходимости живого MCP-подключения.

booster expand --profile balanced

Сканер отдаёт приоритет обычным корням исходников, по умолчанию игнорирует сгенерированные каталоги и каталоги зависимостей и записывает каждое решение о лимите в .agents/booster/scan_report.json. Добавляйте локальные исключения в .boosterignore, когда каталог нерелевантен текущей задаче.

Когнитивный рабочий процесс выполнения

Используйте этот процесс, когда агент собирается изменить код:

1. Вспомните правила проекта с помощью project_memory_recall.

2. Найдите цель с помощью hybrid_search, semantic_search или find_symbol.

3. Оцените радиус поражения с помощью impact_analysis.

4. Проверьте историю с помощью git_intelligence, когда код выглядит неожиданно.

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

6. Вносите узкие исправления, используя существующие паттерны проекта.

7. Проверьте с помощью run_validation_checks и исправляйте тот же срез, пока он не пройдёт или гипотеза не будет отклонена.

Типичная предварительная проверка:

project_memory_recall(query="refactor billing invoice flow", repo="<repo>")
impact_analysis(target="InvoiceService", repo="<repo>", max_depth=3)
git_intelligence(symbol="InvoiceService", repo="<repo>", limit=8)
collect_diagnostics(paths=["src/billing/invoice.py"], repo="<repo>")

Типичная проверка после патча:

run_validation_checks(
  paths=["src/billing/invoice.py"],
  commands=["pytest tests/billing -q"],
  repo="<repo>"
)

Диагностика закрывается при сбое

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

Примеры

Перед рефакторингом

impact_analysis(target="AuthService", repo="<repo>", max_depth=4)
git_intelligence(symbol="AuthService", repo="<repo>")
collect_diagnostics(paths=["src/auth/service.py"], repo="<repo>")

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

Во время поиска ошибки

analyze_error("<stacktrace>")
git_intelligence(path="src/payments/locks.py", symbol="payment_lock")
flipchart_call_graph(symbol="payment_lock", max_depth=4)

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

Для долгосрочных знаний о проекте

remember_project_fact(
  category="architecture",
  fact="Frontend talks to backend only through the BFF layer",
  confidence=0.95,
  source="repo_map+impact_analysis"
)

Будущие сессии могут вспомнить этот факт перед редактированием API или фронтенда.

Встроенные навыки рабочего процесса

• booster-architecture-map

• booster-bug-hunt

• booster-context-inject

• booster-cognitive-runtime

• booster-deep-dive

• booster-feature-add

• booster-flipchart

• booster-mcp-workflow

• booster-onboard

• booster-project-memory

• booster-refactor

• booster-review

Ключевые инструменты MCP

Привязки репозиториев сохраняются в общем пользовательском реестре по адресу ~/.booster/repositories/, поэтому независимо запущенные процессы MCP видят одни и те же активные проекты. booster.task_complete ставит в очередь финальную ограниченную переиндексацию для репозиториев задачи. Каждая завершённая индексация сохраняет .agents/booster/repo_map.md, code_city.html, scan_config.json и scan_report.json в неизменяемом каталоге .agents/booster/snapshots/<commit>-<state>-<digest>/. Предыдущие снимки никогда не удаляются; .agents/booster/latest.json указывает на самый новый. Каждый снимок также сохраняет repo_map_architecture.md, repo_map_symbols.md и index_health.json. Архитектурная карта резервирует место для разнообразия модулей верхнего уровня и покрытия точек входа/конфигурации/контрактов; карта символов применяет ограничение на файл, чтобы большие файлы не могли исчерпать весь бюджет контекста.

Устранение неполадок

Booster отсутствует в VS Code

Проверьте обе области конфигурации:

booster control status --client vscode --scope workspace --project .
booster control status --client vscode --scope user --project .

Только запись рабочей области видна в этой рабочей области. Пользовательская запись видна во всех рабочих областях. Используйте MCP: List Servers, чтобы запустить, довериться, перезапустить или проверить сервер. Используйте MCP: Open User Configuration, чтобы открыть точный глобальный файл, который читает VS Code.

No module named rank_bm25

Клиент запускает другой системный Python вместо окружения Booster. Восстановите окружение и переподключитесь через Booster Control:

uv sync --locked --extra dev
booster control doctor --project .
booster control connect --client vscode --scope user --project . --force

Сканирование слишком узкое

Проверьте отчёт, затем выберите более широкий профиль или явные ограничения:

booster control scan --project . --profile deep
booster expand --profile deep

Проверка релиза

uv lock --check
uv run python -m pytest tests -q
uv run ruff check .
uv run python -m compileall -q booster_home indexing_jobs.py server.py
uv build

Подробные рабочие процессы см. в COOKBOOK.md. По вопросам публикации и распространения клиентов см. MARKETPLACE.md. Сопровождающие также должны прочитать CONTRIBUTING.md и CHANGELOG.md.

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

Booster уже поддерживает в памяти граф символов, вызовов и импортов Tree-sitter. Планируемые производственные улучшения включают:

• сохранение графа знаний в Neo4j или Memgraph для межсессионных графовых запросов и более глубокого обхода зависимостей;

• добавление headless LSP-клиентов для Pyright, TypeScript, rust-analyzer, gopls, clangd и языковых серверов Java;

• связывание коммитов с pull request'ами и issues, чтобы git_intelligence мог объяснить, почему код изменился, а не только что изменилось;

• добавление рецептов валидации для Docker Compose, проверок работоспособности и журналов служб;

• расширение встроенных навыков в агентно-специфичные пакеты архитектуры, отладки, памяти и качества.

Лицензия

MIT