jocay/bolt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
a8d6dd4b87a6a31616d38e46aec7172c060faa16
bolt/README.md
T
jocay a8d6dd4b87 deploy: 站点探测不再强制 IPv4/IPv6 并加超时 
git.jocayn.qzz.io 在 Cloudflare 后面同时有 IPv4/IPv6 地址,部分网络(如 nas)IPv4 不通、
IPv6 可用;原来用 -4 强制 IPv4 且没有连接超时,会重试到卡死。改为由 curl 自动选择协议族,
探测 8 秒连接超时、15 秒总时长且不重试,下载加 15 秒连接超时。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 10:57:56 +08:00

233 lines
15 KiB
Markdown
Raw Blame History

# bolt — 极速单文件 MCP 命令执行服务器
让 AI(Claude Code / Claude Desktop / Cursor 等 MCP 客户端)通过 **MCP 协议**连接后,在服务器上执行 shell 命令、读写和传输文件。
- **单文件**:全部代码在 `src/main.rs`,仅依赖 `serde_json`(Unix 下加 `libc`);base64 / SHA-256 / HMAC 均为手写
- **零框架**:手写 JSON-RPC 2.0 + MCP 协议 + Streamable HTTP 服务器,无 async runtime、无重量级依赖
- **双传输**:`stdio`(本地 AI 客户端默认)与 `Streamable HTTP`(远程连接)
## 快速开始
```bash
cargo build --release # 产物: target/release/bolt (~1MB)
```
**本地模式(stdio)**:由 MCP 客户端拉起本进程
```bash
# Claude Code
claude mcp add --transport stdio bolt -- /abs/path/to/bolt
# 或通用 MCP 客户端配置
# {"mcpServers": {"bolt": {"command": "/abs/path/to/bolt"}}}
```
**远程模式(Streamable HTTP)**:AI 通过网络连接
```bash
bolt --http 127.0.0.1:8080 # 仅本机
bolt --http 0.0.0.0:8080 --token mysecret # 对外 + Bearer 认证
bolt --http 0.0.0.0:8080 --token mysecret --allow "git,docker,curl" --file-root /srv/data
# Claude Code 连接远程
claude mcp add --transport http bolt http://127.0.0.1:8080/mcp
```
## 工具
| 工具 | 说明 |
|---|---|
| `run_command` | 执行 shell 命令:完整 shell 语法(管道/重定向/`&&`)、`cwd`、`env`、`timeout_ms`(超时自动杀进程树)、`max_output_bytes`(输出截断防膨胀)、`shell=false` 直接执行二进制;客户端可传 `_meta.progressToken` 接收进度通知,支持 `notifications/cancelled` 取消 |
| `shell_open` | 开启持久化交互式 shell 会话(`cd`、环境变量等状态跨次保留),可指定 `shell`(sh/bash/zsh/fish)与 `cwd`;空闲 30 分钟自动回收 |
| `shell_write` | 向会话写入输入(自动补换行) |
| `shell_read` | 读取会话新输出,可阻塞等待(`timeout_ms`,0 = 等到会话退出),可被取消 |
| `shell_close` | 关闭并杀掉会话进程树 |
| `file_read` | 读取文件:UTF-8 文本按文本返回,图片按 image 返回,其余按 base64;`offset` + `length` 分块读取,不会切断多字节字符 |
| `file_write` | 写入文件:`overwrite`(默认,临时文件 + rename 原子替换,保留原权限)/ `create`(已存在则失败)/ `append`;`encoding=base64` 写二进制;`mkdirs` 自动建目录;返回 SHA-256 |
| `file_stat` | 文件信息(是否存在、类型、大小、修改时间、权限),可选计算 SHA-256 |
| `file_link` | 仅 HTTP 模式:生成带 HMAC 签名、限时有效的 `/files` 直传链接,并给出可在客户端本机执行的 `curl` 命令 |
所有工具结果都同时提供 `content` 与 `structuredContent`(`file_read` 为两块 `content`:元数据 JSON + 文件内容)。
`run_command` 返回:`exit_code` / `signal` / `timed_out` / `cancelled` / `detached` / `duration_ms` / `stdout` / `stderr` / 截断标志等。命令退出后若仍有后台进程占用输出管道(如 `python -m http.server &`),等待 300ms 后返回 `detached=true`,后台进程继续运行。
## 文件传输
MCP 工具的参数和结果都要经过模型上下文,所以分两层:
- **小文件**(配置、脚本、日志片段、截图):直接用 `file_read` / `file_write`,stdio 和 HTTP 都可用。
- **大文件**(HTTP 模式):数据走 `/files` 端点,不经过模型。
- AI 调用 `file_link` 拿到签名链接,在客户端本机执行返回的 `curl` 命令即可:
```bash
curl -fsSL -o ./backup.tar.gz 'http://host:8080/files?path=/srv/data/backup.tar.gz&exp=...&sig=...' # 下载
curl -fsS -T ./dataset.zip 'http://host:8080/files?path=/srv/data/dataset.zip&exp=...&sig=...&mode=overwrite&mkdirs=0' # 上传
```
- 也可以直接带 Bearer 令牌访问:`curl -H "Authorization: Bearer $T" -T f.bin "http://host:8080/files?path=/srv/data/f.bin&mkdirs=1"`。
- 支持 `Range` 断点续传(206)、`HEAD`、chunked 上传、`Expect: 100-continue`;上传同样是原子替换,失败不破坏原文件,响应里带 SHA-256。
- 签名覆盖方法、路径、写入模式和过期时间,链接只能用于签名时指定的那一个操作;签名密钥在进程启动时随机生成,重启后旧链接失效。
## 配置
CLI 参数(环境变量 `BOLT_*` 为回退):
| 参数 | 默认 | 说明 |
|---|---|---|
| `--http <addr>` | 无(stdio) | 启用 Streamable HTTP 监听地址,如 `127.0.0.1:8080`(`:8080` 等价于 `127.0.0.1:8080`) |
| `--token <t>` | 无 | HTTP 要求 `Authorization: Bearer <t>` |
| `--allow <a,b>` | 空 | 命令白名单(按程序名精确匹配;非空时 shell 模式禁止元字符) |
| `--deny <a,b>` | 空 | 命令黑名单(按程序名匹配命令中每一段,尽力而为) |
| `--timeout-ms <n>` | 30000 | 命令默认超时(工具参数可覆盖,0 = 无限) |
| `--cwd <dir>` | 当前 | 命令与相对文件路径的默认工作目录 |
| `--max-output <n>` | 1M | 单流输出捕获上限(支持 K/M/G) |
| `--allow-origin <url>` | localhost/127.0.0.1 | 额外允许的 HTTP Origin(防 DNS rebinding) |
| `--file-root <d1,d2>` | 不限 | 文件工具与 `/files` 只能访问这些目录;配置了 `--allow` 时必须设置,否则文件功能禁用 |
| `--max-upload <n>` | 2G | `PUT /files` 单次上传上限(支持 K/M/G) |
```bash
export BOLT_TOKEN=xxx BOLT_ALLOW="git,docker" BOLT_TIMEOUT_MS=60000 BOLT_FILE_ROOT=/srv/data
bolt --http 127.0.0.1:8080
```
## 协议实现(2025-06-18 规范)
- `initialize`(协议版本协商,支持 2024-11-05 / 2025-03-26 / 2025-06-18)、`ping`、`tools/list`、`tools/call`、`shutdown`
- `notifications/initialized`、`notifications/cancelled`、`notifications/exit`(仅 stdio 生效)、`notifications/progress`(进度上报)
- 工具执行错误以 `isError: true` 返回;协议错误返回标准 JSON-RPC 错误码(-32601/-32602/-32700 等)
- Streamable HTTP:
- `initialize` 时签发 `Mcp-Session-Id`;携带该头的请求按会话隔离 shell 会话与取消,未知/过期 ID 返回 404,`DELETE /mcp` 终止会话并清理其资源;不带该头的客户端共用一个匿名作用域(兼容无状态客户端)
- POST:通知 → 202;请求 → JSON 或 SSE。`Accept` 含 `text/event-stream` 的 `tools/call` 会在同一个 SSE 响应里先推进度通知、最后推结果
- GET:长连接 SSE 流(接收本会话的服务器通知 + 10s 心跳)
- 支持 chunked 请求体、CORS、Origin 校验、Bearer 认证
## 性能与资源
- 复用缓冲区,输出计数用原子操作,进度推送不占主循环;stdio 每个工具调用一个工作线程,HTTP 每个连接一个线程
- 子进程独占进程组(`setpgid`),超时/取消按进程组 `SIGKILL`,连带杀掉整棵进程树,无僵尸
- 上限:并发工具调用 128、HTTP 连接 512、shell 会话 64(空闲 30 分钟回收)、MCP 会话 1024(空闲 24 小时回收)
- 实测(本机,含 Python 客户端逐字节 I/O 开销):
- ping 往返吞吐 ≈ **14,700 msg/s**
- 并发 `echo` 命令平均 **4.7 ms/次**(进程 spawn + 捕获输出)
- 构建配置:`lto = "fat"`、`codegen-units = 1`、`strip = true`
## 测试
```bash
cargo test --release # 单元测试(策略/编码与摘要/HTTP 解析/文件读写与目录限制/会话缓冲/执行引擎等)
cargo test --release test_files # 只跑某一个
```
端到端测试脚本在 `docs/`(需要 Unix 主机;二进制路径默认 `target/release/bolt`,可用 `BOLT_BIN` 指定):
```bash
python3 docs/bolt_stdio_test.py # stdio 端到端
python3 docs/bolt_http_test.py # HTTP 端到端(含 Mcp-Session-Id、/files、签名链接)
```
## 安全说明
- 默认只接受本机连接(`127.0.0.1`),对外公开需显式 `0.0.0.0` + `--token`(未设置时启动日志会警告)
- 该服务器等于远程 root shell 入口,务必配置认证后再暴露公网
- 白名单(`--allow`):按程序名精确匹配,shell 模式下禁止 `; & | $ \` < > ( ) { }` 和换行,防止 `git status; rm -rf ~` 这类串联绕过;`shell_write` 写入的每一行同样受检。注意白名单内的程序如果自身能执行任意命令(`sh`、`env`、`docker`、`find -exec`、`git -c ...`),白名单就约束不了它
- 黑名单(`--deny`):检查命令每一段的程序名(去掉路径、引号、转义和前置的 `VAR=x`),但仍可能被包装命令绕过,只适合防误操作
- 文件功能等同于任意写文件(可写 `authorized_keys`、crontab),所以配置白名单时必须用 `--file-root` 限定目录,否则文件功能自动禁用;路径会解析符号链接并拒绝 `..` 逃逸
- 不同 MCP 会话之间的 shell 会话与取消相互隔离;HTTP 客户端无法通过 `notifications/exit` 关停服务
- Unix 下命令在独立进程组运行,取消/超时会连带杀掉子进程;收到 SIGINT/SIGTERM(Windows 为 Ctrl+C)时先清理全部子进程再退出
## 平台
- Linux / macOS(完整功能:进程组杀、信号处理)
- Windows(基础功能:`cmd /C`、`taskkill /T` 杀进程树、Ctrl+C 清理退出)
## 在其他设备上部署(一键脚本)
脚本支持 Linux(systemd)和 macOS(launchd),自动识别 amd64 / arm64(Apple Silicon 即使在 Rosetta 终端中也优先选择 arm64),需要 root 权限。仓库公开,无需令牌;IPv4 网络用 `git.jocayn.qzz.io`,IPv6 网络用 `git.draws.qzz.io`(脚本下载二进制时先试 `git.jocayn.qzz.io`、不通再试 `git.draws.qzz.io`,协议族由 curl 自动选择,探测超时 15 秒)。
| 操作 | IPv4 | IPv6 |
|---|---|---|
| 安装 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh \| sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh \| sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌` |
| 更新 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh \| sudo sh` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh \| sudo sh` |
| 卸载 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh \| sudo sh` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh \| sudo sh` |
- **安装**(`install.sh`):下载 Release 上最新版本的 `bolt-<平台>-<架构>` 附件(有 `SHA256SUMS` 附件时自动校验)→ 装到 `/usr/local/bin` → 写配置与服务 → 开机自启 → 启动。已安装的设备会拒绝执行,避免按新参数重写配置时丢掉令牌;确实要重装加 `--reinstall`。
- **更新**(`update.sh`):只替换二进制并重启服务,**保留现有配置**;已是最新版本时直接跳过,不会自动降级。新版本服务起不来时自动回滚到旧版本(旧版本备份在 `/usr/local/bin/bolt.bak`)。重启由独立进程完成,所以通过 bolt 自身执行更新也安全(只是本次调用的连接会断开)。
- `--version v0.2.0` 安装指定版本,`--binary ./bolt` 使用本地二进制,`--force` 同版本也重装
- **卸载**(`uninstall.sh`):停止并删除服务、二进制和备份;默认同时删除配置与日志,加 `--keep-config` 保留。
- 环境变量:`BOLT_GIT_HOST` 指定下载站点,`BOLT_VERSION` 指定版本,`BOLT_DL_URL` 直接指定二进制地址,`BOLT_DL_TOKEN` 用于私有仓库下载。
传参写在 `sh -s --` 之后,例如:
```bash
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sudo sh -s -- \
--http 0.0.0.0:8080 --token 你的令牌 --allow "git,docker" --file-root /srv/data
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh | sudo sh -s -- --version v0.2.0
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh | sudo sh -s -- --keep-config
```
安装参数(全部可选):
| 参数 | 含义 |
|---|---|
| `--http <addr>` | 监听地址,默认 `127.0.0.1:8080`;对外用 `0.0.0.0:8080` |
| `--token <t>` | Bearer 认证令牌(公网必填) |
| `--allow <a,b>` / `--deny <a,b>` | 命令白/黑名单 |
| `--timeout-ms <n>` | 默认命令超时 |
| `--file-root <d1,d2>` | 文件功能允许访问的目录(配置 `--allow` 时必填,否则文件功能禁用) |
| `--max-upload <n>` | `PUT /files` 单次上传上限(默认 2G) |
| `--binary <路径或URL>` | 跳过 Release 下载,用本地二进制(如 `scp` 过去的)或指定 URL |
| `--version <tag>` | 安装指定版本(默认最新) |
| `--reinstall` | 已安装时按本次参数重写配置 |
| `--no-start` / `--no-enable` | 只安装不启动 / 不设开机自启 |
### 发布新版本
在 Gitea 上新建 Release(tag 如 `v0.2.0`),上传附件 `bolt-linux-amd64`、`bolt-darwin-arm64`(以及需要的其他平台)和 `SHA256SUMS`(`sha256sum bolt-* > SHA256SUMS`)。脚本按 `/api/v1/repos/jocay/bolt/releases/latest` 识别最新版本,发布后各设备执行更新命令即可。
Linux 附件建议用 `cargo zigbuild --release --target x86_64-unknown-linux-gnu.2.28` 编译(只依赖 glibc 2.28,Debian 10 及以上都能运行);macOS 附件用 `cargo zigbuild --release --target aarch64-apple-darwin` 交叉编译,脚本安装时会在缺少签名时自动补 ad-hoc 签名。
### macOS(launchd)
脚本会创建以 root 运行的 launchd 系统服务 `io.jocay.bolt`。配置保存在 `/Library/Application Support/bolt/io.jocay.bolt.plist`,包含监听地址、认证令牌、命令规则和超时;启用开机自启时,脚本还会复制到 `/Library/LaunchDaemons/io.jocay.bolt.plist`。两份配置均仅 root 可读写。
`--no-enable` 只保留手动启动配置,取消本服务的开机配置,仍可立即启动;`--no-start` 本次不加载服务,已运行的本服务也会卸载,下次开机是否启动由 `--no-enable` 决定。两个参数可一起使用。
```bash
# 查看服务 / 重启已加载的服务 / 停止并卸载
sudo launchctl print system/io.jocay.bolt
sudo launchctl kickstart -k system/io.jocay.bolt
sudo launchctl bootout system/io.jocay.bolt
# 停止后或使用 --no-start 安装后,手动加载并启动
sudo launchctl bootstrap system '/Library/Application Support/bolt/io.jocay.bolt.plist'
# 查看日志
sudo tail -f /var/log/bolt/stdout.log /var/log/bolt/stderr.log
```
macOS 服务的工作目录为 `/var/root`,PATH 包含 `/opt/homebrew/bin` 和 `/opt/homebrew/sbin`,不会加载个人 shell 配置。
## systemd 服务部署(手动)
仓库内 `deploy/` 提供现成的部署文件:
```bash
sudo install -m 0755 target/release/bolt /usr/local/bin/bolt
sudo cp deploy/bolt.service /etc/systemd/system/
sudo cp deploy/bolt.env.example /etc/bolt.env # 按需修改(监听地址在 service 文件 ExecStart)
sudo systemctl daemon-reload
sudo systemctl enable --now bolt # 开机自启 + 立即启动
```
常用管理命令:
```bash
systemctl status bolt # 查看状态
systemctl restart bolt # 重启(改完配置后)
systemctl stop bolt # 停止
systemctl disable bolt # 取消开机自启
journalctl -u bolt -f # 实时查看日志
```
特性:崩溃自动重启(`Restart=on-failure`,2 秒间隔)、优雅停机(SIGTERM 时杀掉所有子进程树)、日志进 journald、`LimitNOFILE=65536`。默认监听 `127.0.0.1:8080`,对外暴露前务必在 `/etc/bolt.env` 设置 `BOLT_TOKEN`。
Reference in New Issue View Git Blame Copy Permalink