Bombe MCP

炸弹

Bombe是一个用于AI编码代理的结构感知代码检索MCP服务器。 它从源代码构建一个本地图索引，然后为以下对象提供图感知工具：

• 符号发现
• 呼叫者/被呼叫者/引用遍历
• 数据流跟踪
• 变更影响估算
• 令牌预算上下文组装

运行时首先是本地的，在没有任何控制平面的情况下工作。当需要共享智能时，包括可选的混合同步模块用于增量/工件交换。

目录

• 特性
• 需求
• 安装
• 快速开始
• CLI参考
• 环境变量
• MCP工具
• 建筑
• 索引模型
• 混合同步模型
• 性能和释放门
• 仓库布局
• Runbook
• 开发流程
• 规范路线图
• 验证快照
• 故障排除和限制
• 状态

特性

• 使用SQLite进行本地首图索引
• 多语言符号提取（Python、TypeScript、Java、Go）
• 调用/导入/类型依赖边进行结构遍历
• 具有合约测试的严格MCP工具模式
• 增量索引支持（git+非git回退）和性能趋势跟踪
• 具有每次运行摘要的持久解析/索引诊断
• 包括/排除索引过滤器+ .bombeignore 支持
• 具有确定性合并+吞吐量遥测的并行提取路径
• 敏感路径排除和上下文编辑保护
• 发布延迟和工作流质量门的治理检查

需求

• python >=3.11
• 防锈工具链(生锈)
• 马图林 (pip install maturin)
• 对存储库进行本地签出以建立索引
• 对配置的数据库位置的写访问权限

安装

构建并安装Rust扩展，然后是Python包：

maturin develop --manifest-path crates/bombe-core/Cargo.toml
python3 -m pip install .

开发人员安装：

maturin develop --manifest-path crates/bombe-core/Cargo.toml
python3 -m pip install ".[dev]"

快速开始

初始化存储：

PYTHONPATH=src python3 -m bombe.server --repo . --init-only --log-level INFO

运行完整索引：

PYTHONPATH=src python3 -m bombe.server --repo . index-full

启动服务器（STDIO MCP运行时 mcp 可用）：

PYTHONPATH=src python3 -m bombe.server --repo . --log-level INFO

检查运行时运行状况：

PYTHONPATH=src python3 -m bombe.server --repo . doctor

CLI参考

全球争论

子指令

命令示例

完整索引：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo index-full

增量指数：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo index-incremental

带过滤器的增量索引：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo --include "src/**/*.py" --exclude "*test*" index-incremental

混合全索引+同步：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo --hybrid-sync index-full

以渐进式热身方式上菜：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo --hybrid-sync serve --index-mode incremental

监视模式（单周期）：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo watch --max-cycles 1 --poll-interval-ms 500

在可用时使用文件系统事件的监视模式：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo watch --watch-mode fs --max-cycles 1

最新运行的诊断：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo diagnostics --severity error --diagnostics-limit 100

具有安全自动修复功能的医生：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo doctor --fix

严格的配置文件预检（当所需的解析器后端不可用时，会很快失败）：

PYTHONPATH=src python3 -m bombe.server --repo /abs/repo --runtime-profile strict preflight

环境变量

MCP工具

可用工具：

• search_symbols
• get_references
• get_context
• get_structure
• get_blast_radius
• trace_data_flow
• change_impact
• get_indexing_diagnostics
• get_server_status
• estimate_context_size
• get_context_summary
• get_entry_points
• get_hot_paths
• get_orphan_symbols

输入示例

search_symbols

{"query":"auth","kind":"function","limit":20}

get_references

{"symbol_name":"app.auth.authenticate","direction":"both","depth":2}

get_context

{"query":"authenticate flow","entry_points":["app.auth.authenticate"],"token_budget":1200}

get_structure

{"path":".","token_budget":4000,"include_signatures":true}

get_blast_radius

{"symbol_name":"app.auth.authenticate","change_type":"behavior","max_depth":3}

trace_data_flow

{"symbol_name":"app.auth.authenticate","direction":"both","max_depth":3}

change_impact

{"symbol_name":"app.auth.authenticate","change_type":"signature","max_depth":3}

get_indexing_diagnostics

{"run_id":"","stage":"parse","severity":"error","limit":50}

get_server_status

{"diagnostics_limit":20,"metrics_limit":20}

