Booster MCP

文档： English | Русский | 简体中文

Booster 是一个本地 Model Context Protocol (MCP) 服务器，也是面向 AI 编码代理的认知运行时。它为仓库构建一个有界、可查询的世界模型，使代理能够在修改代码之前检查架构、历史、诊断、项目规则和验证要求。

大多数代理已经拥有双手：它们可以快速编写补丁。Booster 为它们提供了通常缺失的感知层。

Booster 存在的原因

大型仓库之所以让代理不堪重负，主要不是因为文件数量多，而是因为重要的关系分散在源代码、测试、git 历史、诊断和项目约定中。

没有 Booster，代理通常会陷入这样的循环：

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

这个循环可能会遗漏：

• 目标符号的调用者和被调用者；

• 接口变更所影响的文件和测试；

• 令人费解的代码背后的历史原因；

• 项目特定规则和已存储的架构决策；

• 现有的编译器、类型、lint 或安全诊断；

• 补丁之后应该运行的验证命令。

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 控制平面

核心服务器提供：

• 通过 hybrid_search 进行归一化的 FAISS 余弦搜索、BM25 词法搜索和倒数排名融合；

• 具有可复现扫描配置的有界仓库扫描；

• 生成的 .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 的上下文资源；

• 符号、导入和调用图、flipcharts、Code City 和仓库诊断；

• 影响分析、git 智能、结构化项目记忆、安全检查和验证循环；

• 同步到 ~/.agents/skills 的十二个内置工作流技能；

• booster control，一个面向 MCP 客户端、扫描设置、诊断和启动器管理的跨平台控制面。

Booster Home 运行时

Home 是一个可选的本地数据平面。它保持 MCP 控制平面完整，并添加了一个 OpenAI 兼容网关，具有确定性上下文编译、有界本地工作器、会话范围的原始工件，以及与现有 Booster 索引和认知运行时的定向集成。

在回环地址上启动它：

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。

上游模型 ID 从 /v1/models 发现；将其替换为本地 OpenAI 兼容服务器报告的 ID。当输出预算被推理消耗时，Nemotron 部署可能返回特定于提供商的 reasoning_content 而不是 message.content。Home 保留该字段，并且不会将不完整的推理响应静默转换为成功答案。

流式响应作为块转发。在块被驱逐之前，其原始内容会保存为不可变工件，并通过内容哈希验证。如果持久化失败，请求会故障关闭，而不是静默丢失上下文。

仓库索引是基于任务的。add_repo(wait=true) 仍然被接受以保持兼容性，但不再阻塞 MCP 请求。使用 index_status、cancel_index 和有界的 wait_until_ready 来观察任务。每个状态包含 job_id、阶段、已处理/总计、已用时间、ETA、最后进度、生成 ID、过期状态和最后一个就绪快照。只读仓库方法在构建新代次时继续返回该就绪快照。

生成的工件按用途拆分：

• 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>

回环是默认设置，不需要网关令牌。除非在 TOML 中、通过 BOOSTER_HOME_AUTH_TOKEN 或使用 --auth-token 配置了 home.auth_token，否则非回环绑定会被拒绝。远程请求必须发送 Authorization: Bearer <token>；令牌永远不会通过状态或日志返回。

证明：Booster + Nemotron 4B

理解 Booster 的最有力方式是看它在难题上的循环。在一次使用相同 4B 级 Nemotron 模型的手动 LM Studio 运行中，一个看似合理的首次解决方案在隐藏用例上失败了。在 Booster 上下文、显式约束和修复并提交循环之后，相同的工作流产生了被接受的提交：

这种模式在额外的困难动态规划任务上重复出现：

• 689. Maximum Sum of 3 Non-Overlapping Subarrays：平局决胜失败 -> 43/43 被接受；

• 123. Best Time to Buy and Sell Stock III：214/214 被接受；

• 记录的接受运行显示 36 ms 和 170 ms 的本地运行时间。

这是一个证据案例研究，而不是受控基准。它展示了面向客户的价值：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，而不是将不透明的模型生成摘要呈现为事实依据。

二进制检查点主体永远不会被读取、索引或发送给模型。只有 文件名、大小、步骤、父级、指标、实验、状态、保留标志和分支等元数据可用。 侧车元数据会按照 .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/ 应 被视为单独的兼容性迁移，不应混入日常 功能开发中。

推荐的 Agent 提示词

此仓库包含一个专用的工程系统提示词： RECOMENDET_PROMPT.md。

在非平凡的编码会话开始时加载它，当 agent 需要 以工程师而非补丁生成器的身份工作时。该提示词定义了 项目上下文路由规则、PERCEIVE -> MODEL -> PLAN -> ACT -> VERIFY -> LEARN 工作流、Booster 优先的上下文检索、根本原因分析、 安全检查、验证要求和记忆纪律。

它是面向编码 agent 的仓库指南，而非应用程序运行时 配置。该提示词有意保留在根目录，以便 agent 工具 能在第一次编辑之前发现它。

安装

要求

• 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

每个安装程序都会在用户本地 bin 目录中创建一个 booster 启动器：

• Windows：%USERPROFILE%\.local\bin\booster.cmd；

• macOS 和 Linux：~/.local/bin/booster。

安装程序会将该目录添加到 PATH。如果当前 shell 尚未看到该启动器，请打开一个新的终端。

开发安装

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，直到启动器安装完成。

Agent 引导：粘贴 GitHub 链接，获取工作流

当此仓库从 GitHub URL 在 AI 编码 agent 中打开时， agent 应将 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 启动器。

然后，agent 应使用以下命令开始每个非平凡任务：

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 是 agent 宿主可以发现指令文件； 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 .

用户级服务器启动后，让 agent 为当前正在编辑的仓库调用 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 中添加本地排除项。

认知运行时工作流

当 agent 即将更改代码时，请使用此流程：

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 发现。这可以防止 agent 将失败的验证运行误认为 干净的代码库。

示例

重构之前

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

agent 可以回答什么调用了该服务、它调用了什么、哪些文件 受影响、哪些测试相关，以及是否已存在红色诊断。

在 Bug 排查期间

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

agent 可以结合堆栈跟踪、调用图和可疑行背后的 历史原因。

用于长期项目知识

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/snapshots/<commit>-<state>-<digest>/ 目录中保留 .agents/booster/repo_map.md、code_city.html、scan_config.json 和 scan_report.json。以前的快照永远不会被删除；.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，以支持跨会话图查询和更深入的依赖遍历；

• 为 Pyright、TypeScript、rust-analyzer、gopls、clangd 和 Java 语言服务器添加无头 LSP 客户端；

• 将提交与拉取请求和问题关联起来，使 git_intelligence 能够解释代码为何更改，而不仅仅是更改了什么；

• 为 Docker Compose、健康检查和服务日志添加验证配方；

• 将捆绑的技能扩展为特定于代理的架构、调试、内存和质量包。

许可证

MIT