Booster MCP

Documentación: English | Русский | 简体中文

Booster es un servidor local de Model Context Protocol (MCP) y un runtime cognitivo para agentes de codificación de IA. Construye un modelo de mundo acotado y consultable de un repositorio para que un agente pueda inspeccionar la arquitectura, el historial, los diagnósticos, las reglas del proyecto y los requisitos de validación antes de cambiar el código.

La mayoría de los agentes ya tienen manos: pueden escribir parches rápidamente. Booster les proporciona la capa de percepción que suele faltar.

Por qué existe Booster

Los repositorios grandes no abruman a los agentes principalmente porque contengan muchos archivos. Los abruman porque las relaciones importantes están dispersas entre el código fuente, las pruebas, el historial de git, los diagnósticos y las convenciones del proyecto.

Sin Booster, un agente suele seguir este bucle:

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

Ese bucle puede pasar por alto:

• llamadores y destinatarios del símbolo objetivo;

• los archivos y pruebas afectados por un cambio de interfaz;

• la razón histórica detrás de un código sorprendente;

• reglas específicas del proyecto y decisiones arquitectónicas almacenadas;

• diagnósticos existentes de compilador, tipos, lint o seguridad;

• el comando de validación que debería ejecutarse después del parche.

Booster añade esas señales al bucle:

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)

Capacidades

Arquitectura

Booster tiene dos planos complementarios:

• Plano de control MCP: indexación de repositorios, búsqueda semántica, gráficos, memoria, diagnósticos, habilidades y herramientas de validación.

• Plano de datos de Booster Home: una pasarela local opcional compatible con OpenAI que compila contexto, almacena artefactos recuperables y reenvía solicitudes a un backend de modelo local o remoto.

El índice de repositorio existente y el Cognitive Runtime se reutilizan. Home no crea un segundo índice de repositorio, pasarela ni base de datos vectorial.

Plano de control MCP

El servidor principal proporciona:

• búsqueda coseno FAISS normalizada, búsqueda léxica BM25 y fusión de rango recíproco mediante hybrid_search;

• escaneo acotado de repositorios con perfiles de escaneo reproducibles;

• artefactos generados en .agents/booster/ como repo_map_architecture.md, repo_map_symbols.md, index_health.json, repo_map.md, code_city.html, scan_config.json y scan_report.json;

• recursos de contexto en repo://map, repo://stack, repo://conventions y repo://artifacts;

• símbolos, gráficos de importación y llamadas, flipcharts, Code City y diagnósticos de repositorio;

• análisis de impacto, inteligencia de git, memoria de proyecto estructurada, comprobaciones de seguridad y bucles de validación;

• doce habilidades de flujo de trabajo incluidas sincronizadas con ~/.agents/skills;

• booster control, una superficie de control multiplataforma para clientes MCP, ajustes de escaneo, diagnósticos y gestión del lanzador.

Runtime de Booster Home

Home es un plano de datos local opcional. Mantiene intacto el plano de control MCP y añade una pasarela compatible con OpenAI con compilación de contexto determinista, trabajadores locales acotados, artefactos sin procesar con ámbito de sesión e integración específica con el índice de Booster y el Cognitive Runtime existentes.

Inícialo en loopback:

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

Home expone:

• /v1/models;

• /v1/chat/completions;

• /v1/responses;

• /health;

• /booster/status.

El ID del modelo ascendente se descubre desde /v1/models; reemplázalo con el ID informado por el servidor local compatible con OpenAI. Las implementaciones de Nemotron pueden devolver reasoning_content específico del proveedor en lugar de message.content cuando el presupuesto de salida se consume en el razonamiento. Home conserva ese campo y no convierte silenciosamente una respuesta de razonamiento incompleta en una respuesta exitosa.

Las respuestas de streaming se reenvían en fragmentos. Antes de que un bloque sea desalojado, su contenido sin procesar se guarda como un artefacto inmutable y se verifica mediante hash de contenido. Si la persistencia falla, la solicitud falla de forma cerrada en lugar de perder contexto silenciosamente.

