内容
# livefire-mcp
`livefire-mcp` 为威胁狩猎代理提供只读 SQL 访问权限，访问已完成的 [open-bots v3](https://github.com/audityourcontracts/open-bots/tree/main/v3) 数据集，以及一个仅允许追加的、明确为未经验证的标志提交账本。它是 [LiveFire](https://github.com/audityourcontracts/livefire) 的原生数据接口，也可以由 Codex、Hermes、Pi 或任何支持本地 stdio 服务器的 MCP 客户端独立使用。
该仓库在单个强化 Rust 数据主机上构建两个接口：
- `livefire-mcp` — 基于 stdio 的类型化模型上下文协议（Model Context Protocol）服务器。
- `livefire-data` — 适用于已经具有受限 shell 工具的代理的 JSON CLI。
这两个接口使用相同的数据集绑定、SQL 授权、DuckDB 连接、结果编码和资源限制。这使得 CLI 在评估 MCP 是否改变猎人的行为时非常有用。
## 状态
该服务器旨在用于本地、单用户实验。它不暴露 HTTP 监听器，不接受远程数据集 URL，并通过一个 DuckDB 工作线程序列化查询。它的功能故意比通用数据库 MCP 服务器更窄。
## 先决条件
- 由单独的 [open-bots 仓库](https://github.com/audityourcontracts/open-bots/tree/main/v3) 生成的已完成、已验证的 `open-bots/v3/output` 目录。
- 从源代码构建 `livefire-mcp` 时，需要 Rust 1.97 或更新版本。
- 安装发布版本时，需要 GitHub CLI 访问此私有仓库。
- 可选的协议烟雾测试需要 Node.js。
转换原始 BOTS v3 数据并未在此仓库中实现。该单独的第一阶段需要 Docker、本地复制的 BOTS v3 和至少 10 GB 的空磁盘空间。下面的端到端说明显示了两个仓库之间的交接。
预期的 open-bots 布局是：
```text
output/
├── manifests/
│ ├── validation.json
│ └── parquet.json
└── parquet/
└── events/
└── event_date=.../*.parquet
```
在启动此服务器之前，请运行 open-bots v3 管道完成其验证、Parquet 和验证门。
## 端到端：BOTS v3 到 Codex
`open-bots` 和 `livefire-mcp` 是单独的 Git 仓库，具有刻意的基于文件的交接：
```text
原始 BOTS v3 数据集
│
▼
open-bots/v3: make all
│
└── output/manifests/*.json
└── output/parquet/events/**/*.parquet
│
▼
livefire-mcp --output-root /absolute/path/to/open-bots/v3/output
│
▼
Codex 工具
```
您必须在启动 `livefire-mcp` 之前完成 `open-bots` 转换和验证。此仓库不会下载 BOTS、运行 Splunk、创建 Parquet 文件或直接接受原始 BOTS 目录。一旦 Parquet 存在，请指向 `livefire-mcp` 到已完成的 `output` 目录，让 Codex 启动 stdio 上的 MCP 服务器。无需运行数据库守护进程。
### 1. 将 BOTS v3 转换为验证的 Parquet
使用上游 [BOTS v3 说明](https://github.com/splunk/botsv3) 获取和提取原始数据集。提取的根目录必须至少包含：
```text
default/indexes.conf
var/lib/splunk/botsv3/db/.bucketManifest
```
克隆单独的 `open-bots` 仓库，配置绝对源路径，并从该检出运行其完整管道：
```sh
git clone https://github.com/audityourcontracts/open-bots.git
cd open-bots/v3
cp .env.example .env
${EDITOR:-vi} .env
make all
```
至少在运行 `make all` 之前，在 `.env` 中设置这些值：
```dotenv
SPLUNK_PASSWORD=replace-with-a-long-random-password
BOTS_SOURCE=/absolute/path/to/extracted/botsv3_data_set
OUTPUT_DIR=output
```
该管道挂载源以只读方式，使用临时 Splunk 容器解码旧桶，验证青铜导出，写入分区 Parquet，并使用 DuckDB 和 Polars 独立验证结果。它不会修改原始 BOTS 文件。在 ARM64 上，解码器在 x86-64 仿真下运行，导出可能需要一些时间。
确认两个清单都已通过后再继续：
```sh
jq '{rows, row_count_valid, sha256_valid, event_addresses_unique}' \
output/manifests/validation.json
jq '{status, rows, parquet_files, raw_bytes}' \
output/manifests/parquet.json
```
对于已发布的 BOTS v3 源，预期结果是 2,030,269 行，`row_count_valid`、`sha256_valid` 和 `event_addresses_unique` 均设置为 `true`，Parquet `status` 设置为 `PASS`。提供给 `livefire-mcp` 的目录是绝对的 `open-bots/v3/output` 路径，而不是 `output/parquet` 和不是生成的 DuckDB 文件。
此时，交接工件已完成。保持对该 `output` 目录的绝对路径；下面每个源代码构建、发布安装或 Codex 注册都使用该路径作为 `--output-root`。
可以通过以下方式停止转换容器而无需删除输出：
```sh
make down
```
有关固定的解码器镜像、确切的重现性合同、各个管道门和故障排除，请参阅 [open-bots v3 README](https://github.com/audityourcontracts/open-bots/tree/main/v3)。
### 2. 构建或安装 livefire-mcp
从源代码检出构建：
```sh
cd /absolute/path/to/livefire-mcp
cargo build --locked --release -p livefire-mcp
```
要安装最新的私有发布版本，请通过 GitHub CLI 认证并运行发布安装程序，同时提供已完成的输出目录：
```sh
gh auth login
gh release download \
--repo audityourcontracts/livefire-mcp \
--pattern install-codex.sh \
--output - \
| bash -s -- \
--output-root /absolute/path/to/open-bots/v3/output
```
安装程序验证清单和 Parquet 快照，安装 `livefire-mcp` 和 `livefire-data` 二进制文件，并使用 `codex mcp add livefire -- ...` 将 `livefire` 注册到 Codex 中。源代码和二进制文件替代方案在下面有详细介绍。
### 3. 确认 Codex 可以看到工具
安装或更改 MCP 注册后，请退出并重新启动 Codex 客户端。Codex 拥有 stdio 子进程；不要将 `livefire-mcp` 留在另一个终端中运行。在 Codex 中，使用 `/mcp` 确认 `livefire` 暴露：
```text
database_info sql_schema sql_query
submit_flag list_flags finalize_flags
```
然后使用此最小提示：
```text
仅使用 livefire MCP 工具。调用 database_info 和 sql_schema，然后使用 sql_query 报告事件总数和前三个 sourcetypes。包括 dataset_sha256 和 sql_query 返回的 query_id。
```
对于已发布的快照，总共有 2,030,269 个事件，最大 sourcetypes 是 `syslog`、`stream:ip` 和 `osquery:results`。
## 构建
```sh
cargo build --locked --release -p livefire-mcp
```
这会生成两个二进制文件：
```text
target/release/livefire-mcp
target/release/livefire-data
```
### 从源代码运行 MCP
在开发过程中，Cargo 可以在单个命令中构建并启动 stdio 服务器：
```sh
cd /absolute/path/to/livefire-mcp
cargo run --locked --release -p livefire-mcp --bin livefire-mcp -- \
--output-root /absolute/path/to/open-bots/v3/output
```
该命令静默等待 stdin 上的 MCP 消息。这是预期的；MCP 客户端通常会启动它。
使用以下命令将此源代码命令注册到 Codex：
```sh
codex mcp add livefire -- \
cargo run --locked --release \
--manifest-path /absolute/path/to/livefire-mcp/Cargo.toml \
-p livefire-mcp --bin livefire-mcp -- \
--output-root /absolute/path/to/open-bots/v3/output
codex mcp get livefire
```
此路径在 Codex 启动服务器时需要 Rust 工具链。不要将单独的副本留在终端中运行：Codex 启动并拥有 stdio 服务器进程。
### 运行和注册已构建的二进制文件
在 `cargo build --release` 后，直接运行可执行文件：
```sh
/absolute/path/to/livefire-mcp/target/release/livefire-mcp \
--output-root /absolute/path/to/open-bots/v3/output
```
该进程静默等待 stdin 上的 MCP 消息。按 `Ctrl-C` 完成此手动启动检查；注册后，Codex 会自行启动二进制文件。
使用以下命令将该可执行文件注册到 Codex：
```sh
codex mcp add livefire -- \
/absolute/path/to/livefire-mcp/target/release/livefire-mcp \
--output-root /absolute/path/to/open-bots/v3/output
codex mcp get livefire
```
运行 `codex mcp remove livefire` 以替换现有的手动注册。下安装程序会自动执行此替换。
## 从发布版本安装到 Codex
该仓库是私有的，因此首先使用具有读取访问权限的帐户对 GitHub CLI 进行身份验证：
```sh
gh auth login
```
然后从最新版本下载安装程序并运行它。提供已完成的 open-bots v3 `output` 目录：
```sh
gh release download \
--repo audityourcontracts/livefire-mcp \
--pattern install-codex.sh \
--output - \
| bash -s -- \
--output-root /absolute/path/to/open-bots/v3/output
```
安装程序：
1. 为当前 macOS 或 Linux 架构选择发布存档；
2. 验证其 SHA-256 校验和；
3. 在 `~/.local/bin` 下安装 `livefire-mcp` 和 `livefire-data`；
4. 验证选定的 open-bots 清单和 Parquet 快照；
5. 使用 `codex mcp add livefire -- ...` 将 stdio 服务器注册到 `codex`；
6. 使用 `codex mcp get livefire` 确认结果。
现有的 `livefire` MCP 注册将被替换。如果注册失败，则恢复以前的 Codex 配置。使用安装程序标志选择特定的发布版本、目标或 MCP 名称：
```sh
--version v0.2.0
--install-dir /custom/bin
--name livefire-botsv3
--repo OWNER/REPO
```
发布资产为 arm64 和 x86-64 macOS 和 Linux 构建。当前不支持原生 Windows；请使用匹配的 Linux 版本的 WSL。
## 在 Codex 中测试已安装的 MCP
无需运行数据库守护进程，也无需设置两个终端。`livefire-data` 是一个一次性诊断 CLI，而 `livefire-mcp` 是 Codex 自动启动的 stdio 服务器。
首先，验证已安装的数据 CLI 可以打开并验证已完成的 open-bots 输出。此命令打印快照元数据并退出：
```sh
~/.local/bin/livefire-data \
--output-root /absolute/path/to/open-bots/v3/output \
info
```
然后验证 Codex 注册：
```sh
codex mcp get livefire
```
它应该报告一个启用的 `stdio` 服务器，其命令是 `~/.local/bin/livefire-mcp`，其 `--output-root` 参数指向相同的 open-bots 输出目录。
在安装或更改注册后重新加载 Codex：
- Codex CLI 或 TUI：退出正在运行的客户端并重新启动 `codex`；使用 `/mcp` 确认 `livefire` 是活动的。
- 桌面应用程序：打开 **设置 > MCP 服务器**，选择 **重启**，并启动新的聊天。
- IDE 扩展：打开其 MCP 服务器设置，选择 **重启扩展**，并启动新的聊天。
在从此源代码仓库重新构建已安装的二进制文件后，请通过退出正在运行的 Codex 客户端、替换可执行文件并重新启动 Codex 来刷新它。MCP 是 Codex 拥有的子进程；没有单独的刷新命令：
```sh
cd /absolute/path/to/livefire-mcp
cargo build --locked --release -p livefire-mcp
install -m 0755 target/release/livefire-mcp "$HOME/.local/bin/livefire-mcp"
codex mcp get livefire
codex
```
如果 Codex 注册的是 `cargo run`，请退出并重启 Codex；Cargo 在 Codex 再次启动 MCP 时会重建更改后的源代码。每个 MCP 进程在 `~/.local/share/livefire-mcp/hunts/` 下创建一个仅追加的狩猎账本。`database_info` 报告当前会话的精确 `hunt_id` 和 `ledger_path`。
在新会话中，使用此提示进行端到端工具测试：
```text
仅使用 livefire MCP 工具。调用 database_info 和 sql_query。报告总事件行数、dataset_sha256 和按计数排名的前三个 sourcetypes。说明使用了哪些 livefire 工具。
```
相同的测试可以从任何目录以非交互方式运行：
```sh
codex exec \
--ephemeral \
--skip-git-repo-check \
--sandbox read-only \
-C /tmp \
'仅使用 livefire MCP 工具。不要使用 shell、filesystem、web 或其他 MCP 服务器。调用 database_info 和 sql_query。报告总事件行数、dataset_sha256 和按计数排名的前三个 sourcetypes。说明使用了哪些 livefire 工具。'
```
对于当前的 BOTS v3 快照，验收结果是 2,030,269 个总事件，`syslog`、`stream:ip` 和 `osquery:results` 是前三个最大的 sourcetypes。如果 Parquet 快照发生变化，计数和摘要可能会发生变化。
维护人员还可以手动测试原始 MCP 协议并准确比较 MCP 和 CLI 结果：
```sh
cd /absolute/path/to/livefire-mcp
LIVEFIRE_MCP_BIN="$HOME/.local/bin/livefire-mcp" \
LIVEFIRE_DATA_BIN="$HOME/.local/bin/livefire-data" \
LIVEFIRE_OUTPUT_ROOT="/absolute/path/to/open-bots/v3/output" \
node tools/livefire-mcp-smoke.mjs
```
### 运行十个代理的 Codex 威胁狩猎
重启 Codex 并确认 `livefire` 出现在 `/mcp` 下后，将此提示粘贴到新的聊天中：
```text
仅使用 livefire MCP 工具和子代理编排控件。不要使用 shell、filesystem、web、apps 或其他 MCP 服务器。
作为根威胁狩猎负责人，首先调用 database_info 和 sql_schema。然后并行生成十个直接的子代理，每个代理负责一个独立的范围：
1. 身份验证滥用、帐户接管、特权更改和异常管理员。
2. 云 API、IAM、凭证、策略、区域和防御逃避活动。
3. 对象存储暴露、不安全的 ACL、秘密访问和可疑的读取/写入。
4. 网络、DNS、代理、信标、隧道扫描和命令和控制。
5. Web 漏洞利用：注入、遍历、上传滥用、利用工具和泄露。
6. 端点执行、LOLBins、持久性、服务、任务和防御损害。
7. 通过 SMB、SSH、RDP、远程管理员和凭证重用进行横向移动。
8. 收集、暂存、存档、不寻常的传输、上传和流出。
9. 加密货币挖矿、类似勒索软件的活动、破坏、欺诈和资源劫持。
10. 假设轻量级跨源时间线关联狩猎，用于其他人错过的链条。
在等待所有代理完成之前生成所有十个代理。每个子代理必须检查模式、查询事件关系并为它认为有物质支持的每个问题调用 submit_flag。散文不是提交。发现什么都不返回的代理返回明确的无发现结果而不提交标志。不要声称仅凭产品名称、端口、罕见事件或孤立警报就存在漏洞。
每个 submit_flag 调用都必须使用唯一的 client_submission_id、worker 的 agent_label 和 hunt_scope、支持的 server-issued query_ids、typed 指标、分类、严重性、0 到 100 的置信度、证据摘要和良性替代方案。submit_flag 记录未经验证的模型信念；它不验证正确性。不要仅凭产品名称、端口、罕见事件或孤立警报来声称漏洞。
在返回之前，每个工作线程必须包括 hunt_id、flag_id 和完整的 submit_flag 结果。等待所有十个收集这些结果，然后调用 list_flags。Codex 可以为每个子代理提供自己的 livefire MCP 进程，因此不要假设根列表包含工作线程标志。当工作线程标志属于另一个 hunt_id 时，请重新运行必要的 SQL，在根进程中提交一个新的协调员副本，使用新的根 query_ids、agent_label 为"root"，以及一个命名源工作线程 hunt_id 和 flag_id 的证据摘要。永远不要引用另一个 hunt 的 query_id。
交叉检查每个候选者，调用 list_flags，然后恰好调用 finalize_flags 一次，使用每个标志的决定：accepted、merged into an accepted canonical flag 或 rejected，每个都有一个原因。
呈现一份最终报告，包括执行摘要、按严重性和置信度排名的验证结果、详细的证据和可复制的 SQL、十行覆盖率矩阵、被拒绝或未解决的线索和方法限制。明确报告如果无法验证任何漏洞或妥协，请不要制造积极的结果。```
### 可选：从 CLI 强制执行仅 MCP 隔离
存储库中包含一个密封的多代理狩猎命令。它忽略了正常的 Codex 配置，禁用了 shell、网络搜索、应用程序、插件和钩子，并且只注入已安装的 `livefire-mcp` 服务器。Codex 的多代理控制工具保持启用，以便根代理可以运行十个直接的猎人并聚合他们的证据：
```sh
cd /绝对路径/to/livefire-mcp
./scripts/codex-hunt.sh /绝对路径/to/open-bots/v3/output
```
启动器默认使用 `~/.local/bin/livefire-mcp` 处的二进制文件，并为此次调用注入其 MCP 配置。它不依赖于全局 `codex mcp` 注册，因此不需要重启 Codex。设置 `LIVEFIRE_MCP_BIN` 以测试不同的二进制文件。
这十个范围涵盖了身份、云控制平面、存储暴露、网络命令和控制、网络利用、端点执行和持久性、横向移动、数据泄露、影响和跨源时间线狩猎。每个子代理都记录其自己的原始信念，带有 `submit_flag` 或者返回明确的无发现结果。根代理收集返回的提交，调用 `list_flags`，在必要时重新查询和导入跨账本候选，并使用 `finalize_flags` 在其协调器账本中密封接受、合并和拒绝的决定，然后呈现一个排名报告和一个十行的覆盖矩阵。
此运行可能会比单代理狩猎消耗更多的令牌。它设置 `agents.max_threads=11` 以供一个根代理和十个直接子代理使用，并使用 `agents.max_depth=1` 防止递归委托。
## 使用 CLI
将 `livefire-data` 指向 open-bots 的 `output` 目录，而不是直接指向其 `parquet` 子目录：
```sh
target/release/livefire-data \
--output-root /绝对路径/to/open-bots/v3/output \
info
target/release/livefire-data \
--output-root /绝对路径/to/open-bots/v3/output \
schema
target/release/livefire-data \
--output-root /绝对路径/to/open-bots/v3/output \
query \
--max-rows 20 \
--statement "SELECT sourcetype, count(*) AS events FROM events GROUP BY sourcetype ORDER BY events DESC LIMIT 20"
```
当此存储库和 `open-bots` 是相邻的 checkout 时，零参数默认值是 `../open-bots/v3/output`：
```sh
target/release/livefire-data info
```
`LIVEFIRE_OUTPUT_ROOT` 可以通过环境设置相同的路径。
## 运行 MCP 服务器
MCP 客户端启动服务器并通过 stdin/stdout 进行通信：
```sh
target/release/livefire-mcp \
--output-root /绝对路径/to/open-bots/v3/output
```
服务器公开了六种工具：
| 工具 | 输入 | 结果 |
| --- | --- | --- |
| `database_info` | `{}` | 数据集来源以及当前的狩猎 ID、账本路径和账本状态。 |
| `sql_schema` | `{}` | `events` 关系的有限列名和 DuckDB 类型。 |
| `sql_query` | `{"statement":"...","max_rows":100}` | 类型化行、查询 ID、保留的请求/结果摘要、快照和 SQL 摘要，以及截断状态。 |
| `submit_flag` | 带有证据的模型信念 | 追加一个原始的、未经验证的标志，绑定到保留的查询 ID。 |
| `list_flags` | `{}` | 列出每个原始标志、可复制的 SQL 引用、根决策和账本路径。 |
| `finalize_flags` | 每个原始标志的决策 | 密封接受、合并和拒绝的根决策，而不重写提交。 |
数据集和列表工具公开 `readOnlyHint=true`。`submit_flag` 和 `finalize_flags` 公开 `readOnlyHint=false`；两者都是有界的仅追加操作，具有幂等性键。每个工具都公开 `destructiveHint=false`、`idempotentHint=true` 和 `openWorldHint=false`。
标志被故意标记为 `model_submitted_unverified`。账本证明了模型提交了什么以及它引用的保留 SQL 调用，但它并不声称这些结果支持解释。正确性和证据质量是运行后的评估者决策。
### 标志生命周期
每个成功的 `sql_query` 都保留在当前的狩猎账本中，并返回一个服务器颁发的 `query_id`。标志必须引用同一个狩猎中的一个或多个查询 ID。服务器将确切的 SQL、行数、截断状态、SQL 摘要和结果摘要复制到仅追加的提交记录中，以便稍后审查不依赖于模型记住其查询输出。
典型的序列是：
1. 调用 `database_info` 并记录 `dataset_sha256`、`hunt_id` 和 `ledger_path`。
2. 调用 `sql_schema`，然后使用有限的 `sql_query` 调用进行调查。
3. 为每个有实质性支持的问题调用 `submit_flag`。代理响应中的散文不是提交。
4. 调用 `list_flags`，交叉检查和去重原始信念，并决定每个信念是接受、合并还是拒绝。
5. 调用 `finalize_flags` 恰好一次。终结密封该狩猎：不再接受后续的 SQL 查询或标志提交。
示例 `submit_flag` 输入在 `sql_query` 返回 `query-000001` 后：
```json
{
"client_submission_id": "storage-public-acl-1",
"agent_label": "storage-hunter",
"hunt_scope": "object-storage exposure",
"title": "S3 bucket granted public read and write",
"summary": "An IAM user granted the global AllUsers group READ and WRITE on the bucket.",
"classification": "exploitable_misconfiguration",
"severity": "high",
"confidence": 95,
"indicators": [
{"kind": "storage_resource", "value": "s3://example-bucket"},
{"kind": "responsible_identity", "value": "example-user"}
],
"query_ids": ["query-000001"],
"evidence_summary": "The cited CloudTrail row contains PutBucketAcl with AllUsers READ and WRITE.",
"alternative_explanation": "An approved temporary public collaboration bucket."
}
```
`client_submission_id` 是狩猎范围内的幂等键。重复相同的请求会返回原始标志；重用带有不同内容的键会被拒绝。成功的调用会返回一个 `flag_id`，例如 `flag-000001`，以及不可变的查询引用。
调用 `list_flags` 时带有 `{}`。结果包含当前狩猎中的所有原始标志、它们的查询来源、账本路径、状态和任何终结。
示例终结三个标志：
```json
{
"client_request_id": "root-finalization-1",
"decisions": [
{
"flag_id": "flag-000001",
"disposition": "accepted",
"canonical_flag_id": null,
"reason": "The retained control-plane event directly establishes public access."
},
{
"flag_id": "flag-000002",
"disposition": "merged",
"canonical_flag_id": "flag-000001",
"reason": "Duplicate observation of the same bucket and ACL change."
},
{
"flag_id": "flag-000003",
"disposition": "rejected",
"canonical_flag_id": null,
"reason": "The cited rows establish scanning but not successful exploitation."
}
]
}
```
终结必须包含该账本中每个标志的精确一个决策。合并的标志必须指向一个接受的规范标志；接受和拒绝的标志不能命名一个。
### 多代理账本范围
一个 `livefire-mcp` 进程拥有一个 `hunt_id` 和一个账本。一些 Codex 多代理配置为每个子代理启动一个单独的 MCP 进程。在这种情况下，每个工作者的 `submit_flag` 在其自己的账本中成功，但根代理的 `list_flags` 只列出根进程的标志；它不是一个跨账本聚合 API。
因此，工作者应该将 `hunt_id`、`flag_id` 和完整的 `submit_flag` 结果返回给协调器。根据当前的服务器，需要一个终结的账本的协调器必须交叉检查这些候选并在自己的狩猎中提交协调器副本，保留源工作者的 `hunt_id`/`flag_id` 在证据摘要中，然后调用 `finalize_flags`。原始工作者账本保持仅追加和未终结。始终根据 `hunt_id` 限定查询和标志 ID，因为在查看多个账本文件时，诸如 `query-000001` 等标识符是账本局部的。
### Codex
添加一个项目范围的 `.codex/config.toml`：
```toml
[mcp_servers.livefire]
command = "/绝对路径/to/livefire-mcp/target/release/livefire-mcp"
args = [
"--output-root", "/绝对路径/to/open-bots/v3/output",
]
enabled_tools = [
"database_info", "sql_schema", "sql_query",
"submit_flag", "list_flags", "finalize_flags",
]
default_tools_approval_mode = "writes"
startup_timeout_sec = 30
tool_timeout_sec = 70
required = true
```
### Hermes
将服务器添加到 `~/.hermes/config.yaml`：
```yaml
mcp_servers:
livefire:
command: "/绝对路径/to/livefire-mcp/target/release/livefire-mcp"
args:
- "--output-root"
- "/绝对路径/to/open-bots/v3/output"
supports_parallel_tool_calls: false
```
### Pi
Pi 可以从扩展调用 `livefire-data` 或使用诸如 `pi-mcp-adapter` 之类的 MCP 适配器。项目 `.mcp.json` 可以包含：
```json
{
"mcpServers": {
"livefire": {
"command": "/绝对路径/to/livefire-mcp/target/release/livefire-mcp",
"args": [
"--output-root", "/绝对路径/to/open-bots/v3/output"
],
"lifecycle": "lazy",
"directTools": [
"database_info", "sql_schema", "sql_query",
"submit_flag", "list_flags", "finalize_flags"
]
}
}
}
```
## 数据集绑定
直接 open-bots 模式在创建 `events` 视图之前验证完成的管道：
1. `validation.json` 必须报告匹配的青铜 SHA-256 和行数门控。
2. 事件地址必须唯一，无报告的重复项。
3. `parquet.json` 必须报告 `PASS`，其行数必须与验证匹配。
4. 发现的 Parquet 文件计数和字节总数必须与清单匹配。
5. 清单、Parquet 根和每个 Parquet 对象必须是所选输出根目录下的常规非符号链接路径。
6. 每个 Parquet 对象都被哈希成一个排序的物理快照绑定。
7. DuckDB 必须在服务器启动前重现清单行数。
`database_info` 公开两个不同的来源值：
- `bronze_sha256` 是由 open-bots 生成的稳定逻辑身份。
- `dataset_sha256` 绑定了此进程查询的确切物理 Parquet 文件。它可以在使用不同 PyArrow 或平台版本制作的等效 Parquet 构建之间更改。
对于单独发布的不可变快照，也提供高级目录模式：
```sh
target/release/livefire-mcp \
--catalogue /绝对路径/to/catalogue.json \
--data-root /绝对路径/to/parquet
```
目录模式检查其预期的 dataset 和对象摘要。 可选的 `--skip-object-verification` 标志仅在该模式下跳过预期的对象摘要检查；直接 open-bots 模式始终哈希文件，因为这些哈希定义了其快照。
## SQL 策略和限制
`sql_query` 接受一个确切的 DuckDB `SELECT` 或 `WITH ... SELECT` 语句，适用于暴露的关系。在执行之前，服务器使用 `sqlparser` 解析语句并拒绝：
- 变更、DDL、`COPY`、`ATTACH`、设置和堆叠语句；
- 未公开、动态选择或限定关系；
- 表函数和文件或网络读取器；
- `SELECT INTO`、锁定子句和 DuckDB `query`/`query_table` 转义。
授权的 AST 会再次呈现，并包装在服务器拥有的行限制中。主机还强制序列化输出和每个单元格的上限、查询超时和 DuckDB 中断、内存限制、线程限制和单个查询工作者门控。
DuckDB 配置为具有精确的 `allowed_paths`，没有允许的目录、禁用的扩展自动安装/自动加载、禁用的社区扩展和锁定的配置。数据集路径仅由操作员在进程启动时选择；模型作者的工具调用不能更改它们。
DuckDB 自身的安全指导将不受信任的 SQL 视为 shell 代码。AST 策略和 DuckDB 设置是纵深防御，而不是操作系统沙盒。对于敌对或多用户主体，请将服务器作为低权限用户运行或在数据集仅读入的容器中，并禁用网络访问。
## 资源选项
```text
--max-rows <ROWS> 默认值：100
--max-output-bytes <BYTES> 默认值：262144
--max-cell-bytes <BYTES> 默认值：32768
--query-timeout-seconds <SECONDS> 默认值：60
--memory-limit <DUCKDB_LIMIT> 默认值：512MB
--threads <THREADS> 默认值：2
--ledger-dir <DIRECTORY> 默认值：~/.local/share/livefire-mcp/hunts
```
调用 `livefire-mcp --help` 或 `livefire-data --help` 以获取完整的命令行界面。
## 开发
```sh
make check
make smoke OPEN_BOTS_OUTPUT=/绝对路径/to/open-bots/v3/output
```
`make smoke` 执行 MCP 初始化和工具发现握手，调用所有六种工具，并通过 MCP 和 CLI 运行相同的公共云存储证据查询。它提交一个原始标志，列出它，并终结一个接受的根决策。测试需要移除 MCP 保留标识符和波动的计时/输出大小字段后的确切查询结果一致性。它还验证耐用的 JSONL 事件，并且两个接口都拒绝本地文件读取器查询。
核心依赖项是：
- [`rmcp`](https://github.com/modelcontextprotocol/rust-sdk)，官方 Rust MCP SDK；
- [`duckdb`](https://github.com/duckdb/duckdb-rs)，嵌入 DuckDB 和 Parquet 支持；
- [`sqlparser`](https://github.com/apache/datafusion-sqlparser-rs)，用于 DuckDB 方言 AST 授权；
- `serde`、`schemars`、`sha2`、`clap` 和 `tokio` 用于合约、模式、快照绑定、配置和异步 MCP 调度。
## 存储库布局
```text
crates/data-host/ 数据集绑定、DuckDB、SQL 策略、限制、JSON 结果
crates/mcp-server/ stdio MCP 服务器和 livefire-data CLI
tools/ 协议和适配器一致性烟雾测试
```
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器