estimate_context_size

{"query":"authenticate flow","entry_points":["app.auth.authenticate"],"token_budget":1200}

get_context_summary

{"query":"authenticate flow","entry_points":["app.auth.authenticate"],"token_budget":1200}

get_entry_points

{"limit":20}

get_hot_paths

{"limit":20}

get_orphan_symbols

{"limit":50}

所有字典返回工具也接受：

{"include_explanations":true}

启用后，响应包括 explanations 带有推理元数据的部分。

所有工具还接受：

{"include_plan":true}

启用后，dict响应包括 planner_trace 元数据（缓存模式、查找/计算定时、缓存纪元令牌）。

合同生效

严格的合同行为通过以下方式验证：

• tests/test_mcp_contract.py

建筑

Bombe使用Rust内核(_bombe_core 通过PyO3/multerin），使用薄Python包装器提供面向MCP的API。

本地运行时

• 文件扫描和语言检测（Rust）
• 树保姆解析加上符号提取加上调用/导入解析（Rust）
• 可选的语义接收者类型提示合并到呼叫解析中
• SQLite图形存储（Rust通过rusqlite）

- files - symbols - edges - external_deps - FTS虚拟表 symbol_fts

• 查询引擎

- 搜索 - 参考文献 - 上下文组装 - 爆炸半径 - 数据流 - 变更影响

• MCP工具注册和处理程序接线
• 用于重复有效载荷的查询计划器缓存层
• 带有可选模型感知令牌计数的令牌化器抽象(tiktoken 如果已安装）

混合模块

• src/bombe/sync/client.py

- 兼容性检查 - 异步推/拉 - 超时预算 - 断路器 - 校验和验证 - 可选工件签名验证 - 隔离

• src/bombe/sync/reconcile.py

- 晋升政策关卡 - 触摸范围合并优先级

• src/bombe/sync/transport.py

- 本地混合部署的文件支持控制平面传输

• src/bombe/sync/orchestrator.py

- 基于局部图状态的delta构造 - 持续同步队列状态更新 - pull+conference+artifact pin flow

发布治理

src/bombe/release/gates.py 根据硬阈值评估记录的套件指标，并返回通过/失败。

可观察性和持久状态

SQLite模式版本 6 包括操作和诊断状态：

• sync_queue
• artifact_quarantine
• artifact_pins
• circuit_breakers
• sync_events
• tool_metrics
• indexing_diagnostics
• migration_history
• trusted_signing_keys
• 回购元数据密钥 cache_epoch 用于查询缓存无效

索引模型

高层管道：

1. 浏览存储库文件并检测支持的语言。
2. 解析文件并提取符号/导入。
3. 解析导入并调用边。
4. 将符号/边/依赖关系持久化到SQLite中。
5. 重新计算查询层使用的排名特征。

增量路径仅更新更改的文件，然后重建受影响的图形状态。

护栏和安全限制

对深度、限制和查询长度实施了运行时有效负载护栏：

• 搜索限制限制为最大值 100
• 图形深度限制为最大值 6
• 上下文令牌预算被限制在最大值 32000
• 入境点上限为 32
• 横向节点/边缘帽可防止失控膨胀
• 自适应遍历上限按存储库符号计数缩放，以确保大型存储库内存安全

这些限制在 src/bombe/query/guards.py.

混合同步模型

混合同步是累加的，不会取代本地查询服务。

• 本地路径仍然具有权威性和可用性。
• 不兼容的工件被拒绝。
• 损坏的文物被隔离。
• 配置签名时，将隔离签名不匹配。
• 可以在中的每个存储库中持久化受信任的密钥策略 trusted_signing_keys 用于验证密钥选择。
• 重复的远程故障会打开断路器。
• 结果明确暴露了回退模式(local_fallback)当远程操作被跳过或失败时。
• 同步结果保存在SQLite中(sync_queue, sync_events, artifact_pins, circuit_breakers).

备份和恢复

数据库备份/还原助手可在 Database:

from pathlib import Path
from bombe.store.database import Database

db = Database(Path("/abs/repo/.bombe/bombe.db"))
backup_path = db.backup_to(Path("/tmp/bombe-backup.db"))
db.restore_from(backup_path)

性能和释放门

运行性能套件：

BOMBE_RUN_PERF=1 PYTHONPATH=src python3 -m unittest discover -s tests/perf -p "test_*.py" -v

运行可选的真实仓库评估（OpenSearch/KubeKubernetes风格的本地签出）：

BOMBE_RUN_PERF=1 BOMBE_REAL_REPO_PATHS=/abs/opensearch,/abs/kubernetes PYTHONPATH=src python3 -m unittest tests.perf.test_real_repo_eval -v

评估放行门：

PYTHONPATH=src python3 -m bombe.release.gates --history /tmp/bombe-perf-history.jsonl

当前闸门系列：

• index
• incremental
• query
• workflow_gates
• gold_eval

阈值定义见 src/bombe/release/gates.py.

仓库布局

• src/bombe/indexer：扫描、解析、提取、导入、调用图、排名、管道
• src/bombe/query：工具后端
• src/bombe/store：SQLite模式和迁移
• src/bombe/tools：MCP定义和模式
• src/bombe/sync：混合同步客户端和协调逻辑
• src/bombe/release：释放门评估器
• tests：单元和集成测试
• tests/perf：perf套件和工作流工具
• tests/perf/real_repo_harness.py：env驱动的真实仓库评估工具
• docs/plans：实施设计文档
• docs/runbooks：操作员操作手册

Runbook

• docs/runbooks/local-only-mode.md
• docs/runbooks/hybrid-mode.md
• docs/runbooks/rollback-and-quarantine.md

开发流程

编译：

PYTHONPATH=src python3 -m compileall src tests

运行测试套件：

PYTHONPATH=src python3 -W error -m unittest discover -s tests -p "test_*.py"

烟雾初始化服务器：

PYTHONPATH=src python3 -m bombe.server --repo . --init-only --log-level INFO

CI职位 .github/workflows/ci.yml:

• rust-check --fmt、clippy、Rust单元测试
• python-with-rust --构建扩展、Python测试、覆盖率（90%阈值）、lint、类型检查

建议本地所有检查运行：

PYTHONPATH=src python3 -m compileall src tests
PYTHONPATH=src python3 -W error -m unittest discover -s tests -p "test_*.py"
BOMBE_RUN_PERF=1 PYTHONPATH=src python3 -m unittest discover -s tests/perf -p "test_*.py" -v
PYTHONPATH=src python3 -m bombe.release.gates --history /tmp/bombe-perf-history.jsonl

规范路线图

实施被跟踪为九个执行阶段，因此代理可以根据规范结果审核进度：

1. 合同和身份基础
2. 本地呼叫解析精度
3. 碰撞安全符号/边缘标识映射
4. 迁移框架和持久状态
5. 查询护栏和质量指标
6. 混合同步协议与协调
7. 服务器生命周期命令和操作状态
8. 工作流基准门和发布门集成
9. 可观察性、运行手册和操作员准备情况

详细执行计划：

• docs/plans/2026-02-08-spec-completion-9-phase-execution-plan.md

验证快照

最新本地验证运行（2026-02-10）：

• PYTHONPATH=src python3 -m compileall src tests ->通行证
• PYTHONPATH=src python3 -W error -m unittest discover -s tests -p "test_*.py" ->通行证(190 测验， 8 跳过性能基准测试）
• BOMBE_RUN_PERF=1 BOMBE_PERF_HISTORY=/tmp/bombe-perf-history.final.jsonl PYTHONPATH=src python3 -m unittest discover -s tests/perf -p "test_*.py" -v ->通行证(6 测验， 1 跳过时 BOMBE_REAL_REPO_PATHS 未设置）
• PYTHONPATH=src python3 -m bombe.release.gates --history /tmp/bombe-perf-history.final.jsonl -> RELEASE_GATES=PASS

故障排除和限制

故障排除

• 解析/提取失败

- 验证文件扩展名和语法 - 确认文件位于索引仓库路径下

• 空查询输出

- 验证索引是否已完成以及DB中是否存在符号

• 闸门故障

- 检查性能历史JSONL - 只重新运行失败的套件 - 再次评估 bombe.release.gates

已知限制

• 静态呼叫解析可能会错过动态调度和反射密集型模式。
• 高度动态代码库中的精确性/召回率取决于语义信号质量。
• 实现了混合同步原语，但共享控制平面的部署拓扑仍然是特定于运营商的。

状态

积极实现混合、规范完整的MCP遍历/运行时，带有硬释放门和运算符运行本。