La indexación de repositorios se basa en trabajos. add_repo(wait=true) sigue siendo aceptado por compatibilidad, pero ya no bloquea la solicitud MCP. Usa index_status, cancel_index y wait_until_ready acotado para observar un trabajo. Cada estado contiene job_id, fase, procesado/total, tiempo transcurrido, ETA, último progreso, ID de generación, estado obsoleto y la última instantánea lista. Los métodos de repositorio de solo lectura continúan devolviendo esa instantánea lista mientras se construye una nueva generación.

Los artefactos generados se dividen por propósito:

• repo_map_architecture.md es un mapa macro acotado con diversidad de módulos de nivel superior, cobertura de puntos de entrada/configuración/contratos y un resumen de cobertura;

• repo_map_symbols.md contiene el mapa de símbolos detallado con un límite por archivo;

• index_health.json registra la generación, rutas obsoletas, archivos seleccionados/omitidos y la completitud del mapa;

• repo_map.md sigue siendo una copia de compatibilidad del mapa de arquitectura.

La precedencia de configuración es:

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

Las claves API se usan solo en los encabezados de solicitudes ascendentes y se redactan del estado, la telemetría, las líneas de tiempo, los registros y el texto de excepciones. Estos comandos inspeccionan Home sin iniciar un segundo servidor ni índice de repositorio:

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

Loopback es el valor predeterminado y no requiere un token de pasarela. Un enlace que no sea loopback se rechaza a menos que home.auth_token esté configurado, ya sea en TOML, mediante BOOSTER_HOME_AUTH_TOKEN o con --auth-token. Las solicitudes remotas deben enviar Authorization: Bearer <token>; el token nunca se devuelve en el estado ni en los registros.

Prueba: Booster + Nemotron 4B

La forma más contundente de entender Booster es ver el bucle en un problema difícil. En una ejecución manual de LM Studio con el mismo modelo Nemotron de clase 4B, una primera solución plausible falló en casos ocultos. Después del contexto de Booster, restricciones explícitas y un bucle de reparación y envío, el mismo flujo de trabajo produjo envíos aceptados:

El patrón se repitió en tareas adicionales de programación dinámica difíciles:

• 689. Maximum Sum of 3 Non-Overlapping Subarrays: fallo en el desempate -> 43/43 aceptados;

• 123. Best Time to Buy and Sell Stock III: 214/214 aceptados;

• las ejecuciones aceptadas registradas muestran tiempos de ejecución locales de 36 ms y 170 ms.

Este es un estudio de caso basado en evidencia, no un benchmark controlado. Demuestra el valor para el cliente: Booster mantiene restricciones, contexto del proyecto, diagnósticos y validación en un solo bucle en lugar de detenerse en un código que simplemente parece correcto.

Consulta el estudio de caso completo de LeetCode para ver la línea base, los pasos de reparación, las capturas de pantalla y la lista de verificación de reproducción.

Compresión de contexto

Home trata la compresión como compilación de contexto, no como olvido irreversible:

1. Clasificar mensajes por rol y tipo de contenido.

2. Normalizar el ruido determinista, como líneas duplicadas, salida de progreso y secuencias de escape ANSI.

3. Persistir el bloque original antes de que pueda ser desalojado.

4. Puntuar la relevancia y asignar el presupuesto de entrada disponible por prioridad.

5. Opcionalmente, ejecutar trabajadores semánticos acotados y recuperación específica del modelo de mundo.

6. Empaquetar los mensajes seleccionados preservando el contexto protegido y la integridad de las llamadas a herramientas.

El compilador informa original_tokens, compiled_tokens, removed_tokens, compression_ratio, operaciones, advertencias y referencias de artefactos. Los invariantes principales son:

• el contexto del sistema y del usuario activo están protegidos;

• los límites duros conocidos fallan de forma cerrada cuando el contexto protegido no cabe;

• los datos sin procesar se persisten antes del desalojo;

• el contenido de los artefactos se verifica mediante hash después de escribir y leer;

• la compresión se puede deshabilitar, pero policy=off aún rechaza una solicitud por encima de un presupuesto de entrada duro conocido;

• los campos específicos del proveedor, incluido reasoning_content, se conservan.

Ejecuta el benchmark de estrés incluido:

uv run python benchmarks/home_context_benchmark.py

El benchmark imprime recuentos de tokens sin procesar, deterministas, recuperados y finales, relación de compresión, latencia del compilador, recuperación exacta de artefactos y resultados de enriquecimiento específico. Una ejecución exitosa debe incluir:

exact_artifact_recovery=True

Coprocesador de investigación

Home también incluye un coprocesador de investigación acotado para experimentos locales. Lee evidencia de research_state.json, memory_bank.md o memory-bank/*.md, métricas y archivos de informe. Devuelve JSON estructurado en lugar de presentar un resumen opaco generado por el modelo como verdad absoluta.

Los cuerpos binarios de los checkpoints nunca se leen, indexan ni envían al modelo. Solo se dispone de metadatos como nombre de archivo, tamaño, paso, padre, métricas, experimento, estado, indicador de conservación y rama. Los metadatos sidecar se buscan junto al checkpoint siguiendo las convenciones .pt.json, .json, _metadata.json y .metadata.json.

El paquete de contexto se organiza como:

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

La inferencia normal usa L0, L1 y las partes relevantes de L2 y L3. Los registros duplicados, las versiones antiguas fallidas, los artefactos binarios y el historial irrelevante se excluyen por política. El contenido del repositorio, las métricas, los informes y la memoria son datos no fiables y no se ejecutan como configuración.

Los roles de trabajador permitidos son:

log_analyst
code_search
benchmark_reader
artifact_indexer
summarizer

El estado de investigación y el registro se escriben atómicamente en <project>/research_state.json. Los artefactos de sesión del directorio home permanecen separados en .agents/booster/runtime/sessions/; el estado de investigación no se mezcla con las líneas temporales de chat ni con el archivo de memoria heredado .agents/booster/memory.json.

Estructura del Repositorio

.
├── 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

Los módulos legacy del plano de control de MCP permanecen intencionadamente en la raíz del repositorio. Los puntos de entrada del paquete (server:main y cli:main) y las integraciones existentes dependen de esos nombres de módulo estables. Moverlos a src/ debe tratarse como una migración de compatibilidad separada, no debe mezclarse con el trabajo rutinario de funcionalidades.

Prompt Recomendado para el Agente

Este repositorio incluye un prompt de sistema de ingeniería dedicado: RECOMENDET_PROMPT.md.

Cárgalo al comienzo de una sesión de codificación no trivial cuando el agente necesite trabajar como ingeniero y no como generador de parches. El prompt define las reglas de enrutamiento del contexto del proyecto, el flujo de trabajo PERCEIVE -> MODEL -> PLAN -> ACT -> VERIFY -> LEARN, la recuperación de contexto Booster-first, el análisis de causa raíz, las comprobaciones de seguridad, los requisitos de validación y la disciplina de memoria.

Es una guía de repositorio para agentes de codificación, no una configuración de tiempo de ejecución de la aplicación. El prompt se mantiene intencionadamente en la raíz para que las herramientas del agente puedan descubrirlo antes de la primera edición.

Instalación

Requisitos

• Python 3.11, 3.12 o 3.13. Se recomienda Python 3.12.

• Git.

• Acceso a Internet en la primera ejecución para descargar el modelo de embeddings.

Windows

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

macOS y Linux

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

Cada instalador crea un lanzador booster en el directorio bin local del usuario:

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

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

El instalador añade ese directorio a PATH. Abre una nueva terminal si el shell actual aún no ve el lanzador.

Instalación de Desarrollo

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

Sin uv, usa un entorno virtual de Python 3.12:

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

En Windows, actívalo con \.venv\Scripts\Activate.ps1 y usa \.venv\Scripts\booster.exe hasta que el lanzador esté instalado.

Arranque del Agente: Pega un Enlace de GitHub, Obtén el Flujo de Trabajo

Cuando este repositorio se abre desde una URL de GitHub en un agente de codificación con IA, el agente debe tratar AGENTS.md como el contrato de arranque del proyecto. Debe instalar las dependencias locales, sincronizar las habilidades de Booster, cargar la guía de ingeniería, crear los artefactos acotados del repositorio y conectar el servidor MCP antes de editar código.

Ejecuta esto una vez desde la raíz del repositorio:

# 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 .

Para Claude Desktop, usa en su lugar la conexión a nivel de usuario:

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

Si uv no está disponible, usa python -m pip install -e ".[dev]" y reemplaza uv run booster por python -m cli o por el lanzador booster instalado.

El agente debe comenzar entonces cada tarea no trivial con:

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.

Esto es intencionadamente a nivel de proyecto y portable. Un repositorio no debe reescribir silenciosamente el prompt de sistema oculto de una aplicación anfitriona ni la configuración global de cliente no relacionada. AGENTS.md es el archivo de instrucciones que los anfitriones de agentes pueden descubrir; booster control connect cambia solo la entrada del cliente MCP seleccionado y preserva los demás servidores.

Conectar con VS Code

Ejecuta el menú de control desde el repositorio que quieras gestionar:

booster control

Usa una conexión de espacio de trabajo para un repositorio:

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

Usa una conexión de usuario cuando Booster deba aparecer en todos los espacios de trabajo de VS Code:

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

Después de que se inicie un servidor a nivel de usuario, pide al agente que llame a add_repo para el repositorio que se está editando actualmente. La indexación se ejecuta en segundo plano por defecto; index_status informa de la fase y el progreso. add_repo(wait=true) sigue siendo aceptado por compatibilidad, pero también es no bloqueante. Usa cancel_index o wait_until_ready acotado cuando sea necesario. Usa --with-repository para vincular un servidor a nivel de usuario a un único repositorio.

VS Code mantiene la configuración MCP de espacio de trabajo y de usuario por separado. Después de cambiar un servidor, ejecuta MCP: List Servers, selecciona Booster, inícialo o reinícialo y acepta la solicitud de confianza. Si sigue sin aparecer, ejecuta Developer: Reload Window e inspecciona MCP: List Servers -> Booster -> Show Output.

Control de Booster

booster control proporciona gestión interactiva de conexiones, perfiles de escaneo, actualización de artefactos, diagnósticos, eliminación de servidores y actualizaciones del lanzador. Las mismas operaciones están disponibles de forma no interactiva:

# 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 .

Escaneo Acotado de Repositorios

Ejecuta booster expand antes de vincular un repositorio grande. Guarda la política de escaneo y genera un mapa inicial sin requerir una conexión MCP activa.

booster expand --profile balanced

El escáner prioriza las raíces de código fuente convencionales, ignora por defecto los directorios generados y de dependencias, y registra cada decisión de límite en .agents/booster/scan_report.json. Añade exclusiones locales en .boosterignore cuando un directorio sea irrelevante para la tarea actual.

Flujo de Trabajo del Runtime Cognitivo

Usa este flujo cuando un agente esté a punto de cambiar código:

1. Recupera las reglas del proyecto con project_memory_recall.

2. Encuentra el objetivo con hybrid_search, semantic_search o find_symbol.

3. Estima el radio de impacto con impact_analysis.

4. Comprueba el historial con git_intelligence cuando el código resulte inesperado.

5. Recopila diagnósticos con collect_diagnostics para los archivos implicados. Para cambios sensibles a la seguridad, ejecuta el asesoramiento independiente security_audit.

6. Aplica parches de forma limitada usando los patrones existentes del proyecto.

7. Valida con run_validation_checks y repara la misma porción hasta que pase o la hipótesis sea rechazada.

Comprobación previa típica:

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>")

Validación típica posterior al parche:

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

Los diagnósticos son de cierre ante fallos

Booster trata los diagnósticos como evidencia de ingeniería. Una herramienta de diagnóstico que agota el tiempo, se bloquea o devuelve una salida no analizable se informa como un hallazgo error. Esto evita que un agente confunda una ejecución de validación rota con una base de código limpia.

Ejemplos

Antes de una Refactorización

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

El agente puede responder qué llama al servicio, a qué llama este, qué archivos están afectados, qué pruebas son relevantes y si ya existen diagnósticos en rojo.

Durante una Caza de Errores

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

El agente puede combinar el stack trace, el grafo de llamadas y la razón histórica detrás de una línea sospechosa.

Para el Conocimiento del Proyecto a Largo Plazo

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

Las sesiones futuras pueden recordar ese hecho antes de editar la API o el frontend.

Habilidades de Flujo de Trabajo Incluidas

• 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

Herramientas MCP Clave

Los enlaces de repositorio se conservan en el registro de usuario compartido en ~/.booster/repositories/, de modo que los procesos MCP iniciados de forma independiente ven los mismos proyectos activos. booster.task_complete pone en cola un reindexado final acotado para los repositorios de la tarea. Cada índice completado conserva .agents/booster/repo_map.md, code_city.html, scan_config.json y scan_report.json en un directorio inmutable .agents/booster/snapshots/<commit>-<state>-<digest>/. Las instantáneas anteriores nunca se eliminan; .agents/booster/latest.json apunta a la más reciente. Cada instantánea también conserva repo_map_architecture.md, repo_map_symbols.md e index_health.json. El mapa de arquitectura reserva espacio para la diversidad de módulos de nivel superior y la cobertura de puntos de entrada, configuración y contratos; el mapa de símbolos aplica un límite por archivo para que los archivos grandes no puedan consumir todo el presupuesto de contexto.

Solución de problemas

Booster no aparece en VS Code

Compruebe ambos ámbitos de configuración:

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

Solo una entrada de área de trabajo es visible en esa área de trabajo. Una entrada de usuario es visible en todas las áreas de trabajo. Use MCP: List Servers para iniciar, confiar, reiniciar o inspeccionar el servidor. Use MCP: Open User Configuration para abrir el archivo global exacto que VS Code está leyendo.

No module named rank_bm25

El cliente está iniciando un Python del sistema distinto en lugar del entorno de Booster. Repare el entorno y vuelva a conectarse a través de Booster Control:

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

El escaneo es demasiado limitado

Inspeccione el informe y, a continuación, seleccione un perfil más amplio o límites explícitos:

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

Validación de lanzamiento

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

Para flujos de trabajo detallados, consulte COOKBOOK.md. Para la publicación y la distribución de clientes, consulte MARKETPLACE.md. Los mantenedores también deberían leer CONTRIBUTING.md y CHANGELOG.md.

Hoja de ruta

Booster ya mantiene un grafo en memoria de símbolos, llamadas e importaciones de Tree-sitter. Las mejoras de producción previstas incluyen:

• persistir el grafo de conocimiento en Neo4j o Memgraph para consultas de grafo entre sesiones y un recorrido de dependencias más profundo;

• añadir clientes LSP headless para Pyright, TypeScript, rust-analyzer, gopls, clangd y los servidores de lenguaje Java;

• vincular los commits con las pull requests y los issues para que git_intelligence pueda explicar por qué cambió el código, y no solo qué cambió;

• añadir recetas de validación para Docker Compose, comprobaciones de estado y registros de servicio;

• ampliar las habilidades integradas para convertirlas en paquetes específicos de agente de arquitectura, depuración, memoria y calidad.

Licencia

MIT